Managing Outbound Service Queues

This API provides the ability to manage the outbound service queues.

For info on starting outbound services see Starting Outbound Services.

• All Queues
• Single Queue

• Outbound Queues

  This retrieves info on all your active outbound service queues.

  Authorisation

  This API uses basic authentication, using your cloud account username and API Access Key.

  Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
  Password	:	API Access key

  Request:

  Url	:	https://ws.aculabcloud.net/service/v1/outbound_queues
  Methods	:	GET

  
  

  Response:

  A list of JSON objects each containing the following parameters:

  Parameter	Value	Description
  service_name	string	The name of the service.
  length	integer	The length of the service's queue.

  Example:

  https://ws.aculabcloud.net/service/v1/outbound_queues

  Response:

      [  
  	   {
            "service_name": "service-name-1",
            "length": 78
         },
         {
            "service_name": "service-name-2",
            "length": 112
         }
  	]

• Single Queue

  Gets queue information for a single outbound service or purges its queue of all outstanding service start requests.

  Method	URL	Description
  GET	https://ws.aculabcloud.net/service/v1/outbound/<ServiceName>/queue	Get current queue information
  DELETE	https://ws.aculabcloud.net/service/v1/outbound/<ServiceName>/queue	Purge all queued service starts

  Authorisation

  This API can be accesses using either the standard web service username & password used for services, or the service start password specific to the service.

  Using the standard web service username & password:

  Username	:	cloudID/username/outbound_service_name (e.g. 1-2-0/This email address is being protected from spambots. You need JavaScript enabled to view it./MyOutboundService)
  Password	:	outbound service password

  Or if using the service start password:

  Username	:	cloudID/username (e.g. 1-2-0/This email address is being protected from spambots. You need JavaScript enabled to view it.)
  Password	:	API Access Key

  
  

  • Get Queue Info
  • Purge Queue

  • Gets the current length of the queue associated with the service.

    Request:

    Url	:	https://ws.aculabcloud.net/service/v1/outbound/<ServiceName>/queue
    Methods	:	GET

    Response:

    A JSON object containing the following parameters:

    Parameter	Value	Description
    service_name	string	The name of the service.
    length	integer	The length of the service's queue.

    Example:

    https://ws.aculabcloud.net/service/v1/outbound/example-service/queue

    Response:

      {
        "service_name": "example-service",
        "length": 112
      }

  • Purges the current queue associated with the service. This is equivalent to calling service_cancel for each entry in the queue.

    Request:

    Url	:	https://ws.aculabcloud.net/service/v1/outbound/<ServiceName>/queue
    Methods	:	DELETE

    Response:

    A JSON object containing the following parameters:

    Parameter	Value	Description
    service_name	string	The name of the service.
    cancelled	integer	The number of queued service_starts that have been cancelled.
    service_refs	array of strings	The services references of each service that has been cancelled. A service reference is returned by service_start.

    Example:

    https://ws.aculabcloud.net/service/v1/outbound/example-service/queue

    Response:

      {
        "service_name": "example-service",
        "cancelled": 12,
    	"service_refs": [
    		"34100b7a_1.1666875127.13791",
    		"34100b7a_1.1666875127.13792",
    		"34100b7a_1.1666875127.13793",
    		"34100b7a_1.1666875127.13794",
    		"34100b7a_1.1666875127.13795",
    		"34100b7a_1.1666875127.13796",
    		"34100b7a_1.1666875127.13797",
    		"34100b7a_1.1666875127.13798",
    		"34100b7a_1.1666875127.13799",
    		"34100b7a_1.1666875127.13800",
    		"34100b7a_1.1666875127.13801",
    		"34100b7a_1.1666875127.13802"
    	]
      }

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:

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

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.

Response content

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

• List
• Get Schema
• Read
• Write
• Modify
• Delete

• 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'
      }
  }

Inbound Services

Inbound services define how inbound voice and fax calls and messages are to be handled. They define the application is going to manage the call (REST or UAS) and/or an endpoint that is going to receive notifications when a message is received.

You can create, configure and delete inbound services using the Cloud Console or use the inbound services Management API.

• Managing

speech model options

Defines the model and optional settings used for speech recognition.

Used by actions get input, play, run speech menu, start transcription and connect with a translator.

language wrappers and examples

It has the following properties:

Note: premium models are charged at a higher rate than standard models.

Messaging

Aculab Cloud lets you communicate with your customers using SMS text messages and MMS messages with multimedia content. You can purchase telephone numbers and use them to send and receive messages.

• Requirements
• Sending and receiving messages
• US-specific information

Requirements

To send and receive messages, you need:

• A Production or Premium account - if you have a Developer account, please upgrade your account.
• A telephone number on Aculab Cloud which has messaging enabled - to check this, view your purchased Telephone Numbers. If SMS/MMS is enabled for a number a green envelope icon will be displayed. You can enable/disable SMS/MMS by clicking the envelope icon. If no envelope is displayed then messaging is not supported on your number.
• A web server - so Aculab Cloud can tell you about status updates for your messages.
• Credit on your account - so you can buy a number and pay for your messages.

To receive messages, you also need:

• An Inbound Service for your number which must be able to handle messages. An Inbound Service tells Aculab Cloud how to handle incoming messages and calls to a particular number.
  
  • First, view your own Telephone Numbers.
  • Click on the service link icon to edit or create the service for your number.
  • Click the service's Messages tab and enter your url into the Notification page field. This is the URL of a page on your web server which Aculab Cloud will access to tell you when new messages arrive.

Note that, to send messages, you don't need an Outbound Service. You only need to call the managing messages web service.

• Sending Messages
• Receiving Messages

• How it works

  You pass the message to Aculab Cloud via the Managing Messages Web Service. You can do this from your browser's address bar, call the appropriate function from one of our High-Level Language Wrappers or call it direct.

  Aculab Cloud queues the message then submits it to a carrier and accesses your status_page to say that's done. The carrier accepts the message, sends it on towards the mobile phone, and Aculab Cloud accesses your status_page to tell you it's been sent.

  If you've requested a delivery report and they're supported, the phone will acknowledge receipt, the carrier passes that on to Aculab Cloud, which accesses your status page to tell you the message has been delivered.

  For more details

  See Handling status updates for details of what is sent to your status page.

  

• How it works

  A mobile phone sends a message to your number. It is received by one of our carriers, which passes it on. It's received by Aculab Cloud, which accesses your notification page to give you the message.

  How to receive messages

  When messages are received on your numbers, you can choose to be notified via pages which you host on your web server. To make this work for one of your numbers:

  • Check you've enabled messages (SMS/MMS) on that number by viewing your telephone numbers and ensuring a green envelope is displayed for the number. If a red envelope is displayed, click to change to green.
  • If you've not already done so, create an Inbound Service for the number.
  • Again if not done already, configure the number's Inbound Service by entering the URL of your web page on its Messages tab.

  For more details

  To see the content of what Aculab Cloud passes to your notification page, see Managing Messages.

  

Written on 12 July 2022.