By using the Aculab site, you agree with our use of cookies.

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.

 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

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

    PropertyRequired/OptionalDescription
    to required A string containing the destination for the outbound call. This can be a phone number, SIP address or conference room name.
    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 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:This email address is being protected from spambots. You need JavaScript enabled to view it.", "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
    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)

    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

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

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

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

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

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

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

    ParameterValueDescription
    application_instance_id string the application instance's unique ID.
    application_name string the name of the application.
    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.
    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".
    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.
    start_time float the time the application instance started.
    stop_time float the time the application instance stopped.
    start_datetime string the time the application instance started formatted as YYYY-MM-DD_hh:mm:ss.
    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.
    exit_status integer the numeric return code passed back by the application instance
    costs_valid string "true" if the costs provided are valid. Else "false".
    pstn_cost float the cost of any outbound PSTN telephone calls.
    platform_cost float the Aculab Cloud platform cost for the instance.
    tollfree_cost float the cost of any toll free telephone calls.
    extra_cost float the cost of any extra channel usage.
    tts_cost float the cost of any Text-To-Speech used.
    total_cost float the total cost for the application instance
    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.
    feature_seconds float the total duration of any features used in seconds.
    feature_cost float the total cost of any features used.
    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.
    rest_log_filename string the name of the REST log file associated with this instance. Empty for non-REST 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
    dir string the direction of the call ("in" or "out").
    channel_type string "p" for a primary call channel, "x" for an extra channel.
    originating_address string the address from which the call was made.
    destination_address string the target destination of the call.
    duration float the duration of the call in seconds.
    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.
    hangup_cause string the reason why the call was disconnected.
    joined float the duration in seconds for which the call was joined (connected or transferred) to another call.

    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_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:

    ParameterValueDescription
    application_instance_id string the application instance's unique ID.
    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".
    start_time float the time at which the feature started.
    stop_time float the time at which the feature stopped.
    start_datetime string the time at which the feature started formatted as YYYY-MM-DD_hh:mm:ss.
    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.
    call_id string the call id for the call on which the feature was used.
    audio_path string a string describing the audio path of the call to which the feature was applied: "in", "out" or "mixed".

    Examples:

    https://ws.aculabcloud.net/application_status?application_instance_id=100d73cb12cbf845.8089

    Response:

      {
        "cdrs":
        {
          "100d73cb12cbf845.106285.246346213":
          {
            "dir": "out",
            "channel_type": "p",
            "destination_address": "tel:443069990123",
            "originating_address": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
            "call_initiated_time": 1552572916.39,
            "call_connected_time": 1552572916.97,
            "call_hangup_time": 1552572949.07,
            "call_initiated_datetime": "2019-03-14_14:15:16",
            "call_connected_datetime": "2019-03-14_14:15:16",
            "call_hangup_datetime": "2019-03-14_14:15:49",
            "duration": 28.2,
            "joined": 0.0,
            "hangup_cause": "NORMAL(200)"
          }
        },
        "adr":
        {
          "application_instance_id": "100d73cb12cbf845.8089",
          "application_name": "outbound_test",
          "uas_ip_address": "",
          "uas_name": "",
          "extra_channel_count": 0,
          "fax": "false",
          "outbound_parameters": "",
          "application_parameters": "",
          "start_datetime": "2019-03-14_14:15:16",
          "stop_datetime": "2019-03-14_14:15:49",
          "start_time": 1552572916.21,
          "stop_time": 1552572949.42,
          "duration": 33.2,
          "exit_status": 0,
          "costs_valid": "true",
          "total_cost": 0.027,
          "pstn_cost": 0.016,
          "platform_cost": 0.01,
          "tollfree_cost": 0.0,
          "extra_cost": 0.0,
          "tts_seconds": 15.0,
          "tts_cost": 0.0018,
          "tts_unit_cost": 0.0072,
          "feature_seconds": 0.0,
          "feature_cost": 0.0000,
          "rest_to": "tel:443069990123",
          "rest_from": "443069999876",
          "rest_initial_token": "9176280",
          "rest_log_filename": "2019/03/14/rest_14_15_49_100d73cb12cbf845.8089.log"
        }
      }

    https://ws.aculabcloud.net/application_status?application_instance_id=049136ca36e44662.200476

    Response:

      {
        "cdrs":
        {
          "049136ca36e44662.209560.914358273":
          {
            "dir": "out",
            "channel_type": "p",
            "destination_address": "tel:443069990123",
            "originating_address": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
            "call_initiated_time": 1366725525.8599,
            "call_connected_time": 1366725535.1099,
            "call_hangup_time": 1366725536.31,
            "call_initiated_datetime": "2013-04-23_13:58:45",
            "call_connected_datetime": "2013-04-23_13:58:55",
            "call_hangup_datetime": "2013-04-23_13:58:56",
            "duration": 1.2,
            "joined": 0.0,
            "hangup_cause": "NORMAL(200)"
          }
        },
        "errs":
        {
            "0":
            {
              "error_code": "2008",
              "error_text": "UAS application [outbound_reminder]. app_args [441908273800]. started ok. completion status [-111]",
              "error_link": "https://cloud.aculab.com/documents/cnws_errors?error=2008"
            }
        },
        "adr":
        {
          "application_instance_id": "049136ca36e44662.200476",
          "application_name": "outbound_test",
          "uas_ip_address": "123.100.100.223",
          "uas_name": "Prod001",
          "extra_channel_count": 0,
          "fax": "false",
          "outbound_parameters": "443069990123;hel...",
          "application_parameters": "443069990123",
          "start_datetime": "2013-04-23_13:58:45",
          "stop_datetime": "2013-04-23_13:58:56",
          "start_time": 1366725525.81,
          "stop_time": 1366725536.67,
          "duration": 10.86,
          "exit_status": -111,
          "costs_valid": "true",
          "total_cost": 0.067,
          "pstn_cost": 0.0,
          "platform_cost": 0.01,
          "tollfree_cost": 0.057,
          "extra_cost": 0.0,
          "tts_seconds": 15,
          "tts_cost": 0.0018,
          "tts_unit_cost": 0.0072,
          "feature_seconds": 0.0,
          "feature_cost": 0.0000,
          "rest_to": "",
          "rest_from": "",
          "rest_initial_token": "",
          "rest_log_filename": ""
        }
      }