Informizely customer feedback surveys
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

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

    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

    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

    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.
    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.
    extra_channel_countintegerthe number of extra channels configured for the application instance.
    faxstring"true" if fax is enabled on the service. Else "false".
    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.
    start_timefloatthe time the application instance started.
    stop_timefloatthe time the application instance stopped.
    start_datetimestringthe time the application instance started formatted as YYYY-MM-DD_hh:mm:ss.
    stop_datetimestringthe time the application instance stopped formatted as YYYY-MM-DD_hh:mm:ss.
    durationfloatthe duration of the application instance in seconds.
    exit_statusintegerthe numeric return code passed back by the application instance
    costs_validstring"true" if the costs provided are valid. Else "false".
    pstn_costfloatthe cost of any outbound PSTN telephone calls.
    platform_costfloatthe Aculab Cloud platform cost for the instance.
    tollfree_costfloatthe cost of any toll free telephone calls.
    extra_costfloatthe cost of any extra channel usage.
    tts_costfloatthe cost of any Text-To-Speech used.
    total_costfloatthe total cost for the application instance
    tts_secondsfloatthe duration of any Text-To-Speech used in seconds.
    tts_unit_costfloatthe per minute cost of any Text-To-Speech used.
    feature_secondsfloatthe total duration of any features used in seconds.
    feature_costfloatthe total cost of any features used.
    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.
    rest_log_filenamestringthe 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
    dirstringthe direction of the call ("in" or "out").
    channel_typestring"p" for a primary call channel, "x" for an extra channel.
    originating_addressstringthe address from which the call was made.
    destination_addressstringthe target destination of the call.
    durationfloatthe duration of the call in seconds.
    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.
    hangup_causestringthe reason why the call was disconnected.
    joinedfloatthe 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_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
    application_instance_idstringthe application instance's unique ID.
    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".
    start_timefloatthe time at which the feature started.
    stop_timefloatthe time at which the feature stopped.
    start_datetimestringthe time at which the feature started formatted as YYYY-MM-DD_hh:mm:ss.
    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.
    call_idstringthe call id for the call on which the feature was used.
    audio_pathstringa 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": "443069999876@sip-0-0-0.aculab.com",
            "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": "443069990123@sip-0-0-0.aculab.com",
            "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": ""
        }
      }