Session

For the impatient

You may explore this data model via the API Playground, by clicking here

Endpoints

• /calls/{domain}/sessions[/{token}]

The Cloudonix session model represents a call in the Cloudonix platform and is used throughout the Session Management APIs and is also used in the session status notification callback and sent to CDR end-points.

Properties

Property	Type	Editable	Description
domainId	Number	No	A numeric identifier of the domain in which this call was processed.
domain	Domain	No	A domain object describing the domain in which this call was processed.
subscriberId	Number	No	A numeric identifier of the subscriber that either originated (for outgoing and app-to-app) ore received the call.
destination	String	Create	The MSISDN of the destination of the call.
callerId	String	Create	The MSISDN of the source of the call.
direction	String	No	A textual description of the direction of the call. See below for details.
token	String	No	The unique session identifier used to access session data through the API and SDKs.
timeLimit	Number	Create	The time limit enforced on the call, in seconds.
profile	Object	Create, Update	A set of metadata fields that an application has assigned to this call. Cloudonix recognizes and reads some specific properties, while the customer may also update the profile with whatever metadata they wish to store in Cloudonix.
callStartTime	Number	No	The call start time (when the SIP session has started) in UNIX epoch milliseconds.
callAnswerTime	Number	No	The time the call was connected in UNIX epoch milliseconds.
callEndTime	Number	No	The time the call was disconnected in UNIX epoch milliseconds.
startTime	Date	No	The call start time in ISO-8601 format.
answerTime	Date	No	The time the call was connected in ISO-8601 format.
endTime	Date	No	The time the call was disconnected in ISO-8601 format.
callback	String	Create	A URL that will receive notification callbacks when the session is updated by Cloudonix services or otherwise.
routes	Object	Create	An LCR routing plan. See [the LCR specifications] for more details.
status	String	No	The current status of the call. See below for details.
createdAt	Date	No	The time when the session was created. That can either be the same as call start time, or earlier for pre-authorized calls
modifiedAt	Date	No	The time when the session object was last modified, either by a customer call or internally.
lastError	String	No	If an error was encountered during processing of this session, this field will include a system error message describing the last error that was detected (possibly causing the disconnection of the call).

Session Profile Properties

The following properties, if set on the profile field of the session, will be recognized by Cloudonix and will cause the behavior documented below for that property.

Field	Type	Description
terminating-trunk-id	Number	For successful calls routed out from the Cloudonix Platform, this field will contain the numeric identfier of the Cloudonix trunk configuration that was used for outbound routing.
errors	array of String	If there were errors during the handling of this call, this field will contain a list of all the errors
sip-headers	Object	If set, for a call routed out from the Cloudonix Platform, Cloudonix will add any property set in the sip-headers object as custom SIP headers on the outgoing SIP session, in the format X-CX-Session-{property-name}: {property-value}. Values will be converted to strings on a best-effort basis.
subscriber-sip-headers	Object	If set, the SIP custom headers (headers set with the prefix X-CX-) sent by the subscriber that originated this session, with the X-CX- prefix stripped.
trunk-sip-headers	Object	If set, the SIP custom headers (headers set with the prefix X-CX-) sent by the trunk that originated this session, with the X-CX- prefix stripped.
recordings	array(String)	if there were recording operations in the call (whether using the <Record> verb, a dial recording or otherwise), this will contain a list of identifiers of such recordings.
raw-recordings	array(String)	if there were recording operations in the call (whether using the <Record> verb, a dial recording or otherwise), this will contain a list of identifiers of the raw data of such recordings.

direction field

The direction field can have one of the following values:

Value	Description
incoming	The call was incoming from a trunk to a subscriber
outgoing	The call was outgoing from a subscriber to a trunk
internal	The call was between two subscribers
application	The call was originated by an application

status field

The status field can have one of the following values:

Value	Description
new	A SIP call has just started or a Registration-Free session was just created.
processing	The Cloudonix Platform is launching the voice application.
ringing	The voice application has dialed another subscriber or an outbound destination; this state includes the call setup and may not actually indicate that the destination is actually ringing. A call may be rejected after it is ringing.
connected	The call is connected to a destination or the voice application has answered.
answer	The call has completed and it was answered before it has ended.
noanswer	The call has completed but it was not answered while ringing before the ringing timeout has expired.
busy	The call was rejected by the destination.
nocredit	The call was disconnected due to not enough credit.
cancel	The call was disconnected by the caller before it was answered. This may be before the voice application was launched or after (if the voice application did not answer, for example because it issued a <Dial>).
external	The call was disconnected by an API call without providing a reason.
error	The call was disconnected due to an error in the voice application or in the Cloudonix Platform.

Session Search Queries

The list sessions operation (GET …/sessions) offers a rich search language using query string parameters, to allow filtering of the results according to the model fields.

The following general query string parameters are understood:

• limit - limit the response to the specified number of entries. The default value is 1000 and it is also not allowed to specify more than 1000 or less than 1.

• start - use paging to access the next block of sessions. For example, specifying limit=100&start=100 will retrieve the 101 to 200 entries.

• desc - use descendind order (either using the default session creation time order, or any other order specified).

The following field-specific query string operators are understood:

• order={field} - when set to the name of a field, the query will be ordered by that field. Only one order field is supported.

• by_{field}={value} - find sessions where the specified field has the specified value. If the value specified is the special string null, then the result will only include sessions where that field is set to null (please note that not all fields are nullable). If the value specified is the special string !null, then the result will only include sessions where that field is not set to null.

• has_{field} - find sessions where thae specified field is not set to null or a numeric field not set to 0 (as appropriate).

• {field}_lt={value}, {field}_le={value}, {field}_lt={value}, {field}_ge={value} - the specified field is set to a value to that less than, less then or equal, greater than, or greater than or equal to the specified value.

Session Recordings

Endpoints

• /calls/{domain}/sessions/{token}/recordings
• /calls/{domain}/sessions/{token}/raw-recordings

Each of these endpoints will return a JSON array of media URLs for the recordings in the session (as per the session model's profile's recordings field) or raw recordings (as per the session model's profile's raw-recordings field), respectively.

The URLs listed can be used to download the recording files through the Cloudonix Media API - as long as these are retained by Cloudonix. The URLs are presented with a file extension as per the configuration in the domain's profile property recording-media-type, but the customer can substitute the extension to have the Cloudonix Media API encode the files to a different supported format.

Cloudonix will store session recording data for up to 15 days since creation. For any session whose end time is older than 15 days, the Cloudonix Media API may not have the data available and will return 404 for these URLs. If you require longer storage times - contact your Cloudonix sales person to get a quote for additional storage.