Managing | Aculab

Managing Outbound Services

This section covers the web services for listing, reading, writing, modifying and deleting outbound services.

In the past, the only mechanism for managing outbound services was to use the online Cloud Console. These web services provide an alternative mechanism, giving the same level of functionality without any manual interaction with the Cloud Console. What's more, the two mechanisms are interchangeable: Outbound services originally created & edited using the Cloud Console can be modified & deleted using the web services, and vice versa.

The outbound web services are accessed using the following URL paths:

Method	URL	Description
GET	https://ws.aculabcloud.net/service/v1/outbound	List the services
GET	https://ws.aculabcloud.net/service/v1/schema/outbound	Get the service schema
GET	https://ws.aculabcloud.net/service/v1/outbound/<ServiceName>	Read a service
PUT	https://ws.aculabcloud.net/service/v1/outbound/<ServiceName>	Write (Create or replace) a service
PATCH	https://ws.aculabcloud.net/service/v1/outbound/<ServiceName>	Modify a service
DELETE	https://ws.aculabcloud.net/service/v1/outbound/<ServiceName>	Delete a service

The URL paths for the Read, Write, Modify and Delete web services are the same and it is the HTTP request method that differentiates between them.

To express what configuration options are set when using the Write or Modify web service, a fully complete or partially complete configuration can be supplied within the body of the HTTP request. When calling the Write web service and supplying a partially complete configuration, default values will be assumed for those options that are omitted. When calling the Modify web service and supplying a partially complete configuration, existing values will be assumed for those options are that omitted (The new configuration is effectively merged into the existing configuration).

You must supply a configuration when creating an outbound service. This is because outbound configurations have a few mandatory options that must be known to the Cloud Server when a new outbound service is created. See the Write web service for more details.

Using the Get Schema web service, you can retrieve a copy of the outbound service configuration schema. This schema is used by the cloud server when it processes configurations received in web service requests. Should the cloud server encounter validation errors, the request will fail and all errors will be listed in an HTTP request error response. The schema can also be used locally, to ensure a tailor-made configuration validates before sending it in a web service request. Whilst it is not essential to do this, it can help gain a better understanding of the schema internals and save on the amount of requests sent to the same web service before your configuration is accepted.

For more information about JSON schemas, visit The home of JSON Schema. See the implementations section for a list of all language specific validators, as well as some online validators. All the online validators are quite similar and simple to use (Paste the schema into one text box, paste a configuration into another text box and click a button to validate).

Response content

All web services in this API return response content of type "application/json".

This is a low level API. For information on higher level APIs see the Web Services Language Wrappers

List

This lists the names of all outbound services.

You need to supply your account username and API access key in the basic authorisation string.

URL	:	https://ws.aculabcloud.net/service/v1/outbound
Methods	:	GET
Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	Your API Access Key

Returns on success:

A JSON object within the body of a 200 response. The object contains the following parameter:

Parameter	Value	Description
services	array	An array of service description objects.

Where each service description object contains the following parameters:

Parameter	Value	Description
name	string	The name of the service.
target	string	A UAS application or a REST API page that the service targets.
description	string	A description of the service.

Example:

(GET) https://ws-1-2-0.aculabcloud.net/service/v1/outbound

Response:

{
    "services" : [
            {
                "name" : "MyWakeUpCallService",
                "target" : "http://11.222.33.44:50080/my_wakeupcall_first_page",
                "description" : "This is the configuration for MyWakeUpCallService"
            },
            {
                "name" : "MyOtherOutboundService",
                "target" : "http://11.222.33.44:50080/OtherOutboundService",
                "description" : "Another great outbound service"
            },
            ...
        ]
}

Get Schema

This retrieves the outbound service configuration schema. Tailor-made configurations can be validated against this schema, before including them into a Write or Modify web service request. The same schema is also used by the Cloud Server when it is processing configurations received in Write or Modify web service requests.

The schema describes all possible configuration options and constraints of the value that each option can be set to. For instance, the expected value type (integer or string), the maximum length (if string), the number range (if integer) etc... The schema also describes relationships that certain options have with each other, where the allowed value of one option is effected by the value of another option.

Your account settings influence the allowed values of certain configuration options. Also, over time Aculab may decide to add new options or change the constraints of an existing option. For this reason, it is best practice to always validate against a recently retrieved schema.

You need to supply your account username and API access key in the basic authorisation string.

URL	:	https://ws.aculabcloud.net/service/v1/schema/outbound
Methods	:	GET
Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	Your API Access Key

Returns on success:

A JSON object within the body of a 200 response. The JSON object is the outbound service configuration schema.

Example:

(GET) https://ws-1-2-0.aculabcloud.net/service/v1/schema/outbound

Response:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Aculab Cloud Outbound Service Configuration Schema",
    "description": "This schema is used to validate an outbound service configuration before it is sent to the Cloud Server in the body of a 'Write' or 'Modify' web service request.",
    "type": "object",
    "properties": {
        "enabled": {...},
        "service_password": {...},
        "description": {...},
        "extra_channels": {...},
        "g729": {...},
        "call_constraints": {...},
        "application_type": {...},
        "uas": {...},
        "rest": {...},
        "fax": {...}
    },
    "definitions": {...},
    "allOf": [...],
    "additionalProperties": false
}

Read

This retrieves an existing outbound service configuration. The retrieved configuration will contain every configuration option and its setting.

You need to supply your account username and API access key in the basic authorisation string.

URL	:	https://ws.aculabcloud.net/service/v1/outbound/<ServiceName>
Methods	:	GET
Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	Your API Access Key

Returns on success:

A JSON object within the body of a 200 response. The JSON object is the outbound service configuration.

Example:

(GET) https://ws-1-2-0.aculabcloud.net/service/v1/outbound/MyWakeUpCallService

Response:

{
    "enabled": true,
    "service_password": "p@$$w0rd",
    "description": "This is the configuration for MyWakeUpCallService",
    "extra_channels": 0,
    "g729": false,
    "call_constraints": {...},
    "application_type": "REST",
    "uas": {...},
    "rest": {
        "first_page": {
            "address": "http://11.222.33.44:50080/my_wakeupcall_first_page",
            "method": "POST"
        },
        "final_page": {
            "address": "http://11.222.33.44:50080/my_wakeupcall_final_page",
            "method": "POST"
        },
        "error_page": {
            "address": "http://11.222.33.44:50080/my_wakeupcall_error_page",
            "method": "POST"
        },
        "api_version": "2.0",
        "application_parameters": null,
        "tts_voice": "English UK Female Polly Amy",
        "authentication": {...},
        "call_recording": {...},
        "max_call_duration": 240,
        "answer_timeout": 30,
        "call_configuration": {...}
    },
    "fax": {...}
}

If unsuccessful, you will receive an HTTP error response containing a JSON object. For example:

{
    'error': {
        'code': 'HTTP 404',
        'text': 'The service name does not exist',
        'datetime': '2022-07-22_14:50:47',
        'link': 'https://www.aculab.com/cloud/web-services/services/outbound/management?target=service_action_tabs&tab-id=read'
    },
    'request': {
        'url': '/service/v1/outbound/MyWakeUpCallService',
        'datetime': '2022-07-22_14:50:47'
    }
}

Write

This writes a new outbound service with the name as supplied in the URL and a configuration supplied within the body of the request, with the Content-Type header set to 'application/json'. If the name does not exist in the list of outbound services, then a new service is created with the supplied configuration. If the name does exist in the list of outbound services, then the configuration of the existing service is replaced by the supplied configuration.

It is not possible to write an outbound service without providing a configuration that contains a few mandatory options. At a bare minimum, the configuration needs to contain a service_password and either a uas.application_name or a rest.first_page.address (Depending on if you have set application_type to 'UAS' (Which it is by default) or 'REST'). Options that are omitted from the configuration will be set to their default values.

You need to supply your account username and API access key in the basic authorisation string.

URL	:	https://ws.aculabcloud.net/service/v1/outbound/<ServiceName>
Methods	:	PUT
Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	Your API Access Key

Returns on success:

A JSON object within the body of either a 201 response (If the service was created) or a 200 response (If the service was replaced). The JSON object is the newly written outbound service configuration.

Example 1 - Create a new UAS service:

In this example, assume 'MyFirstOutboundService' does not already exist:

(PUT) https://ws-1-2-0.aculabcloud.net/service/v1/outbound/MyFirstOutboundService

With the following JSON in the body of the request:
{
    "description"      : "This is my outbound UAS service",
    "service_password" : "p@$$w0rd",
    "uas" : {
        "application_name" : "my_uas_app"
    }
}

Response:

You will receive a JSON object in the body of a 201 response. The JSON object is the configuration for the newly created 'MyFirstOutboundService'. The options that were not set in the supplied configuration will be set to their default values:

{
    "enabled": true,
    "service_password": "p@$$w0rd",
    "description": "This is my outbound UAS service",
    "extra_channels": 0,
    "g729": false,
    "call_constraints": {...},
    "application_type": "UAS",
    "uas": {
        "application_name": "my_uas_app",
        "application_parameters": null
    },
    "rest": {...},
    "fax": {...}
}

Example 2 - Create a new REST service:

In this example, assume 'MySecondOutboundService' does not already exist:

(PUT) https://ws-1-2-0.aculabcloud.net/service/v1/outbound/MySecondOutboundService

With the following JSON in the body of the request:
{
    "service_password" : "p@$$w0rd",
    "description" : "This is my outbound REST service",
    "application_type" : "REST",
    "rest" : {
        "first_page" : {
            "address" : "http://11.222.33.44:50080/my_first_page"
        },
        "final_page" : {
            "address" : "http://11.222.33.44:50080/my_final_page"
        }
    }
}

Response:

You will receive a JSON object in the body of a 201 response. The JSON object is the configuration for the newly created 'MySecondOutboundService'. The service options that were not set in the supplied configuration will be set to their default values:

{
    "enabled": true,
    "service_password": "p@$$w0rd",
    "description": "This is my outbound REST service",
    "extra_channels": 0,
    "g729": false,
    "call_constraints": {...},
    "application_type": "REST",
    "uas": {...},
    "rest": {
        "first_page": {
            "address": "http://11.222.33.44:50080/my_first_page",
            "method": "POST"
        },
        "final_page": {
            "address": "http://11.222.33.44:50080/my_final_page",
            "method": "POST"
        },
        "error_page": {
            "address": null,
            "method": "POST"
        },
        "api_version": "2.0",
        "application_parameters": null,
        "tts_voice": "English UK Female Polly Amy",
        "authentication": {...},
        "call_recording": {...},
        "max_call_duration": 240,
        "answer_timeout": 30,
        "call_configuration": {...}
    },
    "fax": {...}
}

Example 3 - Replace the configuration of an existing service:

In this example, assume 'MySecondOutboundService' already exists and configured as shown above (In the response of the previous example):

(PUT) https://ws-1-2-0.aculabcloud.net/service/v1/outbound/MySecondOutboundService

With the following JSON in the body of the request:
{
    "service_password" : "p@$$w0rd",
    "application_type" : "REST",
    "rest" : {
        "first_page" : {
            "address" : "http://11.222.33.44:50080/my_first_page"
        },
        "error_page" : {
            "address" : "http://11.222.33.44:50080/my_error_page"
        }
    }
}

Response:

You will receive a JSON object in the body of a 201 response. The JSON object contains the new configuration for the existing 'MySecondOutboundService'. The service options that were not set in the supplied configuration will be set to their default values:

{
    "enabled": true,
    "service_password": "p@$$w0rd",
    "description": null,
    "extra_channels": 0,
    "g729": false,
    "call_constraints": {...},
    "application_type": "REST",
    "uas": {...},
    "rest": {
        "first_page": {
            "address": "http://11.222.33.44:50080/my_first_page",
            "method": "POST"
        },
        "final_page": {
            "address": null,
            "method": "POST"
        },
        "error_page": {
            "address": "http://11.222.33.44:50080/my_final_page",
            "method": "POST"
        },
        "api_version": "2.0",
        "application_parameters": null,
        "tts_voice": "English UK Female Polly Amy",
        "authentication": {...},
        "call_recording": {...},
        "max_call_duration": 240,
        "answer_timeout": 30,
        "call_configuration": {...}
    },
    "fax": {...}
}

Example 4 - Failure to write a service due to an incomplete configuration:

(PUT) https://ws-1-2-0.aculabcloud.net/service/v1/outbound/MyExampleOutboundService

With the following JSON in the body of the request:
{
    "description"      : "This is my outbound REST service",
    "application_type" : "REST"
}

Response:

{
    "error": {
        "code": "HTTP 400",
        "text": "Failed to validate configuration, see details for more information.",
        "details": [
            "service_password None is not of type 'string'. For REST, you must provide a first_page, a service_password and you can not enable fax receive.",
            "rest.first_page.address None is not of type 'string'. For REST, you must provide a first_page, a service_password and you can not enable fax receive."
        ],
        "datetime": "2022-07-22_16:28:25",
        "link": "https://www.aculab.com/cloud/web-services/services/outbound/management?target=service_action_tabs&tab-id=write"
    },
    "request": {
        "url": "/service/v1/outbound/MyExampleOutboundService",
        "datetime": "2022-07-22_16:28:24"
    }
}

Modify

This modifies the configuration of an existing outbound service. The name of the service is supplied in the URL. The configuration containing the modified options is supplied within the body of the request, with the Content-Type header set to 'application/json'.

It is not necessary to specify all possible service options in the configuration (You only need to specify the options you want to modify).

When processing a Modify web service request, the Cloud Server iterates through each option in the existing configuration (The configuration that is returned after calling the Read web service). If the same option exists in the supplied configuration, then the value supplied replaces the existing value. The merged configuration is then validated by the outbound service schema before finally becoming the active.

You need to supply your account username and API access key in the basic authorisation string.

URL	:	https://ws.aculabcloud.net/service/v1/outbound/<ServiceName>
Methods	:	PATCH
Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	Your API Access Key

Returns on success:

A JSON object within the body of 200 response. The JSON object is the modified outbound service configuration.

Example:

Assume that an outbound service called 'MyRESTOutboundService' exists that has the following configuration:

{
    "enabled": true,
    "service_password": "p@$$w0rd",
    "description": "This is my outbound REST service",
    "extra_channels": 0,
    "g729": false,
    "call_constraints": {...},
    "application_type": "REST",
    "uas": {...},
    "rest": {
        "first_page": {
            "address": "http://11.222.33.44:50080/my_first_page",
            "method": "POST"
        },
        "final_page": {
            "address": "http://11.222.33.44:50080/my_final_page",
            "method": "POST"
        },
        "error_page": {
            "address": null,
            "method": "POST"
        },
        "api_version": "2.0",
        "application_parameters": null,
        "tts_voice": "English UK Female Polly Amy",
        "authentication": {...},
        "call_recording": {...},
        "max_call_duration": 240,
        "answer_timeout": 30,
        "call_configuration": {...}
    },
    "fax": {...}
}

This is how the Modify web service might used to remove the rest.final_page.address and add a rest.first_page.address:

(PATCH) https://ws-1-2-0.aculabcloud.net/service/v1/outbound/MyRESTOutboundService

With the following JSON in the body of the request:
{
    "rest" : {
        "final_page" : {
            "address" : null
        },
        "error_page" : {
            "address" : "http://11.222.33.44:50080/my_error_page"
        }
    }
}

Response:

You will receive a JSON object in the body of a 200 response. The JSON object is the is the modified configuration for 'MyRESTOutboundService':

{
    "enabled": true,
    "service_password": "p@$$w0rd",
    "description": "This is my outbound REST service",
    "extra_channels": 0,
    "g729": false,
    "call_constraints": {...},
    "application_type": "REST",
    "uas": {...},
    "rest": {
        "first_page": {
            "address": "http://11.222.33.44:50080/my_first_page",
            "method": "POST"
        },
        "final_page": {
            "address": null,
            "method": "POST"
        },
        "error_page": {
            "address": "http://11.222.33.44:50080/my_error_page",
            "method": "POST"
        },
        "api_version": "2.0",
        "application_parameters": null,
        "tts_voice": "English UK Female Polly Amy",
        "authentication": {...},
        "call_recording": {...},
        "max_call_duration": 240,
        "answer_timeout": 30,
        "call_configuration": {...}
    },
    "fax": {...}
}

If unsuccessful, you will receive an HTTP error response containing a JSON object. For example:

{
    'error': {
        'code': 'HTTP 404',
        'text': 'The service name does not exist',
        'datetime': '2022-07-22_14:40:32',
        'link': 'https://www.aculab.com/cloud/web-services/services/outbound/management?target=service_action_tabs&tab-id=modify'
    },
    'request': {
        'url': '/service/v1/outbound/MyRESTOutboundService',
        'datetime': '2022-07-22_14:40:32'
    }
}

Delete a service

This deletes an outbound service, the name of which is supplied in the URL.

You need to supply your account username and API access key in the basic authorisation string.

URL	:	https://ws.aculabcloud.net/service/v1/outbound/<ServiceName>
Methods	:	DELETE
Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	Your API Access Key

Returns on success:

204 (No Content) status code.

Example:

(DELETE) https://ws-1-2-0.aculabcloud.net/service/v1/outbound/SomethingOrOther

If unsuccessful, you will receive an HTTP error response containing a JSON object. For example:

{
    'error': {
        'code': 'HTTP 404',
        'text': 'The service name does not exist',
        'datetime': '2022-07-22_14:45:09',
        'link': 'https://www.aculab.com/cloud/web-services/services/outbound/management?target=service_action_tabs&tab-id=delete'
    },
    'request': {
        'url': '/service/v1/outbound/SomethingOrOther',
        'datetime': '2022-07-22_14:45:09'
    }
}

Cloud documentation

Response content

List

Returns on success:

Example:

Response:

Get Schema

Returns on success:

Example:

Response:

Read

Returns on success:

Example:

Response:

Write

Returns on success:

Example 1 - Create a new UAS service:

Response:

Example 2 - Create a new REST service:

Response:

Example 3 - Replace the configuration of an existing service:

Response:

Example 4 - Failure to write a service due to an incomplete configuration:

Response:

Modify

Returns on success:

Example:

Response:

Delete a service

Returns on success:

Example:

Contact Aculab