API Interface

VoIPSUN PBX provides a simple HTTP API for initiating calls (click2call), terminating calls, displaying active calls, and managing the call center. Additional features can be customized to meet client requirements.

Authentication

All API requests require:

• username — API user credentials (configured in Settings → HTTP API Users)
• password — authentication password

Call Operations

Originate Action

Initiates a new call — first dials the selected extension, then connects to the destination number.

Parameters:

Parameter	Description
action	originate
dstNum	Destination phone number
srcExtenPublicNum	Public number of the source extension (use only one of the src* parameters)
srcExtenInternalNum	Internal number of the source extension
srcExtenId	Source extension ID
srcSipUsername	SIP username of the source extension
dialplanName	Required if multiple extensions share the same internal number
customCDR1-4	Optional custom fields in the CDR record
dialerCid, dialerName	Custom CallerID
monitorFilename, monitorPath	Call recording configuration
checkExten, checkIpHost, checkIpContact	Extension availability verification

Example request:

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=originate&srcExtenInternalNum=100&dstNum=800123456

Dial Action

Routes calls through predefined outbound routing contexts.

Parameters:

Parameter	Description
action	dial
outrouteName or outrouteId	Outbound routing selection
context	Required Asterisk dialplan context
hangupContext	Optional context on call failure

Example request:

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=dial&dstNum=800123456&outrouteName=outgoing&context=processing

Call Termination

Terminates an active call by channel name.

Parameters:

Parameter	Description
action	hangupcall
channelName	Channel identifier from the active calls list

Example request:

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=hangupcall&channelName=SIP/5555-0000b704

Call Monitoring

Active Calls List

Returns a JSON list of ongoing calls with channel names, duration, status, and identifiers.

Parameters:

Parameter	Description
action	listcalls

JSON response fields:

Field	Description
channelName	Channel identifier
context	Dialplan context
src, dst	Source and destination number
duration	Call duration in seconds
status	Connection status (Up)
accountCode	Account identifier

Call Spying

Initiates monitoring of active calls by connecting a supervisor to listen.

Parameters:

Parameter	Description
action	spying
srcExtenPublicNum / srcExtenInternalNum / srcExtenId / srcSipUsername	Supervisor source extension (only one)
dstExtenPublicNum / dstExtenInternalNum / dstExtenId / dstSipUsername / dstChannelName	Target call (only one)
spyCid, spyName	Supervisor CallerID

Caution

Use only one parameter from each group (src*, dst*), otherwise the system will return error 300/301.

SIP Channel Status

Parameters:

Parameter	Description
action	sipstatus

Response fields:

Field	Description
user	SIP username
host	Registration IP address
status	Connection status (OK, UNKNOWN, Unmonitored)
useragent	Device information
regcontact	Registration contact address

Call Center Agent Management

Agent Login

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=agentlogin&srcExtenInternalNum=100&agentNumber=1000&agentPin=1234

Parameters:

Parameter	Description
action	agentlogin
agentNumber	Agent identifier
agentPin	Authentication PIN

Agent Logout

Parameter	Description
action	agentlogout
agentNumber, agentPin	Agent identification

Pause / Unpause

Parameter	Description
action	agentpause or agentunpause
agentNumber, agentPin	Agent identification

Add to Queue

Parameter	Description
action	agentadd
queueName	Queue identifier
penalty	Priority level

Remove from Queue

Parameter	Description
action	agentremove
queueName	Queue identifier

Agent Status

Returns agent status: logged in/logged out, available/busy/in call/on hold/unavailable.

Parameter	Description
action	agentstatus
agentNumber, agentPin	Agent identification

Queue Status

Provides complete queue metrics including agent details, wait times, service levels, and waiting callers.

Parameter	Description
action	queuestatus
queueName	Target queue

Recording Management

Move Recording

Moves and optionally renames a call recording.

Parameter	Description
action	moverecord
cdrId	CDR record identifier
filename	New file name (optional)
path	Target directory (optional, at least one of filename/path is required)

Example request:

http://IP_PBX/api/api.php?username=voipsun&password=secretpwd&action=moverecord&cdrId=10000&filename=record.wav&path=/archive/2024

Error Codes

General Errors

Code	Description
100	Unauthorized user or insufficient permissions
110	Unknown action parameter
120	Missing required parameters

Originate Errors (200–228)

Code	Description
200	Conflicting extension selection parameters
201–203	Extension, dialplan, or configuration not found
210–211	IP address mismatch
220–228	Extension unavailability states (unavailable, busy, ringing, etc.)

Dial Errors (250)

Code	Description
250	Outbound routing not found

Spying Errors (300–312)

Code	Description
300	Conflicting source parameters
301	Conflicting destination parameters
302–304	Source extension/dialplan issues
310–312	Destination extension/dialplan issues

Agent Errors (500–636)

Code	Description
500–504	Agent authentication or extension lookup
550	Logout authentication failure
580, 590	Pause/unpause authentication failure
600–601	Queue management failure
610–636	Agent status and availability verification errors

Recording Errors (800–812)

Code	Description
800	CDR record not found
801	No recording data in CDR
810–812	File permission or access issues

JSON Response Format

Successful response:

{"success":"true"}

Error response:

{"success":"false","errno":"100","reason":"Unauthorized user or bad permissions"}