Call Control APIs

This section describes the Call Control API portion of the PortSIP PBX REST API 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.

Authentication

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 REST API.

Initiate a call directly

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

/api/sessions/directly?extension_number=1001&password=A1s2d3f4&caller=1001&callee=1002&domain=test.io&send_sdp=true

URL Parameters

Name	Value
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

200

{
    "id": "884757570370146304"
}

Initiate a call

POST /sessions

Use this REST API to initiate a call, the access_token is required for this API.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
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

{
"caller" : "1001",
"callee" : "1002",
 "send_sdp" : true
}

Response

200

{
    "id": "884757570370146304"
}

Hang up a call

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

/api/sessions/884761305393664000/destroy

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Response

200

Hold a call

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

/api/sessions/884761305393664000/hold

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
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

200

Unhold a call

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

/api/sessions/884761305393664000/unhold

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
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

200

Blind transfer a call

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. In the URL parameter, you can specify the {id} as 1 means do not need to match the call.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
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 1:

1001 has established a call. Use the following body payload to blind transfer extension 1001 to the number 0033187691.

1. Pass 1 for the URL parameter {id}

2. Use the below POST body

Note: If the sessionId is specified as 1 in the URL parameter {id} and extension 1001 has multiple established calls, the PBX will automatically select the most recently established call and perform the transfer.

{
"extension_number" : "1001",
"refer_to" : "0033187691"
}

Example 2:

Extension 1001 has multiple active calls. To blind transfer the call with session ID 111222 from extension 1001 to the number 0033187691, use the following POST request:

• Set the URL parameter {id} to 111222

• Use the following POST body:

{
"extension_number" : "1001",
"refer_to" : "0033187691"
}

Response

200

400

Attended transfer a call

POST /sessions/{id}/attended_refer

Use this API to attend transfer a call by specifying the session ID. Pass the 1 as 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

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
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 is optional, or 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 is optional, or 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 1:

Extension 1001 establishes a call with 1002, the session ID is 111111, and establishes a call with 1003, the session ID is 222222. 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 call.

• Pass 1 for the URL parameter {id}

• Use the following POST body:

{
"extension_number" : "1001",
"refer_to_1" : "1002",
"session_1" : "111111",
"refer_to_2" : "1003",
"session_2" : "222222"
}

Example 2:

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 call.

• Pass 1 for the URL parameter {id}

• Use the following POST body:

{
"extension_number" : "1001",
"refer_to_1" : "1002",
"refer_to_2" : "1003"
}

Response

200

400