Skip to end of metadata
Go to start of metadata

The REST APIs in this section are used to control communications in the system.

  • Call Control
  • Voicemail

Starting with V14.10, the following functionality canbe viewed or modified through the Dial Plan API.

Call Control

The SipXcallController is a RESTful service for third party call control. It is bundled as a JAR package file format and is loaded by the sipXrest container on initialization. It is invoked by the HTTP methods GET and POST to a specific URL.
The sipXrest service can run on any node in the cluster, but this is transparent for the end-user because end-user will always make the REST call to sipXconfig (admin node). SipXconfig is the only container that knows where sipXrest is running, and will route the call accordingly.
The SipXcallController implements a third party call controller. The third party call controller works by either sending an INVITE to the calling party and subsequently sending that calling party a REFER to transfer the call to the called party (fire and forget) or by staying in the call path using the call flow 4 of RFC 3725.
The latter method allows subsequent control of the call such as being able to transfer the call after call setup.
The call controller tracks the state of the call in progress for a specified period of time after the call is placed and provides this status for query by applications.
When the operation is invoked from a node inside the cluster, no pin is required, and no certificate (HTTP protocol is used). For communication inside the cluster data encryption is optional and configurable from UI. Otherwise, a pin must be supplied for the operation to succeed and also a certificate must be accepted (HTTPS protocol is used). The security model for these operations is enforced by the sipXconfig container, that contains the most complex security layer including BASIC or DIGEST authentication schemes, LDAP authentication, HTTP secured (HTTPS). On the back scenes we proxy call controller calls through sipXconfig, and then sipXconfig will route the call on the host where sipXrest service is running.
Services
If you are issuing the cURL command from a node inside cluster please use only HTTP (no authentication is required) and the hostname is the node where sipXrest is running
From outside cluster you must authenticate the curl command with Basic, Digest authentication or perform LDAP authentication
You can use only HTTPS when issuing the curl command from outside the cluster
For calls issued from outside the cluster, only sipXconfig (admin) port and hostname are used (port 443, the standard HTTPS port)
The URI is as follows: /my/redirect<callcontroller URI>

Query call progress

Resource URI: callcontroller/{callingUser}/{calledUser}
Default Resource Properties: N/A
URL Parameters:

Property

Description

sipMethod

The SIP request method used. Available methods are:

  • Refer - Asks recipient to issue SIP request (call transfer.)
  • Invite - Indicates a client is being invited to participate in a call session.
    Default is Refer.

action

The action to be performed. Options are

  • Call – Place a call
  • Transfer – Transfer a call
    Default is Call.

target

The target user for the call transfer. If an ongoing call exists, the call is transferred to the target user. This is meaningful only if the call was previously started using the Invite SIP method.

timeout

The time measured in seconds for which the calling party is alerted before pickup. If the calling party does not pickup in that time period, the call is aborted.

agent

The user name of the agent that is placing the third party call. This defaults to the calling user.

subject

The subject of the call. Determines what goes into the SIP subject header of the initial call setup invite.

isForwardingAllowed

Determines is forwarding is allowed. Values are

  • True
  • False
    Default is false whether or not forwarding is allowed for the initial invite.

resultCacheTime

The amount of time measured in seconds progress cache record are kept in memory.

Status Values: N/A
Specific Response Codes:
HTTP Method: POST
Initiates a call from the callingUser to the calledUser
Return Values: N/A
Unsupported HTTP Method: GET, PUT, DELETE

View ongoing calls

Resource URI: callcontroller/{callingUser}/{calledUser}
Default Resource Properties: N/A
URL Parameters: All URL parameters are ignored. Note that you an only get the current call state of you have previously initiated the call from callingUser to calledUser.
Status Values: N/A
Specific Response Codes:
HTTP Method: GET
Get the current call state for any ongoing call between callingUser and calledUser.
Return Values: N/A
Unsupported HTTP Method: POST, PUT, DELETE

Examples

Initiating a call from a remote host
From inside cluster:
curl -k -X POST http://<callcontroller_node_host>:6667/callcontroller/{callingUser}/{calledUser}?timeout=<seconds>
From outside cluster:
curl -k -X POST -u {callingUser}:{pin} https://<web_admin_host>/sipxconfig/rest/my/redirect/callcontroller/{callingUser}/{calledUser}?timeout=<seconds>
Initiating a call as third party
From inside cluster:
curl -k -X POST http://<callcontroller_node_host>:6667/callcontroller/<callingUser>/<calleedUser>?agent=<agentName>
From outside cluster:
curl -k -X POST -u {agent}:{agentPin} https://<web_admin_host>/sipxconfig/rest/my/redirect/callcontroller/<callingUser>/<calleedUser>?agent=<agentName>
Initiating a call between user1 and user2 when user1 is the calling party
From inside cluster:
curl -k -X POST http://sipxtest.sipxtest.net:6667/callcontroller/user1/user2
From outside cluster:
curl -k -X POST -u user1:123 https://sipxtest.sipxtest.net/sipxconfig/rest/my/redirect/callcontroller/user1/user2
Iitiating a call between user1 and user2 when user3 is a third party agent.
From inside cluster:
curl -k -X POST http://sipxtest.sipxtest.net:6667/callcontroller/user1/user2?agent=user3
From outside cluster:
curl -k -X POST -u user3:123 https://sipxtest.sipxtest.net/sipxconfig/rest/my/redirect/callcontroller/user1/user2?agent=user3
Similar to "place a call", the query can be made either from calling party. The URL is exactly the same as that you would use when placing the call but the method is GET.
Here is an example of how to query call setup progress for call between user1 and user2 as user1.
From inside cluster:
curl -k http://sipxtest.sipxtest.net:6667/callcontroller/user1/user2
From outside cluster:
curl -k -u user1:123 https://sipxtest.sipxtest.net/sipxconfig/rest/my/redirect/callcontroller/user1/user2
Querying call progress setup
Here is an example of how to query call setup progress for call between user1 and user2 via agent user3 from the internal cluster, with no password required:
curl -k http://sipxtest.sipxtest.net:6667/callcontroller/user1/user2?agent=user3
Here is an example of how to query call setup progress for call between user1 and user2 via agent user3 from the openUC external cluster:
curl -k -u user3:123 -X GET https://sipxtest.sipxtest.net/sipxconfig/rest/my/redirect/callcontroller/user1/user2?agent=user3
Return result from the query above
If the transfer is invoked using the Refer SIP method, the calling party records the Notify bodies and reports it (interpreted) when the user issues an HTTP GET to retrieve the call status. This is reported to the caller when the GET method is performed as shown below:
<status-lines xmlns="http://www.sipfoundry.org/sipX/schema/xml/call-status-00-00">
<status>
<timestamp>1259114103662</timestamp>
<call-id>7959e447b88502416ee2477f3d36a480@12.23.34.45</call-id>
<method>INVITE</method>
<status-line>SIP/2.0 100 Trying</status-line>
</status>
<status>
<timestamp>1259114103667</timestamp>
<call-id>7959e447b88502416ee2477f3d36a480@12.23.34.45</call-id>
<method>INVITE</method>
<status-line>SIP/2.0 407 Proxy Authentication Required</status-line>
</status>
<status>
<timestamp>1259114103678</timestamp>
<call-id>7959e447b88502416ee2477f3d36a480@12.23.34.45</call-id>
<method>INVITE</method>
<status-line>SIP/2.0 100 Trying</status-line>
</status>
<status>
<timestamp>1259114103841</timestamp>
<call-id>7959e447b88502416ee2477f3d36a480@12.23.34.45</call-id>
<method>INVITE</method>
<status-line>SIP/2.0 180 Ringing</status-line>
</status>
</status-lines>

Voicemail

View or modify mailbox MWI

Resource URI: /mwi
Default Resource Properties: N/A
Specific Response Codes: N/A
HTTP Method: GET
Returns the MWI status for this mailbox in RFC-3842 format. The content type is set to application/simple-message-summary.
Example: N/A
HTTP Method: PUT
Updates the MWI for this mailbox.
Unsupported HTTP Method: GET, POST, DELETE

View all messages

Resource URI: /messages
Default Resource Properties
The resource is represented by the following properties when the GET request is performed:

Property

Description

message id

Unique identification number of the message.

heard

Displays False if the message has not been heard and True it it has already been heard..

urgent

Displays False if the message has not been flagged as urgent and True if it is flagged as urgent.

folder

The folder where the message is located. Options are: Inbox, Saved, Deleted.

duration

The duration of the call.

contentLength

 

received

 

author

The name of the caller

authorExtension

The extension of the caller.

username

The username of the caller.

format

Format type of the audio file.

Status Values:
Specific Response Codes:
HTTP Method: GET
Returns all messages in mailbox.
Examples: XML format only
<messages>
<message id="100001038" heard="false" urgent="false" folder="inbox" duration="10" contentlength="20880" received="1387567094000" author="2014" authorExtension="2014" username="2011" format="mp3"/>
<message id="100001037" heard="false" urgent="false" folder="inbox" duration="10" contentlength="20736" received="1387566754000" author="2014" authorExtension="2014" username="2011" format="mp3"/>
<message id="100001036" heard="false" urgent="false" folder="inbox" duration="10" contentlength="20880" received="1387566688000" author="2014" authorExtension="2014" username="2011" format="mp3"/>
</messages>
cURL command to retrieve all messages:
$curl --digest -k --request GET https://200:123@<admin_host>/sipxconfig/rest/my/redirect/mailbox/200/messages
<message id=00000018 heard=true urgent=false folder=deleted duration=0 received=1171062204000/>
Unsupported HTTP Method: PUT, POST, DELETE

View or modify the Heard message status

Resource URI: /message/{messageid}/heard
Default Resource Properties
The resource is represented by the following properties when the GET request is performed:

Property

Description

heard

Displays False if the message has not been heard and True it it has been heard..

Specific Response Codes: N/A
HTTP Method: GET
Retrieves information on user with the specified ID
Example: XML format
<heard>true|false</heard>
HTTP Method: PUT
Marks the message heard and updates MWI. A message with no body is required.
Example: To mark User 200's message 00000080 as heard
$curl --digest -k --request PUT https://200:123@<admin_host>/sipxconfig/rest/my/redirect/mailbox/200/message/00000080/heard
HTTP Method: DELETE
Marks the message unheard and updates the MWI.
Unsupported HTTP Method: POST

Delete messages

Resource URI: /message/{messageid}/delete
Default Resource Properties: N/A
Specific Response Codes: N/A
HTTP Method: PUT
Moves the message to Trash folder. A message with no body is required.
Unsupported HTTP Method: GET, POST, DELETE

Update message subject

Resource URI: /message/{messageid}/subject
Default Resource Properties: N/A
Specific Response Codes: N/A
HTTP Method: PUT
Updates message subject given input stream. A message with a body is required.
Unsupported HTTP Method: GET, POST, DELETE

Move messages in folders

Resource URI: /message/{messageid}/move/{folder}
Default Resource Properties: N/A
Specific Response Codes: N/A
HTTP Method: PUT
Moves the specified message into the desired folder.
Unsupported HTTP Method: GET, POST, DELETE

Mailbox active greeting

Resource URI: /preferences/activegreeting
Default Resource Properties
The resource is represented by the following properties when the GET request is performed:

Property

Description

activeGreeting

Values can be None, Standard, Out of office or Extended absence.

Specific Response Codes: N/A
HTTP Method: GET
returns the active greeting (returns above fragment)
Example: XML format
<activegreeting>{standard}\</activegreeting>
User 200's active greeting preference
$curl --digest -k --request GET https://200:123@<admin_host>/sipxconfig/rest/my/redirect/mailbox/200/preferences/activegreeting
standard
TP Method: PUT
Set an active greeting. You can set the Value to None, Standard, Out of office or Extended absence.
Example:
<activegreeting>{value}\</activegreeting>
HTTP Method: DELETE
Sets the active greeting to None.
Unsupported HTTP Method: POST

View call ID

Resource URI: /uuid
Default Resource Properties
The resource is represented by the following properties when the GET request is performed:

Property

Description

 

 

Specific Response Codes: N/A
HTTP Method: GET
Returns the call ID of the original call.
Unsupported HTTP Method: PUT, POST, DELETE

View messages in Inbox folder

Resource URI: /inbox
Default Resource Properties
The resource is represented by the following properties when the GET request is performed:

Property

Description

 

 

Specific Response Codes: N/A
HTTP Method: GET
Retrieves all the voice mail messages in the Inbox folder.
Unsupported HTTP Method: PUT, POST, DELETE

View messages in Saved folder

Resource URI: /saved
Default Resource Properties
The resource is represented by the following properties when the GET request is performed:

Property

Description

 

 

Specific Response Codes: N/A
HTTP Method: GET
Returns all messages contained in the "saved" folder.
Unsupported HTTP Method: PUT, POST, DELETE

View messages in Deleted folder

Resource URI: /deleted
Default Resource Properties
The resource is represented by the following properties when the GET request is performed:

Property

Description

 

 

Specific Response Codes:
HTTP Method: GET
Returns all messages contained in the "deleted" folder.
Unsupported HTTP Method: PUT, POST, DELETE

View messages in Conference folder

Resource URI: /conference
Default Resource Properties
The resource is represented by the following properties when the GET request is performed:

Property

Description

 

 

Specific Response Codes:
HTTP Method: GET
Returns all messages contained in the Conference folder.
Unsupported HTTP Method: PUT, POST, DELETE




Dial plan

  1. Available in 14 starting with 14.10

View or modify dialing rules

  1. Available in 14 starting with 14.10
  2. Resource URI: /rules/{ruleId}
  3. Default Resource Properties:
  4. The resource is represented by the following properties when the GET request is performed:
    1. Property
    1. Description
    1. id
    1. name

     

    1. enabeled

     

    1. type

     

    1. description

     

    1. permissions

     

    1. hatewayAware

     

    1. authorizationChecked

     

    1. internal

     

    1. pstnPrefixOptional

     

    1. longDistancePrefixOptional

     

    1. externalLen

     

    1. optionalPrefix

     

    1. emergencyNumber

     

    1. afterHoursAttendantEnabled

     

    1. enableLiveAttendant

     

  5. Specific Response Codes: N/A
  6. HTTP Method: GET
  7. View the description for the specified schedule ID.
        1. Example: XML format
  8. <Rules>
  9. <Rule>
  10. <id>1</id>
  11. <name>Emergency</name>
  12. <enabled>false</enabled>
  13. <type>Emergency</type>
  14. <description>Emergency dialing plan</description>
  15. <permissions />
  16. <gatewayAware>true</gatewayAware>
  17. <authorizationChecked>true</authorizationChecked>
  18. <internal>false</internal>
  19. <pstnPrefixOptional>false</pstnPrefixOptional>
  20. <longDistancePrefixOptional>false</longDistancePrefixOptional>
  21. <externalLen>0</externalLen>
  22. <optionalPrefix>9</optionalPrefix>
  23. <emergencyNumber>911</emergencyNumber>
  24. <afterHoursAttendantEnabled>false</afterHoursAttendantEnabled>
  25. <enableLiveAttendant>false</enableLiveAttendant>
  26. </Rule>
  27. <Rule>
  28. <id>2</id>
  29. <name>International</name>
  30. <enabled>false</enabled>
  31. <type>Long_Distance</type>
  32. <description>International dialing</description>
  33. <permissions />
  34. <gatewayAware>true</gatewayAware>
  35. <authorizationChecked>true</authorizationChecked>
  36. <internal>false</internal>
  37. <pstnPrefix />
  38. <pstnPrefixOptional>false</pstnPrefixOptional>
  39. <longDistancePrefix>011</longDistancePrefix>
  40. <longDistancePrefixOptional>false</longDistancePrefixOptional>
  41. <areaCodes />
  42. <externalLen>-1</externalLen>
  43. <afterHoursAttendantEnabled>false</afterHoursAttendantEnabled>
  44. <enableLiveAttendant>false</enableLiveAttendant>
  45. </Rule>
  46. </Rules>
    1. JSON format

{

rules: [8]


0: {
id: 1
name: "Emergency"
enabled: false
type: "Emergency"
description: "Emergency dialing plan"
scheduleId: null
permissions: {

names: [0]


}-
gatewayAware: true
authorizationChecked: true
internal: false
mediaServerHostname: null
mediaServerType: null
dialPatterns: null
callPattern: null
pstnPrefix: null
pstnPrefixOptional: false
longDistancePrefix: null
longDistancePrefixOptional: false
areaCodes: null
externalLen: 0
optionalPrefix: "9"
emergencyNumber: "911"
afterHoursAttendant: null
afterHoursAttendantEnabled: false
holidayAttendant: null
workingTimeAttendant: null
holidayAttendantPeriods: null
workingTimeAttendantPeriods: null
extension: null
attendantAliases: null
did: null
enableLiveAttendant: false
}-
1: {
id: 2
name: "International"
enabled: false
type: "Long_Distance"
description: "International dialing"
scheduleId: null
permissions: {

names: [0]


}-
gatewayAware: true
authorizationChecked: true
internal: false
mediaServerHostname: null
mediaServerType: null
dialPatterns: null
callPattern: null
pstnPrefix: ""
pstnPrefixOptional: false
longDistancePrefix: "011"
longDistancePrefixOptional: false
areaCodes: ""
externalLen: -1
optionalPrefix: null
emergencyNumber: null
afterHoursAttendant: null
afterHoursAttendantEnabled: false
holidayAttendant: null
workingTimeAttendant: null
holidayAttendantPeriods: null
workingTimeAttendantPeriods: null
extension: null
attendantAliases: null
did: null
enableLiveAttendant: false
}-
2: {
id: 3
name: "Local"
enabled: false
type: "Long_Distance"
description: "Local dialing"
scheduleId: null
permissions: {

names: [0]


}-
gatewayAware: true
authorizationChecked: true
internal: false
mediaServerHostname: null
mediaServerType: null
dialPatterns: null
callPattern: null
pstnPrefix: "9"
pstnPrefixOptional: false
longDistancePrefix: ""
longDistancePrefixOptional: true
areaCodes: ""
externalLen: 7
optionalPrefix: null
emergencyNumber: null
afterHoursAttendant: null
afterHoursAttendantEnabled: false
holidayAttendant: null
workingTimeAttendant: null
holidayAttendantPeriods: null
workingTimeAttendantPeriods: null
extension: null
attendantAliases: null
did: null
enableLiveAttendant: false
}
}

  1. HTTP Method: PUT
  2. Update the description for the specified rule.
  3. HTTP Method: POST
  4. Create a new rule.
  5. HTTP Method: DELETE
      1. Delete the specified rule.
  6. Unsupported HTTP Method: N/A
  • No labels