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 (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 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
    outbound_parameters 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. The count and delimiter parameters that can be supplied to service_start for a UAS application are ignored. For further details see REST API: How to start your Outbound Web App.

    Returns:

    A JSON array of unique service invocation reference IDs.

    Example:

    https://ws.aculabcloud.net/service_start?outbound_parameters= [ { "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 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:

    A JSON object containing the detailed status of the corresponding application instance. This contains three parts: "adr", the application data record; "cdrs", the call data records; and "errs", the error reports.

    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.
    exit_status integer the numeric return code passed back by the application instance
    start_time float the time at which the application instance started.
    stop_time float the time at which the application instance stopped.
    duration float the duration of the application instance in seconds.
    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.
    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".
    total_cost float the total cost for the application instance
    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.
    costs_valid string "true" if the costs provided are valid. Else "false".

    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, "e" 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_connected_time float the time at which the call became connected.
    call_hangup_time float the time at which the call was hung up.
    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.

    Example:

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

    Response:

      {
        "cdrs":
        {
          "049136ca36e44662.209560.914358273":
          {
            "originating_address": "441908273800@sip-0-0-0.aculab.com",
            "call_hangup_time": 1366725536.31,
            "joined": 0.0,
            "channel_type": "p",
            "call_initiated_time": 1366725525.8599,
            "duration": 1.2,
            "destination_address": "tel:447555555555",
            "hangup_cause": "NORMAL(200)",
            "dir": "out",
            "call_connected_time": 1366725535.1099
          }
        },
        "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":
        {
          "fax": "false",
          "exit_status": -111,
          "total_cost": 0.067,
          "extra_channel_count": 0,
          "costs_valid": "true",
          "tollfree_cost": 0.057,
          "start_time": 1366725525.81,
          "application_instance_id": "049136ca36e44662.200476",
          "application_name": "outbound_test",
          "pstn_cost": 0.0,
          "outbound_parameters": "447555555555;hel...",
          "stop_time": 1366725536.67,
          "platform_cost": 0.01,
          "duration": 10.86,
          "extra_cost": 0.0,
          "application_parameters": "441908273800"
        }
      }