Starting Outbound Services
This describes how to use a web service to start outbound services on Aculab Cloud and how to query for inbound and outbound application status.
An Inbound Service is invoked when a call is made to its telephone number or SIP address.
An Outbound Service is invoked by calling the 'service_start' web service with its Outbound Service Name.
The application status for both inbound and outbound services can be queried using the Application Status web service.
Call prefixes
When specifying telephone numbers and sip addresses Aculab Cloud will treat anything containing only digits,
optionally separated by a single '-', as a telephone number and everything else as a SIP address.
One of the following prefixes can be used to declare a specific type of number/address.
| Prefix | Description | Example |
|---|---|---|
| tel | a telephone or cell (mobile) number | tel:441908273800 |
| sip | a SIP username@address | sip:contact@example.com |
| loc | an inbound service hosted on the same cloud region | loc:my_inbound_service |
| webrtc | a WebRTC client identified by the supplied client ID | webrtc:clientId |
| wss | a secure websocket URL | wss://www.example.com/mywsapp |
| con | a conference room name | con:MyConferenceRoom |
When using the tel prefix for a call destination, the full international number must be supplied.
This must not contain any leading '0'. The leading '+' is optional. The call will be placed with Aculab's default providers.
Aculab Cloud does not support calling premium rate numbers via our outbound provider.
Note
This is a low level API. For information on higher level APIs see the Web Services Language Wrappers
Service Start (REST)
This invokes an outbound service that makes an outbound call and starts an outbound REST application to handle that call.
Authorisation
This API uses basic authentication, using a combination of the cloud id, your cloud account username and the name of the service you are starting and this service's outbound password.
| Username | : | cloudID/username/service_name (e.g. 1-2-0/ |
| Password | : | Outbound Service Password |
Request:
| Url | : | https://ws.aculabcloud.net/ |
| Methods | : | GET, POST |
| Parameter | Value | Description |
|---|---|---|
| rest_calls | string | A JSON formatted string containing either a single object specifying where to call or, for Production and Premium accounts only, a list of these objects. An outbound service will be started for each object. |
| outbound_parameters | string | A legacy alias for rest_calls. |
| unique_id | string (optional) | If supplied this is a unique identifier for a request. This acts to ensure that duplicate requests to the service_start API are idempotent. A duplicate request will return the list of service references previously started by the original request. A duplicate identifier with different parameters will result in an error. |
The JSON objects contain the following parameters:
| Property | Required/Optional | Description |
|---|---|---|
| to | required | A string containing the destination for the outbound call. This can be a phone number, SIP address, inbound service address, webRTC client, or conference room name (see Call Prefixes). |
| from | required only if to is a telephone number |
A string containing the caller ID (a telephone number or SIP username) for the call.
If to is a telephone number, then this needs to be a validated
Caller ID).
|
| token | optional | A string containing a user-defined token of up to 5000 characters that will be passed transparently to the Web App in the
token property of the instance_info argument to the page
request.
|
| outbound_parameters | optional | A string containing user-defined data that will be passed transparently to the
Web App in the this_call.outbound_parameters
property of the instance_info argument to the page
request.
|
| extra_sip_headers | optional | A list of SIP header objects. These represent additional headers to include in the request to initiate the outbound call. |
Returns:
A JSON array of unique service invocation reference IDs.
Example:
https://ws.aculabcloud.net/service_start?rest_calls= [ { "to" : "441908283800", "from" : "441908283801", "token" : "token1", "outbound_parameters" : "some user data" }, { "to" : "sip:bob@acompany.com", "token" : "token2", "extra_sip_headers": [ { "name": "X-AccountInfo", "value": "bob/123456789" } ] } ]
Response:
[
"2e891aea_0.1366641192.77832",
"2e891aea_0.1366641192.77833"
]
Service Start (UAS)
This invokes an outbound service that initiates an outbound UAS application instance that makes an outbound call.
Authorisation
This API uses basic authentication, using a combination of the cloud id, your cloud account username and the name of the service you are starting and this service's outbound password.
| Username | : | cloudID/username/service_name (e.g. 1-2-0/ |
| Password | : | Outbound Service Password |
Request:
| Url | : | https://ws.aculabcloud.net/ |
| Methods | : | GET, POST |
| Parameter | Value | Description |
|---|---|---|
| count | integer (optional) | by default a single instance is invoked. Specifying more than one (Production and Premium accounts only) invokes multiple instances. |
| outbound_parameters | string (optional) | the outbound parameter string to be sent to the outbound application(s). Specifying a number of strings, each separated by the delimiter character below, invokes an instance for each one (and count is ignored). Must contain only seven bit ASCII, excluding ^, | and the control characters. |
| delimiter | character (optional) | the delimiting character when multiple outbound parameter strings are defined(Production and Premium accounts only) |
| unique_id | string (optional) | If supplied this is a unique identifier for a request. This acts to ensure that duplicate requests to the service_start API are idempotent. A duplicate request will return the list of service references previously started by the original request. A duplicate identifier with different parameters will result in an error. |
Returns:
A JSON array of unique service invocation reference IDs.
Example:
https://ws.aculabcloud.net/service_start?outbound_parameters=destinationForApp1,destinationForApp2&delimiter=,
Response:
[
"2e891aea_0.1366641192.77832",
"2e891aea_0.1366641192.77833"
]
Service Cancel
This attempts to cancel one or more services that have been queued, but that are not yet running. Once a service is running it cannot be cancelled.
Authorisation
This API uses basic authentication, using your cloud account username and API Access Key.
| Username | : | cloudID/username (e.g. 1-2-0/ |
| Password | : | API Access key |
Request:
| Url | : | https://ws.aculabcloud.net/ |
| Methods | : | GET, POST |
| Parameter | Value | Description |
|---|---|---|
| service_refs | string | a list of service invocation reference IDs (as returned by service_start) delimited by the character /. |
Returns:
A JSON object containing a status for each of the service instances supplied, keyed by their service invocation reference Id. The status for each service invocation will be either: "success", "unknown" or "failed". "success" indicates that the service invocation was successfully cancelled before it was run. "unknown" indicates that the service was not recognised, either because it was incorrect or has expired. "failed" indicates that the service was recognised but could not be cancelled.
Example:
https://ws.aculabcloud.net/service_cancel?service_refs=2e891aea_0.1366641192.77832/2e891aea_0.1366641192.77834
Response:
{
"2e891aea_0.1366641192.77832" : "success",
"2e891aea_0.1366641192.77834" : "unknown"
}
Service Status
This retrieves the status of one or more outbound service invocations given their service invocation reference IDs.
Authorisation
This API uses basic authentication, using your cloud account username and API Access Key.
| Username | : | cloudID/username (e.g. 1-2-0/ |
| Password | : | API Access key |
Request:
| Url | : | https://ws.aculabcloud.net/ |
| Methods | : | GET, POST |
| Parameter | Value | Description |
|---|---|---|
| service_refs | string | a list of service invocation reference IDs (as returned by service_start) delimited by the character /. |
Returns:
A JSON object containing a status object for each of the service instances supplied, keyed by their service invocation reference Id. The status object returned for each service invocation has the following properties:
| Parameter | Value | Description |
|---|---|---|
| status | string | a string containing one of "queued", "running", "completed", "couldnotrun", "cancelled" or "unknown". If it is "completed" the application's numeric return code is also included. If the status is "couldnotrun" a textual reason is also included. "unknown" indicates that the id was not recognised and "cancelled" is returned for a service that has been cancelled using service_cancel. |
| application_status_eta | integer | the time at which the application's status will be ready for retrieval. |
| application_instance_id | string | the application instance ID. Use this ID to get the status of an application instance. |
Example:
https://ws.aculabcloud.net/service_status?service_refs=2e891aea_0.1366641192.77832/2e891aea_0.1366641192.77834
Response:
{
"2e891aea_0.1366641192.77832":
{
"status": "completed 0",
"application_status_eta": 1366710198,
"application_instance_id": "049136ca36e44662.200476"
},
"2e891aea_0.1366641192.77834":
{
"status": "couldnotrun No UAS is connected",
"application_status_eta": 0,
"application_instance_id": ""
}
}
Application Status
This retrieves the detailed status of a single application instance.
Authorisation
This API uses basic authentication, using your cloud account username and API Access Key.
| Username | : | cloudID/username (e.g. 1-2-0/ |
| Password | : | API Access key |
Request:
| Url | : | https://ws.aculabcloud.net/ |
| Methods | : | GET, POST |
| Parameter | Value | Description |
|---|---|---|
| application_instance_id | string | the application instance id of the instance to check. |
Returns:
JSON object containing the detailed status of the corresponding application instance.
This always contains three parts: "adr", the application data record; "cdrs", the call data records; and "errs", the error reports.
In addition it may contain an additional part: "fdrs", the feature data records, depending on whether certain features are used by the application (e.g. Speech Recognition).
adr
The application data record contains details of the application instance.
| Parameter | Value | Description |
|---|---|---|
| application_instance_id | string | the application instance's unique ID. |
| application_name | string | the name of the application. |
| start_time | float | the time the application instance started. |
| start_datetime | string | the time the application instance started formatted as YYYY-MM-DD_hh:mm:ss. |
| stop_time | float | the time the application instance stopped. |
| stop_datetime | string | the time the application instance stopped formatted as YYYY-MM-DD_hh:mm:ss. |
| duration | float | the duration of the application instance in seconds. |
| tts_seconds | float | the duration of any Text-To-Speech used in seconds. |
| tts_unit_cost | float | the per minute cost of any Text-To-Speech used. |
| extra_channel_count | integer | the number of extra channels configured for the application instance. |
| fax | string | "true" if fax is enabled on the service. Else "false". |
| platform_cost | float | the Aculab Cloud platform cost for the instance. |
| extra_cost | float | the cost of any extra channel usage. |
| pstn_cost | float | the cost of any outbound PSTN telephone calls. |
| tts_cost | float | the cost of any Text-To-Speech used. |
| tollfree_cost | float | the cost of any toll free telephone calls. |
| feature_seconds | float | the total duration of any features used in seconds. |
| feature_cost | float | the total cost of any features used. |
| total_cost | float | the total cost for the application instance |
| costs_valid | string | "true" if the costs provided are valid. Else "false". |
| exit_status | integer | the numeric return code passed back by the application instance |
| outbound_parameters | string | a shortened representation of the outbound parameters passed to the application instance. |
| application_parameters | string | a shortened representation of the application parameters sent to the application instance. |
| rest_log_filename | string | the name of the REST log file associated with this instance. Empty for non-REST applications. |
| uas_ip_address | string | for REST applications this returns an empty string. Otherwise it contains the public ip address of the UAS where the application was run. |
| uas_name | string | for REST applications this return an empty string. Otherwise it contains the UAS name as set in the UAS Management Console settings page where this application was run. |
| rest_to | string | the to parameter supplied for an outbound REST call. Empty for non-REST or inbound applications. |
| rest_from | string | the from parameter supplied for an outbound REST call. Empty for non-REST or inbound applications. |
| rest_initial_token | string | a shortened representation of the token parameter initially supplied for an outbound REST call. Empty for non-REST or inbound applications. |
| tts_neural_seconds | float | the duration of any neural Text-To-Speech used in seconds. |
| tts_neural_unit_cost | float | the per minute cost of any neural Text-To-Speech used. |
| tts_neural_cost | float | the cost of any neural Text-To-Speech used. |
cdrs
The call data records contain information about the telephone calls that were made by the application instance. These are JSON objects keyed on the ID for each call. Each cdr contains the following information:
| Parameter | Value | Description |
|---|---|---|
| destination_address | string | the target destination of the call. |
| originating_address | string | the address from which the call was made. |
| dir | string | the direction of the call ("in", "out" or "client"). |
| channel_type | string | "p" for a primary call channel, "x" for an extra channel, "ca" for an audio only WebRTC client call, "cv" for a WebRTC client call with video. |
| call_initiated_time | float | the time at which the call was placed. |
| call_initiated_datetime | string | the time at which the call was placed formatted as YYYY-MM-DD_hh:mm:ss. |
| call_connected_time | float | the time at which the call became connected. |
| call_connected_datetime | string | the time at which the call became connected formatted as YYYY-MM-DD_hh:mm:ss. |
| call_hangup_time | float | the time at which the call was hung up. |
| call_hangup_datetime | string | the time at which the call was hung up formatted as YYYY-MM-DD_hh:mm:ss. |
| duration | float | the duration of the call in seconds. |
| joined | float | the duration in seconds for which the call was joined (connected or transferred) to another call. |
| hangup_cause | string | the reason why the call was disconnected. |
| call_cost | float | the cost of the call |
| costs_valid | string | "true" if the costs provided are valid. Else "false". |
errs
The error data will normally be an empty JSON object, but if an error has occurred it will contain an error message and a link to relevant information on cloud.aculab.com. The JSON object is keyed on the error number.
| Parameter | Value | Description |
|---|---|---|
| error_code | string | a four digit code for the error. |
| error_text | string | a textual explanation of the error. |
| error_link | string | a link to online documentation for the error code. |
fdrs
The feature data records contain information about any specific features that were used by the application instance. These are JSON objects keyed on a unique ID for each feature. Each record contains the following information:
| Parameter | Value | Description |
|---|---|---|
| audio_path | string | a string describing the audio path of the call to which the feature was applied: "in", "out", "mixed" or "" if not applicable. |
| type | string | the type of feature used. Speech Recognition features start with "sr" and include: "sr_play", "sr_get_input", "sr_run_speech_menu", "sr_start_transcription" for standard models and "srp1_play", "srp1_get_input", "srp1_run_speech_menu", "srp1_start_transcription" for premium models. Speaker Verification features start with "sv" and include: "sv_register" and "sv_verify". Connect Translator features start with "ct" and include: "ct_connect_translator" for a translator using a standard Text-To-Speech voice and a standard speech recognition model, "ctn_connect_translator" for a translator using a neural Text-To-Speech voice and a standard speech recognition model, "ctp1_connect_translator" for a translator using a standard Text-To-Speech voice and a premium speech recognition model and "ctnp1_connect_translator" for a translator using a neural Text-To-Speech voice and a premium speech recognition model. |
| start_time | float | the time at which the feature started. |
| start_datetime | string | the time at which the feature started formatted as YYYY-MM-DD_hh:mm:ss. |
| stop_time | float | the time at which the feature stopped. |
| stop_datetime | string | the time at which the feature stopped formatted as YYYY-MM-DD_hh:mm:ss. |
| duration | float | the duration of the feature in seconds. |
| duration_for_cost | float | the duration in seconds that was used to calculate cost. |
| cost | float | the cost of using the feature. |
| unit_cost | float | the per minute cost of using the feature. |
| costs_valid | string | "true" if the costs provided are valid. Else "false". |
| application_instance_id | string | the application instance's unique ID. |
| call_id | string | the call id for the call on which the feature was used. |
| transaction_id | string | the ID of the transaction. |
Examples:
https://ws.aculabcloud.net/application_status?application_instance_id=100d73cb12cbf845.8089
Response:
{
"adr": {
"application_instance_id": "100d73cb12cbf845.8089",
"application_name": "outbound_test",
"application_parameters": "",
"costs_valid": "true",
"duration": 33.21,
"exit_status": 0,
"extra_channel_count": 0,
"extra_cost": 0.0,
"fax": "false",
"feature_cost": 0.0,
"feature_seconds": 0.0,
"outbound_parameters": "",
"platform_cost": 0.01,
"pstn_cost": 0.016,
"rest_from": "443069999876",
"rest_initial_token": "9176280",
"rest_log_filename": "2019/03/14/rest_14_15_49_100d73cb12cbf845.8089.log",
"rest_to": "tel:443069990123",
"start_datetime": "2019-03-14_14:15:16",
"start_time": 1552572916.21,
"stop_datetime": "2019-03-14_14:15:49",
"stop_time": 1552572949.42,
"tollfree_cost": 0.0,
"total_cost": 0.027,
"tts_cost": 0.0018,
"tts_neural_cost": 0.0,
"tts_neural_seconds": 0.0,
"tts_neural_unit_cost": 0.0192,
"tts_seconds": 15.0,
"tts_unit_cost": 0.0072,
"uas_ip_address": "",
"uas_name": ""
},
"cdrs": {
"100d73cb12cbf845.106285.246346213": {
"call_connected_datetime": "2019-03-14_14:15:16",
"call_connected_time": 1552572916.97,
"call_cost": 0.0,
"call_hangup_datetime": "2019-03-14_14:15:49",
"call_hangup_time": 1552572949.07,
"call_initiated_datetime": "2019-03-14_14:15:16",
"call_initiated_time": 1552572916.39,
"channel_type": "p",
"costs_valid": "false",
"destination_address": "tel:443069990123",
"dir": "out",
"duration": 32.09,
"hangup_cause": "NORMAL(200)",
"joined": 0.0,
"originating_address": "443069999876@sip-0-0-0.aculab.com"
}
},
"errs": {},
"fdrs": {}
}
https://ws.aculabcloud.net/application_status?application_instance_id=049136ca36e44662.200476
Response:
{
"adr": {
"application_instance_id": "049136ca36e44662.200476",
"application_name": "outbound_test",
"application_parameters": "443069990123",
"costs_valid": "true",
"duration": 10.86,
"exit_status": -111,
"extra_channel_count": 0,
"extra_cost": 0.0,
"fax": "false",
"feature_cost": 0.0,
"feature_seconds": 0.0,
"outbound_parameters": "443069990123;hel...",
"platform_cost": 0.01,
"pstn_cost": 0.0,
"rest_from": "",
"rest_initial_token": "",
"rest_log_filename": "",
"rest_to": "",
"start_datetime": "2013-04-23_13:58:45",
"start_time": 1366725525.81,
"stop_datetime": "2013-04-23_13:58:56",
"stop_time": 1366725536.67,
"tollfree_cost": 0.057,
"total_cost": 0.067,
"tts_cost": 0.0,
"tts_neural_cost": 0.0048,
"tts_neural_seconds": 15.0,
"tts_neural_unit_cost": 0.0192,
"tts_seconds": 0.0,
"tts_unit_cost": 0.0072,
"uas_ip_address": "123.100.100.223",
"uas_name": "Prod001"
},
"cdrs": {
"049136ca36e44662.209560.914358273": {
"call_connected_datetime": "2013-04-23_13:58:55",
"call_connected_time": 1366725535.1099,
"call_cost": 0.0,
"call_hangup_datetime": "2013-04-23_13:58:56",
"call_hangup_time": 1366725536.31,
"call_initiated_datetime": "2013-04-23_13:58:45",
"call_initiated_time": 1366725525.8599,
"channel_type": "p",
"costs_valid": "false",
"destination_address": "tel:443069990123",
"dir": "out",
"duration": 1.2,
"hangup_cause": "NORMAL(200)",
"joined": 0.0,
"originating_address": "443069990123@sip-0-0-0.aculab.com"
}
},
"errs": {
"0": {
"error_code": "2008",
"error_link": "https://www.aculab.com/cloud/web-services/web-service-errors?error=2008",
"error_text": "UAS application [outbound_reminder]. app_args [443069990123]. started ok. completion status [-111]"
}
},
"fdrs": {}
}
Job Status
This retrieves the result of a service start submitted with a customer defined unique_id.
Authorisation
This API uses basic authentication, using your cloud account username and API Access Key.
| Username | : | cloudID/username (e.g. 1-2-0/ |
| Password | : | API Access key |
Request:
| Url | : | https://ws.aculabcloud.net/ |
| Methods | : | GET, POST |
| Parameter | Value | Description |
|---|---|---|
| unique_id | string | The unique identifier supplied in the service start. |
Returns:
JSON object containing the result of the service start.
| Parameter | Value | Description |
|---|---|---|
| queued | integer | The number of service starts queued in the original request |
| service_refs | list of strings | The list of service references created in the original service start request |
| count | integer | The number of service starts that where submitted in the original request |
Example:
https://ws.aculabcloud.net/job_status?unqiue_id=452f1997-73ac-4b40-aaa9-f5516fe6b119,
Response:
{
"queued": 2,
"service_refs": [
"2e891aea_0.1366641192.77832",
"2e891aea_0.1366641192.77833" ],
"count": 2
}