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.

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.

• Service Start (REST)
• Service Start (UAS)
• Service Cancel
• Service Status
• Application Status
• Job Status
• Service Start (REST)

• 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/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 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/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 ^, | 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/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 /.

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

  Request:

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

  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/other-apis/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/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.

  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
    }