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.

Parameter	Value	Description
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

Basic authentication, uses 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/bob@example.com/MyOutboundService)
Password	: Outbound Service Password

Request


URL	: https://ws.aculabcloud.net/service_start
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 rest_calls JSON objects contain the following parameters:

Parameter	Value	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.

Response

A JSON array of unique service invocation reference IDs.

Example

Request

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

Basic authentication, uses 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/bob@example.com/MyOutboundService)
Password	: Outbound Service Password

Request


URL	: https://ws.aculabcloud.net/service_start
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 ^,
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.

Response

A JSON array of unique service invocation reference IDs.

Example

Request

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/bob@example.com)
Password	: API Access Key

Request


Url	: https://ws.aculabcloud.net/service_cancel
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 /.

Response

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

Request

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"
  }

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/bob@example.com)
Password	: API Access Key

Request


URL	: https://ws.aculabcloud.net/application_status
Methods	: GET, POST

Parameter	Value	Description
application_instance_id	string	the application instance id of the instance to check.

Response

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 (Application Data Record)

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.
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 (Call Data Records)

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".
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.
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 (Feature Data Records)

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

Example 1

Request

https://ws-0-2-0.aculabcloud.net/<wbr>application_status?<wbr>application_instance_id=<wbr>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&#64;sip-0-0-0.aculab.com"
    }
  },
  "errs": {},
  "fdrs": {}
}

Example 2

Request

https://ws-0-2-0.aculabcloud.net/<wbr>application_status?<wbr>application_instance_id=<wbr>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&#64;sip-0-0-0.aculab.com"
    }
  },
  "errs": {
    "0": {
      "error_code": "2008",
      "error_link": "https://docs.cloud.aculab.com/Web_Services_API/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/bob@example.com)
Password	: API Access Key

Request


URL	: https://ws.aculabcloud.net/job_status
Methods	: GET, POST

Parameter	Value	Description
unique_id	string	The unique identifier supplied in the service start.

Response

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

Request

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
  }