Outbound Calls

• Placing an outbound call
• Call prefixes
• Blocked prefixes
• Allowed prefixes
• Price cap
• Call destination
• Outbound telephony providers

Placing an outbound call

An outbound call can be placed on Aculab Cloud by calling service_start which takes the name of one of your Outbound Services and a telephone number or SIP address for the call destination. If the Outbound Service has been written as a UAS application, the service starts an instance of the UAS application which then controls when to make the outbound call. For REST, the service makes the outbound call and starts the REST application once the call is answered.

If the call destination is a telephone number the call uses an outbound telephony provider to route the call. If it is a SIP address then the call can be made directly to the SIP endpoint.

For telephone numbers you must specify a valid Caller ID (you can set this in the Cloud Console's Settings / Caller IDs page).

You can use Live Speaker Detection, also known as Answering Machine Detection (AMD), to establish how the call has been answered. There are also some best practices that can be followed.

Note that, due to the way in which the telephone network works, if the called party of an outbound call hangs up, the Aculab Cloud may not generally be informed of this immediately and, therefore, cannot guarantee to inform your application in a timely manner. So, we strongly recommend that you write your application to interact with the called party and, in the event of repeated no response, hang up the call.

Call prefixes

When specifying telephone numbers and sip addresses Aculab Cloud will treat anything containing only digits, optionally separated by a single '-', as a telephone number and everything else as a SIP address.

One of the following prefixes can be used to declare a specific type of number/address.

Prefix	Description	Example
tel	a telephone or cell (mobile) number	tel:441908273800
sip	a SIP username@address	sip:contact@example.com
loc	an inbound service hosted on the same cloud region	loc:my_inbound_service
webrtc	a WebRTC client identified by the supplied client ID	webrtc:clientId
con	a conference room name	con:MyConferenceRoom

When using the tel prefix for a call destination, the full international number must be supplied. This must not contain any leading '0'. The leading '+' is optional. The call will be placed with Aculab's default providers. Aculab Cloud does not support calling premium rate numbers via our outbound provider.

Examples:

"443069990123" is equivalent to "tel:443069990123"
"bob@acompany.com" is equivalent to "sip:bob@acompany.com"
"loc:MyInboundService" for an inbound service named "MyInboundService"
"webrtc:Client7356" for a webRTC client with id "Client7356"
"con:MyConferenceRoom" for a conference room name "MyConferenceRoom"

Blocked prefixes

You can set a list of blocked prefixes on your account via Settings. Outbound calls using Aculab's provider to numbers that start with any of these prefixes will fail with a code of -103.

On each of your inbound and outbound services you can override this list by specifying a set a list of blocked prefixes specific to that service from the Outbound Calls section of the General tab.

Example:

Blocked prefix: 44

- blocks calls to numbers starting with 44

Allowed prefixes

You can set a list of allowed prefixes on your account via Settings. Outbound calls using Aculab's provider to numbers that start with any of these prefixes will be allowed through, overriding any relevant blocked prefix.

On each of your inbound and outbound services you can override this list by specifying a set a list of allowed prefixes specific to that service from the Outbound Calls section of the General tab.

Example:

Blocked prefix: 44
Allowed prefix: 447

- allows calls to numbers starting with 447, but blocks calls to all other 44 numbers

Price cap

You can set a USD/min price cap on the rate for each outbound call that you make on your account that uses Aculab's provider. You can modify this in Settings. Outbound calls that have a price rate that exceeds this will fail with a code of -103.

On each of your inbound and outbound services you can override this account default by specifying a price cap specific to that service from the Outbound Calls section of the General tab.

The maximum price cap you can set is 0.5 USD/min. If you want to raise this limit please contact us.

Call destination

The type of your application determines how you specify the call destination:

• REST Applications
• UAS Applications

• For REST applications, you specify your call destinations in rest_calls, a JSON array of objects each with a 'to' property, and a 'from' property for the caller id. An application instance will be created for each object in the array.

  Examples:

  service_start?rest_calls=[{ "to" : "443069990123", "from" : "443069999876"}, { "to" : "bob@acompany.com" }]
  service_start?rest_calls=[{ "to" : "loc:MyInboundService"}, { "to" : "webrtc:Client7356" }]

  Aculab Cloud makes the outbound call and starts the REST application once the call is answered.

• For UAS applications, you specify a list of data strings in outbound_parameters. One application will be started for each data string in the list and receive the data string in its outbound_parameters argument. You are free to pass any information, such as call destinations in each data string. If specifying more than one data string, the list will be delimited by a character you specify as an additional argument

  Examples:

  service_start?outbound_parameters=443069990123;443069999876,bob@acompany.com&delimiter=,
  service_start?outbound_parameters=tel:443069990123;tel:443069999876,sip:bob@acompany.com&delimiter=,
  service_start?outbound_parameters=webrtc:Client7356

  The UAS application then uses one of the high-level UAS APIs to make an outbound call.

  Examples:

  (C#) channel.Call("443069990123", "443069999876");
  (C#) channel.Call("webrtc:Client7356");
  (C#) channel.CallInboundService("MyInboundService");
  (Python) channel.call("443069990123", call_from="443069999876")
  (Python) channel.call("webrtc:Client7356")
  (Python) channel.call_inbound_service("MyInboundService")

Outbound telephony providers

Outbound telephone calls placed via Aculab's provider will be charged to your account. In addition to using Aculab's default outbound telephony provider, it is possible to add your own. If you'd like to add an outbound provider to the list and manage their billing yourself, you'll need to contact us in order to supply the connection details. There may be a charge for this facility.

When signed in, the current list of available providers will be listed here. Each entry in the list has a selector number associated with it.

In this example two providers have been added to the list in addition to the default Aculab provider.

Selector	Provider Name
0	aculab
1	providerA
2	providerB

The selector number is a zero-based digit, used as a prefix that determines the provider that should be used. The default provider is aculab and unless the destination address is modified calls will be routed to Aculab's default provider. So a destination address of tel:12225551234 will go via aculab.

Prefixing the destination number with 0 as the selector number will also use aculab as the provider, eg tel:0-12225551234.

To change the provider to providerA the selector number 1 must be used, tel:1-12225551234. Other providers in the list can be selected in the same way.