Call Control APIs
Last updated
Last updated
This section describes the Call Control API portion of the PortSIP PBX and provides guidance for developers building 3rd applications. You can use this API to write agent applications that provide a variety of call-related features, from agent state management and call control to supervisor monitoring and call recording.
Before calling the REST API to make the call, and control the call, we need to authenticate with the PortSIP PBX to obtain the access_token. Please refer to the .
GET /sessions/directly
Use the GET method to initiate a call directly. This API does not require an access_token. Some hardware is not programmable and only allows pasting the URL to initiate the call. This API is designed for that purpose.
Example
URL Parameters
extension_number
An extension number
password
The extension password is used by the PBX for authentication instead of the access_token. (required)
caller
The caller number, it's can be either an extension number or a PSTN number. (required)
callee
The callee number, it's can be either an extension number or a PSTN number. (required)
domain
The sip domain of the tenant. (required)
send_sdp
Include the SDP in the INVITE message to initiate the call, true or false. (required)
caller_display_name
Specify the display name for caller. (optional)
trunk
This is a trunk name used to indicate that this call should be routed through the specified trunk. If the specified trunk is not available, the call will fail.(optional)
rewrite_from
Specify when to send this call to the trunk. Use rewrite_from to rewrite the user of the From header in the INVITE message. Usually use this to set the outbound caller ID for the outbound call.(optional)
rewrite_pai
Specify when to send this call to the trunk. Use rewrite_pai to rewrite the user of the P-Asserted-Identity header in the INVITE message. (optional)
rewrite_rpi
Specify when to send this call to the trunk. Use rewrite_rpi to rewrite the user of the Remote-Party-ID header in the INVITE message. (optional)
user_data
Use this key to pass the additional information to the call. This information will be stored in the CDR, allowing you to easily track and analyze the call.(optional)
additional_header
Specifies whether to add an additional SIP header (RFC 5373) to the INVITE SIP message. The possible values are:
ANSWER_MODE: Adds the Answer-Mode header to the INVITE SIP message.
CALL_INFO: Adds the Call-Info header with answer-after=0 to the INVITE SIP message.
ALERT_INFO_AUTO_ANSWER_DELAY0: Adds the Alert-Info header with info=alert-autoanswer;delay=0 to the INVITE SIP message.
ALERT_INFO_AUTO_ANSWER: Adds the Alert-Info header with info=Auto Answer to the INVITE SIP message.
ALERT_INFO_INTERCOM: Adds the Alert-Info header with info=intercom to the INVITE SIP message.
(optional)
header_direction
Specifies which party of the call should receive the additional_header. If the additional_header is not specified, this parameter will be ignored. The possible values are:
CALLER: Adds the specified header in additional_header to the INVITE SIP message sent to the caller.
CALLEE: Adds the specified header in additional_header to the INVITE SIP message sent to the callee.
ALL: Adds the specified header in additional_header to the INVITE SIP messages sent to both the caller and callee.
(optional)
Response
POST /sessions
Use this REST API to initiate a call, the access_token is required for this API.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
caller
string
The caller number, it's can be either an extension number or a PSTN number. (required)
callee
string
The callee number, it's can be either an extension number or a PSTN number. (required)
send_sdp
boolean
Include the SDP in the INVITE message to initiate the call, true or false. (required)
caller_display_name
Specify the display name for caller. (optional)
trunk
string
This is a trunk name used to indicate that this call should be routed through the specified trunk. If the specified trunk is not available, the call will fail.(optional)
rewrite_from
string
Age of the user
rewrite_pai
string
Specify when to send this call to the trunk. Use rewrite_pai to rewrite the user of the P-Asserted-Identity header in the INVITE message. (optional)
rewrite_rpi
Specify when to send this call to the trunk. Use rewrite_rpi to rewrite the user of the Remote-Party-ID header in the INVITE message. (optional)
user_data
string
Use this key to pass the additional information to the call. This information will be stored in the CDR, allowing you to easily track and analyze the call.(optional)
additional_header
string enum
Specifies whether to add an additional SIP header (RFC 5373) to the INVITE SIP message. The possible values are:
ANSWER_MODE: Adds the Answer-Mode header to the INVITE SIP message.
CALL_INFO: Adds the Call-Info header with answer-after=0 to the INVITE SIP message.
ALERT_INFO_AUTO_ANSWER_DELAY0: Adds the Alert-Info header with info=alert-autoanswer;delay=0 to the INVITE SIP message.
ALERT_INFO_AUTO_ANSWER: Adds the Alert-Info header with info=Auto Answer to the INVITE SIP message.
ALERT_INFO_INTERCOM: Adds the Alert-Info header with info=intercom to the INVITE SIP message.
(optional)
additional_header
string enum.
Specifies which party of the call should receive the additional_header. If the additional_header is not specified, this parameter will be ignored. The possible values are:
CALLER: Adds the specified header in additional_header to the INVITE SIP message sent to the caller.
CALLEE: Adds the specified header in additional_header to the INVITE SIP message sent to the callee.
ALL: Adds the specified header in additional_header to the INVITE SIP messages sent to both the caller and callee.
(optional)
Example of the body
Response
POST /sessions/{id}/destroy
Use this API to hang up a call by specifying the session ID. Pass the call session ID to the URL parameter ID.
Example
Headers
Content-Type
application/json
Authorization
Bearer <token>
Response
POST /sessions/{id}/hold
Use this API to hold a call by specifying the session ID. Pass the call session ID to the URL parameter ID.
Example
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
extension_number
string
The extension_number can be either a PortSIP PBX extension number or a PSTN number. Since a call can have multiple call legs, if this parameter is specified, the PBX will match the call leg by extension_number and session ID, then perform the hold on the matched call leg. If the ID parameter in the URL is set to 1, the hold will be performed on the last call associated with this extension_number. (required)
Response
POST /sessions/{id}/unhold
Use this API to unhold a call by specifying the session ID. Pass the call session ID to the URL parameter ID.
Example
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
extension_number
string
The extension_number can be either a PortSIP PBX extension number or a PSTN number. Since a call can have multiple call legs, if this parameter is specified, the PBX will match the call leg by extension_number and session ID, then perform the unhold on the matched call leg. If the ID parameter in the URL is set to 1, the unhold will be performed on the last call associated with this extension_number. (required)
Response
POST /sessions/{id}/refer
Use this API to blind transfer a call by specifying the session ID. Pass the call session ID to the URL parameter ID.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
extension_number
string
To transfer a call to a specific refer_to number, you need to specify the extension_number, it's can be either a PortSIP PBX extension number or a PSTN number. If the ID parameter in the URL is set to 1, the last call associated with that extension_number will be transferred. (required)
refer_to
string
The target number to which the call will be transferred. (required)
Example
1001 has established a call. Use the following body payload to blind transfer extension 1001 to the number 0033187691:
Response
POST /sessions/{id}/attended_refer
Use this API to attended transfer a call by specifying the session ID. Pass the current call session ID to the URL parameter ID.
Consider this scenario: Extension 1001 establishes calls with both 1002 and 1003. Now, use this API to perform an attended transfer, which will connect the call between 1002 and 1003, and extension 1001 will be disconnected from the calls.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
extension_number
string
To do attended transfer, you need to specify the extension_numberfor select the transffer, it's can be either a PortSIP PBX extension number or a PSTN number (required)
session_1
string
The session ID of the call which will be transffered. The PBX will match the call leg by both extension_number and this specified session ID. This parameter can be set as "0".
refer_to_1
string
If the session_1 is specified as 0, then the PBX will use the extension_number and this refer_to_1 to match the call leg. This parameter can be set as a empty string. If the session_1 is "0" and refer_to_1 is empty, this API will fail.
session_2
string
The session ID of the call which will be transffered. The PBX will match the call leg by both extension_number and this specified session ID. This parameter can be set as "0".
refer_to_2
string
If the session_2 is specified as 0, then the PBX will use the extension_number and this refer_to_2 to match the call leg. This parameter can be set as a empty string. If the session_2 is "0" and refer_to_2 is empty, this API will fail.
Example
Extension 1001 establishes calls with both 1002 and 1003. Now, use this API to perform an attended transfer, which will connect the call between 1002 and 1003, and extension 1001 will be disconnected from the calls.
Response