Managing | Aculab

Managing Inbound Services

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

In the past, the only mechanism for managing inbound 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: Inbound services originally created & edited using the Cloud Console can be modified & deleted using the web services, and vice versa.

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

Method	URL	Description
GET	https://ws.aculabcloud.net/service/v1/inbound	List the services
GET	https://ws.aculabcloud.net/service/v1/schema/inbound	Get the service schema
GET	https://ws.aculabcloud.net/service/v1/inbound/<ServiceName>	Read a service
PUT	https://ws.aculabcloud.net/service/v1/inbound/<ServiceName>	Write (Create or replace) a service
PATCH	https://ws.aculabcloud.net/service/v1/inbound/<ServiceName>	Modify a service
DELETE	https://ws.aculabcloud.net/service/v1/inbound/<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).

For inbound services, it is possible to call the Write web service without supplying a configuration at all. This will result in a configuration being written with all of its options set to default values.

Using the Get Schema web service, you can retrieve a copy of the inbound 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 inbound services.

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

URL	:	https://ws.aculabcloud.net/service/v1/inbound
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/inbound

Response:

{
    "services" : [
            {
                "name" : "MyVoicemailService",
                "target" : "http://11.222.33.44:50080/my_voicemail_first_page",
                "description" : "This is the configuration for MyVoicemailService"
            },
            {
                "name" : "MyOtherInboundService",
                "target" : "http://11.222.33.44:50080/OtherInboundService",
                "description" : "Another great inbound service"
            },
            ...
        ]
}

Get Schema

This retrieves the inbound 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/inbound
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 inbound service configuration schema.

Example:

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

Response:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Aculab Cloud Inbound Service Configuration Schema",
    "description": "This schema is used to validate an inbound 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": {...},
        "description": {...},
        "extra_channels": {...},
        "g729": {...},
        "maintenance_message": {...},
        "outbound_call_constraints": {...},
        "application_type": {...},
        "uas": {...},
        "rest": {...},
        "messages": {...},
        "fax": {...}
    },
    "definitions": {...},
    "allOf": [...],
    "additionalProperties": false
}

Read

This retrieves an existing inbound 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/inbound/<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 inbound service configuration.

Example:

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

Response:

{
    "enabled": true,
    "description": "This is configuration for MyVoicemailService",
    "extra_channels": 0,
    "g729": false,
    "maintenance_message": {...},
    "outbound_call_constraints": {...},
    "application_type": "REST",
    "uas": {...},
    "rest": {
        "first_page": {
            "address": "http://11.222.33.44:50080/my_voicemail_first_page",
            "method": "POST"
        },
        "final_page": {
            "address": "http://11.222.33.44:50080/my_voicemail_final_page",
            "method": "POST"
        },
        "error_page": {
            "address": "http://11.222.33.44:50080/my_voicemail_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,
        "early_media": false,
        "ring_time": 2
    },
    "messages": {...},
    "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/inbound/management?target=service_action_tabs&tab-id=read'
    },
    'request': {
        'datetime': '2022-07-22_14:50:47',
        'url': '/service/v1/inbound/MyVoicemailService'
    }
}

Write

This writes an inbound service with the name as supplied in the URL and (Optionally) a configuration supplied within the body of the request. If the name does not exist in the list of inbound services, then a new service is created with the supplied configuration. If the name does exist in the list of inbound services, then the configuration of the existing service is replaced by the supplied configuration.

If a configuration is supplied, any option that is omitted from the configuration will be set to its default value. If a configuration is not supplied, then a service will be created with all options set to their default values.

If you are supplying a configuration, ensure the request's Content-Type header is set to 'application/json'. If you are not supplying a configuration, then ensure the request's Content-Length header is set to '0'.

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

URL	:	https://ws.aculabcloud.net/service/v1/inbound/<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 inbound service configuration.

Example 1 - Create a new service without supplying a configuration:

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

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

Response:

You will receive a JSON object in the body of a 201 response. The JSON object is the configuration for the newly created 'MyFirstInboundService'. As the request body did not contain a configuration, all the options will have been set to their default values:

{
    "enabled": true,
    "description": null,
    "extra_channels": 0,
    "g729": false,
    "maintenance_message": {...},
    "outbound_call_constraints": {...},
    "application_type": "UAS",
    "uas": {
        "application_name": null,
        "application_parameters": null,
        "fallback_message": {...}
    },
    "rest": {
        "first_page": {
            "address": null,
            "method": "POST"
        },
        "final_page": {
            "address": null,
            "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,
        "early_media": false,
        "ring_time": 2
    },
    "messages": {...},
    "fax": {...}
}

Example 2 - Create a new service:

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

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

With the following JSON in the body of the request:
{
    "description"      : "This is my inbound 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 configuration for the newly created 'MySecondInboundService'. The options that were not set in the supplied configuration will be set to their default values:

{
    "enabled": true,
    "description": "This is my inbound REST service",
    "extra_channels": 0,
    "g729": false,
    "maintenance_message": {...},
    "outbound_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,
        "early_media": false,
        "ring_time": 2
    },
    "messages": {...},
    "fax": {...}
}

Example 3 - Replace the configuration of an existing service:

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

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

With the following JSON in the body of the request:
{
    "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 200 response. The JSON object contains the new configuration for the existing 'MySecondInboundService'. The options that were not set in the supplied configuration will be set to their default values:

{
    "enabled": true,
    "description": null,
    "extra_channels": 0,
    "g729": false,
    "maintenance_message": {...},
    "outbound_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,
        "early_media": false,
        "ring_time": 2
    },
    "messages": {...},
    "fax": {...}
}

Example 4 - Failure to write a service due to configuration mistakes:

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

With the following JSON in the body of the request:
{
    "description"      : "This is my inbound REST service",
    "application_type" : "ROAST",
    "rest" : {
        "first_page" : {
            "address" : "hello"
        },
        "final_page" : {
            "address" : "http://11.222.33.44:50080/my_final_page"
        }
    }
}

Response:

{
    "error": {
        "code": "HTTP 400",
        "text": "Failed to validate configuration, see details for more information.",
        "details": [
            "application_type 'ROAST' is not one of ['UAS', 'REST'].", 
            "rest.first_page.address 'hello' must be prefixed with http:// or https:// and must not contain any of the following characters: caret, backslash, quotation mark, apostrophe or angled brackets.",
            "rest.first_page.address 'hello' is too short."
        ], 
        "datetime": "2022-07-22_14:05:58",
        "link": "https://www.aculab.com/cloud/web-services/services/inbound/management?target=service_action_tabs&tab-id=write"
    },
    "request": {
        "datetime": "2022-07-22_14:05:58",
        "url": "/service/v1/inbound/MyExampleInboundService"
    }
}

Modify

This modifies the configuration of an existing inbound 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 inbound 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/inbound/<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 inbound service configuration.

Example:

Assume that an inbound service called 'MyRESTInboundService' exists that has the following configuration:

{
    "enabled": true,
    "description": "This is my inbound REST service",
    "extra_channels": 0,
    "g729": false,
    "maintenance_message": {...},
    "outbound_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,
        "early_media": false,
        "ring_time": 2
    },
    "messages": {...},
    "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/inbound/MyRESTInboundService

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 modified configuration for 'MyRESTInboundService':

{
    "enabled": true,
    "description": "This is my inbound REST service",
    "extra_channels": 0,
    "g729": false,
    "maintenance_message": {...},
    "outbound_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,
        "early_media": false,
        "ring_time": 2
    },
    "messages": {...},
    "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/inbound/management?target=service_action_tabs&tab-id=modify'
    },
    'request': {
        'datetime': '2022-07-22_14:40:32',
        'url': '/service/v1/inbound/MyRESTInboundService'
    }
}

Delete

This deletes an inbound 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/inbound/<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/inbound/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/inbound/management?target=service_action_tabs&tab-id=delete'
    },
    'request': {
        'datetime': '2022-07-22_14:45:09',
        'url': '/service/v1/inbound/SomethingOrOther'
    }
}

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 service without supplying a configuration:

Response:

Example 2 - Create a new service:

Response:

Example 3 - Replace the configuration of an existing service:

Response:

Example 4 - Failure to write a service due to configuration mistakes:

Response:

Modify

Returns on success:

Example:

Response:

Delete

Returns on success:

Example:

Contact Aculab