Call and Session Control

Session Initiation

Outbound Call From Application

Why is it called Outbound Call From Application?

In Cloudonix, every session is governed by a Voice Application. From the voice application's point of view, when an outbound call is created, it MUST connect to a voice application. This voice application may be provided as an application, url or even and embedded cxml.

POST /calls/<domain-name-or-id>/application

This call is used by a customer application backend to have a voice application initiate a call to a subscriber or another destination. The resulting session will have the application as the caller and the specified destination as the callee.

The call will first be setup as if a <Dial> verb was invoked with the provided destination as its <Number> noun, which will be resolved to a call to a subscriber or a call through the border according to the normal rules. Once the destination has answered, DTMF tones will be played as per the send-digits request field (if specified) then the specified voice application will be executed as if the destination has called that application. The voice application may perform any relevant action, including <Dial> verbs to dial to other destinations.

Conditions

This is a privileged API and requires system administrator, tenant administrator, or domain administrator authorization for the specified domain. When the server receives a call with lesser authorization it must return a 401 (“Unauthorized”) HTTP error response and stop processing.

Request

Mandatory Data Fields

URL Data Fields

The following data field must be provided in the request URL:

Field	Description
domain-name-or-id	The Cloudonix domain name or Cloudonix domain ID in which the specified subscriber is registered and in which to route the call.

JSON Body Data Fields

The following data fields must be provided in a JSON document sent in the request body:

Field	Description
destination	The destination number to which the voice application is to be connected to.
caller-id	The caller identification number to be send to the destination of the call. If not specified, no caller identification number will be sent.
send-digits	list of DTMF signals to be sent to the destination, after the call is answered and before executing the application. Must be a string composed of only the characters 0 through 9, *, # or the character w to specify a half-second delay. If not specified, no DTMF signals will be sent before executing the application.
application	The Cloudonix voice application name or numeric ID of the voice application to execute when the call is connected. Either this field, the url field, or the cxml field must be set.
url	An HTTP or HTTPS URL to a CXML application to execute when the call is connected. Either this field, the application field, or the cxml field must be set.
cxml	(also twiml for backward compatibility) - A static CXML application code to execute when the call is connected. Either this field, the application field, or the cxml field must be set.

Optional Data Fields

The following data fields are optional:

Field	Description
callback	A URL to be called with the session status changes. Whenever additional session data changes (after the initial creation) the API.Core will send a POST request to that URL with the session object (the same as being returned in this call’s response).
send-digits	list of DTMF signals to be sent to the destination, after the call is answered and before executing the application. Must be a string composed of only the characters 0 through 9, *, # or the character w to specify a half-second delay. If not specified, no DTMF signals will be sent before executing the application.
profile	JSON Object containing properties to set on the session profile of the created session.
routes	A routing plan for the outbound application call, as a JSON object according to the LCR API. If not specified, all active outbound trunks will be tried in creation order.
timeout	Number of seconds to wait for the destination to answer before canceling the call. The default value is 60.
execute	One of connected: execute the application when the destination answers the call (the default), or immediately: execute the application when the destination is ringing.
schedule	If an ISO-8601 formatted time stamp is set in this field, the call will be scheduled to start at the specified time instead of immediately.
record	Whether to record the outbound call, can be a boolean value or the text "true" to enable recording.
recordingStatusCallback	URL to send the recording status events to, in case recording was enabled.
recordingStatusCallbackMethod	The HTTP method to use when sending recording status events to the recordingStatusCallback URL, defaults to POST.
recordingStatusCallbackEvent	List of recording status events to be sent to the recordingStatusCallback URL, contains any of in-progress, completed and absent. Defaults to completed.
trim	whether to trim silence from the recording, one of trim-silence or do-not-trim, defaults to trim-silence.
trunk	(also byoc for backward compatibility) - route the outbound call through the specified outbound trunk, or one of the list of trunks. See <Dial>'s trunks attribute for an explanation of the acceptable values.
timeLimit	maximum time for the call, in seconds, after which a call in progress will be forcefully disconnected. If not set, defaults to the time limit specified for the domain.
machineDetection	detect answering machines, one of Enable or DetectMessageEnd. See Answering Machine Detection below for further details.
machineDetectionTimeout	Timeout in seconds for answering machine detection (see below for details).
machineDetectionSpeechThreshold	Minimal time, in milliseconds, for the answering machine greeting (see below for details).
machineDetectionSpeechEndThreshold	Minimal time to detect the answering machine greeting end (see below for details).
machineDetectionSilenceTimeout	maximum time to wait after answer, before detecting any speech, to give up on the answering machine detection (see below for details).
asyncAmd	should answering machine detection be performed in the background while the application is already running.
asyncAmdStatusCallback	URL to be invoked with answering machine detection results for background answering machine detection.
asyncAmdStatusCallbackMethod	The HTTP method to be used when calling the asyncAmdStatusCallback URL, defaults to POST.
deadline	if set to an ISO-8601 time stamp, if the call has not started by that time - the call will be rejected with an error.

Response

If the request is successful, the server will respond with an HTTP 200 (“OK”) response with the content type “application/json” containing a JSON document with the created session.

Example

Request

POST /calls/example.com/application
Host: api.cloudonix.io
Authorization: bearer XI1234567890
Content-Type: application/json

{
  "destination": "63121233333",
  "caller-id": "972547340014",
  "application": 15
}

Response

HTTP/1.1 200 OK
{
  "domainId": 3,
  "subscriberId": 372,
  "destination": "63121233333",
  "direction": "outbound-api",
  "token": "16a7294c989b11e7b3d32b9edb8660c7"
}

Answering Machine Detection

Answering machine detection is offered on outbound application calls to allow the application to have a different behavior for a called human vs. if an answering machine has answered. The detection system can be run in blocking mode or in asynchronous mode.

To enable the answering machine detection system, set the machineDetection field to either Enable or DetectMessageEnd: when set to Enable the detection algorithm will end as soon as it made a positive determination about the nature of the callee, while in DetectMessageEnd, if the detection algorithm has determined the callee is an answering machine, it will wait until the answering machine greeting has completed, and a few seconds after that, to make sure the application s run on the recording stage of the answering machine.

In the default blocking mode, the answering machine detection runs as soon as the call is answered. The application for the call starts only after detection is complete. If the application is set up as a URL or a Cloudonix application (configured in Cloudonix Cockpit), the application’s URL will be triggered with the AnsweredBy field showing the detection result (more details below).

The asynchronous mode starts by setting the asyncAmd field to true and providing an asyncAmdStatusCallback URL. With these settings, the application runs right away when the call is answered (like normal, without answering machine detection). The results of the answering machine detection are then sent to the specified callback URL.

Additional configuration

The following fields in the Outbound Call from Application request can be used to fine tune the answering machine detection algorithm:

Field	Description	Accepted Values	Default Value
machineDetectionTimeout	If the answering machine detection system had not made a determination within that many _seconds, the result will be unknown.	Between 3 and 59	30
machineDetectionSpeechThreshold	The minimal greeting length, in milliseconds, that an answering machine is expected to use. If the first speech period detected is shorter than that, the detection algorithm may cause the result to be human.	Between 1000 and 6000	2400
machineDetectionSpeechEndThreshold	The minimal time, in milliseconds, after the end of the speech, to make sure that the answering machine greeting had ended. When machineDetection is set to DetectMessageEnd, the machine_end_silence result will be delayed by this duration.	Between 500 and 5000	1200
machineDetectionSilenceTimeout	The maximum time, in milliseconds, to wait for speech after the call has been answered. If no speech is detected in that time, the result will be unknown.	Between 2000 and 10000	5000

Answering Machine Detection Results

The possible results of then answering machine detection system will change depending on the value of the machineDetection field was set to:

• Enable : The possible results are: human, machine_start, or unknown
• DetectMessageEnd : The possible results are: human, machine_end_beep, machine_end_silence, machine_end_other, human, fax, or unknown

If the asyncAmd field was set, any and all results may be submitted, one after the other, at any time until the answering machine detection algorithm has ended. For each result, the asyncAmdStatusCallback URL will be called - with all the fields as per the Voice Application Request specification, with the addition of the field AnsweredBy that is set to the result (final or interim) of the answering machine detection algorithm. If the asyncAmd field is not set, the answering machine detection algorithm result will be sent in the additional AnsweredBy field in the Voice Application Request that starts the application - if the application was not specified as inlined CXML code in the Outbound Call from Application request.

The meaning of the possible results is as follows:

Result	Description
human	The callee is presumed to be a human. This is a final result and no additional results are to be expected by the asyncAmd status callback.
machine_start	The callee is presumed to be an answering machine that have just started its greeting. When machineDetection is set to Enable, this is a final result and no additional results are to be expected by the asyncAmd status callback.
machine_end_beep	The callee is presumed to be an answering machine, and the greeting's end "beep" sound was detected.
machine_end_silence	The callee is presumed to be an answering machine, and the machineDetectionSpeechEndThreshold time was exceeded, after the last detected speech. This is a final result and no additional results are to be expected by the asyncAmd status callback.
machine_end_other	The callee is presumed to be an answering machine, and machine is expected to tbe in the recording stage, as determined by the algorithm. This is a final result and no additional results are to be expected by the asyncAmd status callback.
unknown	The answering machine detection algorithm could not make a determination as to the nature of the callee, likely due to no speech detected during the specified maximum wait time. This is a final result and no additional results are to be expected by the asyncAmd status callback.

Note:

If either the sendDigits is set, or if the execute field is set to something other than connected - the answering machine detection will be disabled and any answering machine detection specific settings will be ignored, and an error message will be logged.

Pre-Dial Session Initiation - Outgoing

POST /calls/<domain-name-or-id>/outgoing/<subscriber-msisdn>

This call is used by a subscriber application backend service to authorize a subscriber for Registration-Free Dialing™ outgoing call. The token generated by the response can then used for SIP dialing without the UA needing to register first and without providing SIP credentials.

The API call may include a routing plan, in which case the Cloudonix VoIP stack will act on the provided routing plan. Otherwise Cloudonix will use a different routing plan based on the domain configuration, either a default routing plan or to use the LCR module configured for the domain.

Conditions

This is a privileged API and requires system administrator, tenant administrator, or domain administrator authorization for the specified domain. When the server receives a call with lesser authorization it must return a 401 (“Unauthorized”) HTTP error response and stop processing.

Request

The following data field must be provided in the request URL:

Field	Description
domain-name-or-id	The domain name or Cloudonix domain ID in which the specified subscriber is registered and in which to route the call.
subscriber-msisdn	The E164 MSISDN number of the subscriber for which to generate the session token.

The following data field must be provided in a JSON document sent in the request body:

Field	Description
destination	The destination number to which the subscriber is going to dial.

The following data field may be provided in a JSON document sent in the request body:

Field	Description
routing	The routing plan for the call in JSON format according to the LCR API.
timeLimit	The maximum time to allow for the call specified, in seconds. After that time has passed in the call, Cloudonix Voice Application Service will disconnect the call automatically.
callback	A URL to be called with the session status changes. Whenever additional session data changes (after the initial creation) the API.Core will send a POST request to that URL with the session object (the same as being returned in this call’s response).

Response

If the request is successful, the server will respond with an HTTP 200 (“OK”) response with the content type “application/json” containing a JSON document with the generated session token.

If the request is for a subscriber that does not exist, the server will respond with an HTTP error 404 (“Not Found”) response.

Example

POST /calls/example.com/outgoing/972547340014
Host: api.cloudonix.io
Authorization: bearer XI1234567890
Content-Type: application/json

{
  "destination": "63121233333",
  "timeLimit": 7205,
  "routing": {
    "sellrate": 0.02,
    "sellrate_mimimum": 60,
    "sellrate_increment": 60,
    "route": [
      {
        "provider_id": 1,
        "rate_id": 302,
        "cx_trunk_id": 101,
        "offer_id": 1,
        "termination_ip": "187.33.22.44:5060",
        "termination_number": "2828#63121233333",
        "buyrate": 0.012,
        "buyrate_minimum": 1,
        "buyrate_increment": 1
      },
      {
        "provider_id": 1,
        "rate_id": 302,
        "cx_trunk_id": 102,
        "offer_id": 1,
        "termination_ip": "187.33.22.45:5060",
        "termination_number": "2828#63121233333",
        "buyrate": 0.012,
        "buyrate_minimum": 1,
        "buyrate_increment": 1
      }
    ]
  }
}

HTTP/1.1 200 OK

{
  "domainId": 3,
  "subscriberId": 372,
  "destination": "63121233333",
  "direction": "outgoing",
  "token": "16a7294c989b11e7b3d32b9edb8660c7",
  "timeLimit": 7205
}

Session Control

Update Time Limit

PATCH /calls/<domain-name-or-id>/sessions/<token>
PATCH /calls/<domain-name-or-id>/outgoing/<subscriber-msisdn>/<token>
PATCH /calls/<domain-name-or-id>/incoming/<subscriber-msisdn>/<token>

This call is used by an application backend to change the parameters of an outgoing call session in progress.

Conditions

This is a privileged API and requires system administrator, tenant administrator, domain administrator or an application authorization for the specified domain. When the server receives a call with lesser authorization it must return a 401 (“Unauthorized”) HTTP error response and stop processing.

Request

The following data field must be provided in the request URL:

Field	Description
domain-name-or-id	The domain name or Cloudonix domain ID in which the specified subscriber is registered and in which to route the call.
token	The session token for the session that will be updated.

The following data field must be provided in the request URL when using the “outgoing” call:

Field	Description
subscriber-msisdn	The E164 MSISDN of the subscriber this session is originating from.

The following data field must be provided in the request URL when using the “incoming” call:

Field	Description
subscriber-msisdn	The E164 MSISDN of the subscriber this session is terminating to.

The following data field may be provided in a JSON document sent in the request body:

Field	Description
timeLimit	An updated session time limit, in seconds, to apply to the session.
callStartTime	Set the call start timestamp if it wasn’t set already. May be used by the call routing application to update an incoming call session data.

Response

If the request is successful, the server will respond with an HTTP 200 (“OK”) response with the content type “application/json” containing a JSON document with the session details.

If the request is for a session token that doesn’t exist, the server will respond with an HTTP error 404 (“Not Found”) response.

Example

PATCH /calls/example.com/outgoing/972547340014/16a7294c989b11e7b3d…
Host: api.cloudonix.io
Authorization: bearer XI1234567890
Content-Type: application/json

{
  "timeLimit": 60
}

HTTP/1.1 200 OK

{
  "domainId": 3,
  "subscriberId": 372,
  "destination": "63121233333",
  "direction": "outgoing",
  "token": "16a7294c989b11e7b3d32b9edb8660c7",
  "timeLimit": 60
}

Ringing Notification

This call is used by an MUA receiving a call to notify the API.Core that it started ringing and to wait for confirmation on pickup or disconnect. This API call is intended to be used for long polling and is expected to wait for a pickup event or a cancel event, which may take a long time - thus it is recommended that client set a request timeout of at least 5 minutes.

GET /calls/<domain-name-or-id>/ringing/<msisdn>/<token>

Conditions

This is an unprivileged API and does not require any authorization. Access control is ensured by forcing the caller to know a valid session token and the destination subscriber’s MSISDN for that session.

Request

The following data fields must be provided in the URL of the request:

Field	Description
domain-name-or-id	The domain name or Cloudonix domain ID in which the specified session is registered.
msisdn	The E164 MSISDN of the subscriber this session is terminating to.
token	The session token for the session to be notified.

Response

If the request is successful the server will respond with either a 200 (“OK”) HTTP response if the session was picked up or a 205 (“Reset Content”) HTTP response if the session was disconnected by the caller before it was picked up by calee. In either case the response will have the application/json content type and contain a JSON document describing the status of the session.

The response JSON document will contain the following fields:

Field	Type	Description
status	String	The session status description.

Response Error Conditions

HTTP Error 403

If any of the below conditions isn't met, the server will respond with a 403 (“Forbidden”) HTTP error:

• The session status must be either “new” or “ringing”
• The terminating subscriber is active (i.e. not disabled in the Cloudonix platform)

HTTP Error 404

If any of the below conditions isn't met, the server will respond with a 404 (“Not Found”) HTTP error:

• The session token is valid for the domain
• The session token is valid for the recipient MSISDN specified for the request

Example

GET /calls/example.com/ringing/972547340014/16a7294c989b11e7 HTTP/1.1
Host: api.cloudonix.io

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ringing"
}

Get Session

GET /calls/<domain-name-or-id>/sessions/<token>
GET /calls/<domain-name-or-id>/outgoing/<msisdn>/<token>
GET /calls/<domain-name-or-id>/incoming/<msisdn>/<token>

This call is used by Cloudonix services to lookup session data, but can also be used by application backends to recall session data.

Conditions

This is a privileged API and requires system administrator, tenant administrator, domain administrator or an application authorization for the specified domain. When the server receives a call with lesser authorization it must return a 401 (“Unauthorized”) HTTP error response and stop processing.

Request

The following data fields must be provided in the request URL:

Field	Description
domain-name-or-id	The domain name or Cloudonix domain ID in which the specified session is registered.
token	The session token for the session to be retrieved.

The following data field must be provided in the request URL when using the “outgoing” call:

Field	Description
subscriber-msisdn	The E164 MSISDN of the subscriber this session is originating from.

The following data field must be provided in the request URL when using the “incoming” call:

Field	Description
subscriber-msisdn	The E164 MSISDN of the subscriber this session is terminating to.

Response

If the request is successful, the server will respond with an HTTP 200 (“OK”) response with the content type “application/json” containing a JSON document with the session details.

If the request is for a session that does not exist, or is not of the correct type or with the correct MSISDN (for the relevant calls) the server will respond with an HTTP error 404 (“Not Found”) response.

Example

GET /calls/example.com/sessions/16a7294c989b11e7b3d32b9edb8660c7
Host: api.cloudonix.io
Authorization: bearer XI1234567890

HTTP/1.1 200 OK

{
  "domainId": 3,
  "subscriberId": 372,
  "remote": "63121233333",
  "direction": "outgoing",
  "token": "16a7294c989b11e7b3d32b9edb8660c7",
  "timeLimit": 7205,
  "routing": {
    "sellrate": 0.02,
    "sellrate_mimimum": 60,
    "sellrate_increment": 60,
    "routes": [
      {
        "provider_id": 1,
        "rate_id": 302,
        "cx_trunk_id": 101,
        "offer_id": 1,
        "termination_ip": "187.33.22.44:5060",
        "termination_number": "2828#63121233333",
        "buyrate": 0.012,
        "buyrate_minimum": 1,
        "buyrate_increment": 1
      },
      {
        "provider_id": 1,
        "rate_id": 302,
        "cx_trunk_id": 102,
        "offer_id": 1,
        "termination_ip": "187.33.22.45:5060",
        "termination_number": "2828#63121233333",
        "buyrate": 0.012,
        "buyrate_minimum": 1,
        "buyrate_increment": 1
      }
    ]
  }
}

List Sessions

GET /calls/<domain-name-or-id>/sessions

This call is used by an application backend to enumerate ongoing sessions.

Conditions

This is a privileged API and requires system administrator, tenant administrator, domain administrator or an application authorization for the specified domain. When the server receives a call with lesser authorization it must return a 401 (“Unauthorized”) HTTP error response and stop processing.

Request

The following data field must be provided in the request URL:

Field	Description
domain-name-or-id	The domain name or Cloudonix domain ID in which the specified session is registered.

Response

If the request is successful, the server will respond with an HTTP 200 (“OK”) response with the content type “application/json” containing a JSON document with a list of session records, each with all session details except routing details (if set). See Sessions Model documentation for all the details of the session record - the example below is intentionally minimal.

Example

GET /calls/example.com/sessions
Host: api.cloudonix.io
Authorization: bearer XI1234567890

HTTP/1.1 200 OK

[
  {
    "domainId": 3,
    "subscriberId": 372,
    "remote": "63121233333",
    "direction": "outgoing",
    "status": "new",
    "token": "16a7294c989b11e7b3d32b9edb8660c7",
    "timeLimit": 7205
  },
  {
    "domainId": 3,
    "subscriberId": 15,
    "remote": "12124459087",
    "direction": "incoming",
    "status": "ringing",
    "token": "09bc786c98e711e7aa5927c0c5bb7cb4",
    "timeLimit": null
  }
]

Destroy Session (Hangup)

DELETE /calls/<domain-name-or-id>/sessions/<token>[?reason=<reason>]

This call can be used by the application backend to disconnect ongoing calls, or by Cloudonix services to remove the session data once the call has ended.

Conditions

This is a privileged API and requires system administrator, tenant administrator, domain administrator or an application authorization for the specified domain. When the server receives a call with lesser authorization it must return a 401 (“Unauthorized”) HTTP error response and stop processing.

Request

The following data fields must be provided in the request URL:

Field	Description
domain-name-or-id	The domain name or Cloudonix domain ID in which the specified session is registered.
token	The session token for the session to be deleted.

The following data field may be provided in the request query string:

Field	Description
reason	The reason for cancelling the session. See below table.

Reason	Description
timeout	the subscriber cannot be reached (either they’re offline or have not responded in time).
denied	the subscriber has rejected the call.
busy	the subscriber cannot take the call (another call is in progress).
nocredit	the subscriber has ran out of credit.

Response

If the request is successful, the server will respond with an HTTP 204 (“No Content”) response.

If the session being deleted has a callback field set to a URL, then the server will send a POST request to that URL with the session object as it looked just before the deletion with the additional field action set to deleted.

Example

DELETE /calls/example.com/sessions/16a7294c989b11e7b3d32b9edb8660c7
Host: api.cloudonix.io
Authorization: bearer XI1234567890

HTTP/1.1 204 No Content

Switch Voice Application

POST /calls/<domain-name-or-id>/sessions/<token>/application

This call can be used by the application backend to cause an active session to abort the running voice application and start running a new voice application, as specified in the request parameters.

Please note: if the currently active application is in a Dial command or a similar command that creates a phone call, the outgoing call will first be disconnected - as if the Hangup command was executed.

Conditions

This is a privileged API and requires system administrator, tenant administrator, domain administrator. If the API receives a call with lesser authorization it will return a 401 (“Unauthorized”) HTTP error response.

Additionally, the specified session must be actively running a voice application. If the API receives this request before a voice application has been executed, or after the session has been disconnected, the API will return a 400 ("Bad Request") HTTP error response.

Additionally, the request document must contain either the field cxml or the field url. If the API receives this request without any of these fields, or with both fields provided, the API will return a 400 ("Bad Request") HTTP error response.

Request

The following data fields must be provided in the request URL:

• Domain name or id - the domain name or Cloudonix domain ID in which the specified session is registered.
• Token - the session token for the session to be retrieved.

The following data field may be provided in a JSON document sent in the request body:

• cxml - the CXML document to be executed as the Voice Application instead of calling a remote URL to load the CXML document. The provided document must be a well-formed and valid CXML document (including the XML PI header), otherwise the session will be disconnected with an error.
• method - the HTTP method that will be used to send the CXML request to the Voice Application specified in the url field, if provided. Can contain the value "POST" or "GET". If not specified, and the url field is specified, this field is assumed to be "POST".
• url - a URL to a Voice Application that will be invoked with a CXML request for the session being updated. The result must be a valid CXML document that will be executed, otherwise the session will be disconnected with an error.

Response

If the request is successful, the server will respond with an HTTP 200 (“OK”) response with the content type “application/json” containing a JSON document with the current session details.

Example

POST  /calls/example.com/sessions/16a7294c989b11e7b3d32b9edb8660c7/application
Host: api.cloudonix.io
Authorization: bearer XI1234567890

{
  "cxml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Response><Say>We apologize for the interruption. Bye.</Say><Hangup/></Response>"
}

HTTP/1.1 200 OK

{
  "domainId": 3,
  "subscriberId": 372,
  "callerId": "63121222222",
  "remote": "63121233333",
  "token": "16a7294c989b11e7b3d32b9edb8660c7",
  ...
}

Fork Routed Call

POST /calls/<domain-name-or-id>/sessions/<token>/fork

The Fork operation is used to change an existing call between two voice endpoints (i.e. two subscribers, or a subscriber and a trunk, but not an application that interacts with a caller) into two calls with new applications running on each side of the call. When this request is executed by Cloudonix, the audio connection between the two ends of the call is disconnected where the caller session is switched to one of the applications provided by the fork request (similar to a Switch Voice Application request) and the callee is moved to its own session that will run the second application provided by the fork request.

Please note: for the fork request to succeed, the session must be in a Dial operation that is in a connected state. Otherwise the fork request will fail.

Conditions

This is a privileged API and requires system administrator, tenant administrator, domain administrator. If the API receives a call with lesser authorization it will return a 401 (“Unauthorized”) HTTP error response.

Additionally, the specified session must be actively running a voice application's Dial operation and in a connected state (i.e. after the callee has answered and before they hang up). If the API receives this request where those conditions are not fulfilled, the API will return a 409 ("Conflict") HTTP error response.

Additionally, each application described in the request document must contain either the field cxml or the field url. If the API receives this request without any of these fields, or with both fields provided, or missing any of the required fields, the API will return a 400 ("Bad Request") HTTP error response.

Request

The following data fields must be provided in the request URL:

• Domain name or id - the domain name or Cloudonix domain ID in which the specified session is registered.
• Token - the session token for the session to be retrieved.

The following data field must be provided in a JSON document sent in the request body:

• caller - a JSON object describing the application that will be executed on the caller's side of the call. The caller application object may provide the following fields:
• cxml - the CXML document to be executed as the Voice Application instead of calling a remote URL to load the CXML document. The provided document must be a well-formed and valid CXML document (including the XML PI header), otherwise the session will be disconnected with an error. Either this field or the url field must be provided.
• method - the HTTP method that will be used to send the CXML request to the Voice Application specified in the url field, if provided. Can contain the value "POST" or "GET". If not specified, and the url field is specified, this field is assumed to be "POST".
• url - a URL to a Voice Application that will be invoked with a CXML request for the session being updated. The result must be a valid CXML document that will be executed, otherwise the session will be disconnected with an error. Either this field or the cxml field must be provided.
• callee - a JSON object describing the application that will be executed on the callee's (remote) side of the call. The callee application object may provide the following fields:
• cxml - the CXML document to be executed as the Voice Application instead of calling a remote URL to load the CXML document. The provided document must be a well-formed and valid CXML document (including the XML PI header), otherwise the session will be disconnected with an error. Either this field or the url field must be provided.
• method - the HTTP method that will be used to send the CXML request to the Voice Application specified in the url field, if provided. Can contain the value "POST" or "GET". If not specified, and the url field is specified, this field is assumed to be "POST".
• url - a URL to a Voice Application that will be invoked with a CXML request for the session being updated. The result must be a valid CXML document that will be executed, otherwise the session will be disconnected with an error. Either this field or the cxml field must be provided.
• callback - If provided, set as the session updates callback URL for the new session that will be created for the callee's (remote) side.

Response

If the request is successful, the server will respond with an HTTP 202 (“Accepted”) response with the content type “application/json” containing a JSON document. The response document will contain two fields:

• caller - a session document, as can be retrieved from the Retrieve Session operation, describing the original ("caller") session.
• callee - a session document, as can be retrieved from the Retrieve Session operation, describing the new ("callee") session.

If the request does not contain all the required field in their required formats, the server will respond with an HTTP error 400 ("Bad Request") response, optionally detailing the problem with the request.

If the request cannot be fulfilled by the voice application engine, whether due to the forked session not being in a valid state (running Dial that is connected) or another issue, the server will respond with an HTTP error 409 ("Conflict") response.

Example

POST  /calls/example.com/sessions/16a7294c989b11e7b3d32b9edb8660c7/fork
Host: api.cloudonix.io
Authorization: bearer XI1234567890

{
  "caller": {
    "cxml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Response><Dial><Conference>room 101</Conference></Dial><Hangup/></Response>"
  },
  "callee": {
    "cxml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Response><Dial><Conference>room 101</Conference></Dial><Hangup/></Response>"
  }
}

HTTP/1.1 200 OK

{
  "caller": {
    "domainId": 3,
    "subscriberId": 372,
    "callerId": "63121222222",
    "remote": "63121233333",
    "token": "16a7294c989b11e7b3d32b9edb8660c7",
    ...
  },
  "callee": {
    "domainId": 3,
    "callerId": "63121233333",
    "remote": "63121222222",
    "token": "27683350ec524cacb8f27f79c32e361a",
    ...
  }
}

Mute or Unmute Call

POST /calls/<domain-name-or-id>/sessions/<token>/mute
DELETE /calls/<domain-name-or-id>/sessions/<token>/mute

The mute session operation is used to request the Cloudonix Application Runtime Engine to mute all audio (both directions) for the specified session.

Use the POST request to set the session to muted and the DELETE request to set the session back to normal.

Conditions

This is a privileged API and requires either a system administrator, tenant administrator, or domain administrator. If the API receives a call with lesser authorization it will return a 401 (“Unauthorized”) HTTP error response.

The session must have an audio channel connected to a Cloudonix Voice Application runtime. If the API receives a call before the session has setup an audio channel or after the audio channel had disconnected, it will return a 409 ("Conflict") HTTP error response.

Request

The following data fields must be provided in the request URL:

• Domain name or id - the domain name or Cloudonix domain ID in which the specified session is registered.
• Token - the session token for the session to be retrieved.

The request body is not inspected and can be anything.

Response

If the request is successful, the server will respond with an HTTP 204 (“No Content”) with no body.

Example

POST /calls/example.com/sessions/16a7294c989b11e7b3d32b9edb8660c7/mute
Host: api.cloudonix.io
Authorization: bearer XI1234567890

HTTP/1.1 204 No Content

DELETE /calls/example.com/sessions/16a7294c989b11e7b3d32b9edb8660c7/mute
Host: api.cloudonix.io
Authorization: bearer XI1234567890

HTTP/1.1 204 No Content

List Session Recordings

GET /calls/<domain-name-or-id>/sessions/<token>/recordings

The list recordings operation is used to list the audio files for any recordings performed for the session.

Conditions

This is a privileged API and requires either a system administrator, tenant administrator, or domain administrator. If the API receives a call with lesser authorization it will return a 401 (“Unauthorized”) HTTP error response.

Request

The following data fields must be provided in the request URL:

• Domain name or id - the domain name or Cloudonix domain ID in which the specified session is registered.
• Token - the session token for the session to be retrieved.

Response

If the request is successful, the server will respond with an HTTP 200 (“Accepted”) response with the content type “application/json” containing a JSON list containing URL strings for each recording found for the session. The URLs will be in the prefered audio recording format as specified by the recording-media-type property in the domain profile or "wav" if none specified.

Example

GET /calls/example.com/sessions/16a7294c989b11e7b3d32b9edb8660c7/recordings
Host: api.cloudonix.io
Authorization: bearer XI1234567890

HTTP/1.1 200 OK

[
"https://api.cloudonix.io/media/recording/example.com/2023/1/1/786b911f-78ad-4209-a676-dc7846669236.mp3"
]

Get Subscriber Active Sessions

GET /domains/<domain-name-or-id>/subscribers/<uuid-or-msisdn>/sessions

The list active sessions operation is used to list which sessions are currently active for a given subscriber. Here "active" means ringing or connected - to an application, trunk or another subscriber.

Conditions

This is a privileged API and requires either a system administrator, tenant administrator, or domain administrator. If the API receives a call with lesser authorization it will return a 401 (“Unauthorized”) HTTP error response.

Request

The following data fields must be provided in the request URL:

• Domain name or id - the domain name or Cloudonix domain ID that owns the specified subscriber.
• Subscriber UUID or MSISDN - an active subscriber identifier.

Response

If the request is successful, the server will respond with an HTTP 200 (“Accepted”) response with the content type “application/json” containing a JSON list containing session token strings for each session that this subscriber currently has active.

Example

GET /domains/example.com/subscribers/49765551-125d-47b5-ad42-d45ac7aa29ca/sessions
Host: api.cloudonix.io
Authorization: bearer XI1234567890

HTTP/1.1 200 OK

[
  "3d6fe57668f55288a8bc2aed6b9e7e01", "e81db2ed26388da0abe8ee1e50c8612c"
]