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

 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 initiates an outbound application instance when using the REST application. The outbound service name and outbound service password are supplied in the authorisation string.

    Url:https://ws.aculabcloud.net/service_start
    Methods:GET, POST
    Username:cloudID/username/outbound_service_name (e.g. 1-2-0/user@example.com/MyOutboundService)
    Password:outbound service password

    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.

    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.

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

    Response:

      [
        "2e891aea_0.1366641192.77832",
        "2e891aea_0.1366641192.77833"
      ]
  • Service Start (UAS)

    This invokes an outbound service that initiates an outbound application instance when using a UAS application. The outbound service name and outbound service password are supplied in the authorisation string.

    Url:https://ws.aculabcloud.net/service_start
    Methods:GET, POST
    Username:cloudID/username/outbound_service_name (e.g. 1-2-0/user@example.com/MyOutboundService)
    Password:outbound service password

    ParameterValueDescription
    countinteger (optional)by default a single instance is invoked. Specifying more than one (Production and Premium accounts only) invokes multiple instances.
    outbound_parametersstring (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.
    delimitercharacter (optional)the delimiting character when multiple outbound parameter strings are defined(Production and Premium accounts only)

    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.

    Url:https://ws.aculabcloud.net/service_cancel
    Methods:GET, POST

    (see Overview for required authentication)


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

    Url:https://ws.aculabcloud.net/service_status
    Methods:GET, POST

    (see Overview for required authentication)


    ParameterValueDescription
    service_refsstringa 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:

    ParameterValueDescription
    statusstringa 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_etaintegerthe time at which the application's status will be ready for retrieval.
    application_instance_idstringthe 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.

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

    (see Overview for required authentication)


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

    ParameterValueDescription
    application_instance_idstringthe application instance's unique ID.
    application_namestringthe name of the application.
    start_timefloatthe time the application instance started.
    start_datetimestringthe time the application instance started formatted as YYYY-MM-DD_hh:mm:ss.
    stop_timefloatthe time the application instance stopped.
    stop_datetimestringthe time the application instance stopped formatted as YYYY-MM-DD_hh:mm:ss.
    durationfloatthe duration of the application instance in seconds.
    tts_secondsfloatthe duration of any Text-To-Speech used in seconds.
    tts_unit_costfloatthe per minute cost of any Text-To-Speech used.
    extra_channel_countintegerthe number of extra channels configured for the application instance.
    faxstring"true" if fax is enabled on the service. Else "false".
    platform_costfloatthe Aculab Cloud platform cost for the instance.
    extra_costfloatthe cost of any extra channel usage.
    pstn_costfloatthe cost of any outbound PSTN telephone calls.
    tts_costfloatthe cost of any Text-To-Speech used.
    tollfree_costfloatthe cost of any toll free telephone calls.
    feature_secondsfloatthe total duration of any features used in seconds.
    feature_costfloatthe total cost of any features used.
    total_costfloatthe total cost for the application instance
    costs_validstring"true" if the costs provided are valid. Else "false".
    exit_statusintegerthe numeric return code passed back by the application instance
    outbound_parametersstringa shortened representation of the outbound parameters passed to the application instance.
    application_parametersstringa shortened representation of the application parameters sent to the application instance.
    rest_log_filenamestringthe name of the REST log file associated with this instance. Empty for non-REST applications.
    uas_ip_addressstringfor REST applications this returns an empty string. Otherwise it contains the public ip address of the UAS where the application was run.
    uas_namestringfor 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_tostringthe to parameter supplied for an outbound REST call. Empty for non-REST or inbound applications.
    rest_fromstringthe from parameter supplied for an outbound REST call. Empty for non-REST or inbound applications.
    rest_initial_tokenstringa shortened representation of the token parameter initially supplied for an outbound REST call. Empty for non-REST or inbound applications.

    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:

    ParameterValueDescription
    destination_addressstringthe target destination of the call.
    originating_addressstringthe address from which the call was made.
    dirstringthe direction of the call ("in", "out" or "client").
    channel_typestring"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_timefloatthe time at which the call was placed.
    call_initiated_datetimestringthe time at which the call was placed formatted as YYYY-MM-DD_hh:mm:ss.
    call_connected_timefloatthe time at which the call became connected.
    call_connected_datetimestringthe time at which the call became connected formatted as YYYY-MM-DD_hh:mm:ss.
    call_hangup_timefloatthe time at which the call was hung up.
    call_hangup_datetimestringthe time at which the call was hung up formatted as YYYY-MM-DD_hh:mm:ss.
    durationfloatthe duration of the call in seconds.
    joinedfloatthe duration in seconds for which the call was joined (connected or transferred) to another call.
    hangup_causestringthe reason why the call was disconnected.
    call_costfloatthe cost of the call
    costs_validstring"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.

    ParameterValueDescription
    error_codestringa four digit code for the error.
    error_textstringa textual explanation of the error.
    error_linkstringa 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:

    ParameterValueDescription
    audio_pathstringa string describing the audio path of the call to which the feature was applied: "in", "out", "mixed" or "" if not applicable.
    typestringthe type of feature used.
    Speech Recognition features start with "sr_" and include: "sr_play", "sr_get_input", "sr_run_speech_menu", "sr_start_transcription".
    Speaker Verification features start with "sv_" and include: "sv_register", "sv_verify".
    start_timefloatthe time at which the feature started.
    start_datetimestringthe time at which the feature started formatted as YYYY-MM-DD_hh:mm:ss.
    stop_timefloatthe time at which the feature stopped.
    stop_datetimestringthe time at which the feature stopped formatted as YYYY-MM-DD_hh:mm:ss.
    durationfloatthe duration of the feature in seconds.
    duration_for_costfloatthe duration in seconds that was used to calculate cost.
    costfloatthe cost of using the feature.
    unit_costfloatthe per minute cost of using the feature.
    costs_validstring"true" if the costs provided are valid. Else "false".
    application_instance_idstringthe application instance's unique ID.
    call_idstringthe call id for the call on which the feature was used.
    transaction_idstringthe 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_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.0018,
        "tts_seconds": 15.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": {}
    }