1. Introduction
    1. Notification
    2. One Time Password (OTP)
    3. Request DTMF
  2. Authentication
  3. Getting Started
    1. Swagger
    2. Postman
  4. The Apps
    1. Notification App
      1. Notification App callback
    2. One Time Password (OTP) App
      1. One Time Password (OTP) App
    3. Request-DTMF App
      1. Request-DTMF App callback
    4. Result codes
  5. Audio and voices
    1. Custom audio files
    2. Custom audio files for the OTP App
    3. Text-To-Speech
  6. Voicemail detection

Introduction

The Voice API Apps are a set of pre-configured apps for outbound scenarios. Currently, the set consists of the following three apps:

Notification (Billing per minute)
One Time Password (OTP) (Billing per OTP message)
Request DTMF (Billing per minute)

These apps can be initiated by sending a request to the CM Server(s), which will initiate the call and once answered, will complete the process (flow) of the app.

Notification

Sending a Notification means sending a call that simply plays some audio and then hangs up. This audio can be spoken text (either using a custom audio file or our Text-To-Speech system), a commercial or any audio you can think of.

One Time Password (OTP)

Sending a One Time Password uses a bit more elaborate approach. This call contains a welcome message, the code (password), an outro, etc. It also allows the end user to press '1' to have the code repeated.

Every single piece of audio in an OTP call can be a custom audio file or a piece of text that is read by our Text-To-Speech system.

Request DTMF

DTMF, or Dual Tone Multi-Frequency, is the technique of using the numeric keys on your phone for input. Using this technique, we can send a call to end users, asking them to enter a code. This can for instance be used for authentication, to opt-in to a service or to accept an emergency call.

Authentication

Authentication for the VoiceAPI uses your CM API key (also known as your product token).

An API Key can be obtained from the API Settings menu in the Voice Management App. To access this app, you need at least a prepaid CM.com platform account.

In order to authenticate your request, add the following header, containing your API Key:

X-CM-PRODUCTTOKEN

Getting Started

We have an open source netstandard library available @ https://github.com/cmdotcom/talk-sdk-dotnet that enables you to use the API directly from a .NET or .NET Core application. You can install it from Nuget using the following command in the Nuget Console:

Install-Package CM.Voice.VoiceApi.Sdk

or search for CM.Voice.VoiceApi.Sdk in the Nuget Package Manager.

This is the easiest way to get your first call out, but if you are using another programming language or platform, sending a POST command with some JSON is usually fairly straight-forward.

Below you can find some examples, including .NET using the SDK, but also the plain JSON to send and an example using cURL (tip: you can import the cURL call into Postman).

Please note that all examples use a random (not working) API Key, so you will need to replace this with your own (always keep your key secret!). The same goes for the callee number.

Examples

C#

  var myApiKey = Guid.Parse("00000000-0000-0000-0000-000000000000");
  var httpClient = new HttpClient();
  var client = new VoiceApiClient(httpClient, myApiKey);
  var instruction = new NotificationInstruction
  {
      Caller = "003176xxxxxxx",
      Callee = "00316xxxxxxxx",
      Prompt = "This is a test notification call using the C M voice A P I.",
      MaxReplays = 2,
      ReplayPrompt = "Press 1 to repeat this message."
  };
  var result = await client.SendAsync(instruction).ConfigureAwait(false);

cURL

curl -X POST \
  https://api.cm.com/voiceapi/v2/Notification\
  -H 'Content-Type: application/json' \
  -H 'X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000' \
  -d '{
  "callee": "00316xxxxxxxx",
  "caller": "003176xxxxxxx",
  "prompt": "This is a test notification call using the C M voice A P I.",
  "prompt-type": "TTS"
}'

JSON

{
  "callee": "00316xxxxxxxx",
  "caller": "003176xxxxxxx",
  "prompt": "This is a test notification call using the C M voice A P I.",
  "prompt-type": "TTS"
}

Swagger

The Voice Api has Swagger documentation available:

Swagger UI
Swagger JSON

When using the UI, please note that you need to enter your Api Key in the authorization (see button in the top right of the page). If your Voice Account has more than one Api Account, please also enter the Key of the Api Account to use.

Postman

You can download a Postman collection with example calls to the Voice API:

Voice API Postman collection

The Apps

The next chapters will describe the different apps available and the paramaters required / available to use them. All the apps share the same base structure and the same security system, so all the Apps are initiated by sending a POST command to the CM Server(s) and passing it a JSON body with the parameters and their values.

The CM server will only accept your requests if they contains the correct information in the X-CM-PRODUCTTOKEN header, please see section Authentication for more info.

Notification App

In order to initiate a Notification call, you can use the CM endpoint at:

https://api.cm.com/voiceapi/v2/Notification

The flow of the call is:

  1. Call callee
  2. Wait for answer
  3. Play prompt
  4. Hang up

Variable definition

Variable Data type Length Required Description
instruction-id Alphanumeric 64 No A string to identify the instruction, useful to match events to the instruction they belong to, generated by the customer’s server.
callee Alphanumeric 24 Yes The number to dial in international format.
caller Alphanumeric 24 Yes The number to show as the caller in international format.*
anonymous Boolean 1 No (Default = false) The caller number is hidden when set to true.
prompt Alphanumeric 750 Yes The text to say (TTS / TTS_SSML) or the (path and) name of the file to play. The path is always relative to the root of the folder of the customer.
prompt-type Alphanumeric 4 No (Default = File) The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
replay-prompt Alphanumeric 750 No The text to say (TTS / TTS_SSML) or the (path and) name of the file to play, to instruct the callee to press 1 to repeat the prompt. The path is always relative to the root of the folder of the customer.
replay-prompt-type Alphanumeric 4 No (Default = TTS) The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
max-replays Numeric 1 No (default = 0) The maximum number of times the prompt can be repeated. Maximum value is 3.
auto-replay Boolean 1 No (default = false) The prompt will automatically repeat if true, it will play replay-prompt and wait for a press on the "1" otherwise.
voice JSON * No The voice to use if using TTS or TTS_SSML. See Text-To-Speech.
callback-url Alphanumeric 256 No The url (including http(s)://) for the callback. Defaults to the configured callback url if this variable is not supplied.
voicemail-response Alphanumeric 256 No The action to be executed when voicemail has been detected. See Voicemail detection

* Please note that it is technically possible to supply any caller id, but you are not allowed (by law) to (ab)use telephone numbers not owned by you.

C#

var myApiKey = Guid.Parse("00000000-0000-0000-0000-000000000000");
var httpClient = new HttpClient();
var client = new VoiceApiClient(httpClient, myApiKey);
var instruction = new NotificationInstruction
{
    Caller = "003176xxxxxxx",
    Callee = "00316xxxxxxxx",
    Prompt = "This is a test notification call using the C M voice A P I.",
    MaxReplays = 2,
    ReplayPrompt = "Press 1 to repeat this message."
};
var result = await client.SendAsync(instruction).ConfigureAwait(false);

cURL

curl -X POST \
    https://api.cm.com/voiceapi/v2/Notification\
    -H 'Content-Type: application/json' \
    -H 'X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000' \
    -d '{
    "callee": "00316xxxxxxxx",
    "caller": "003176xxxxxxx",
    "prompt": "This is a test notification call using the C M voice A P I.",
    "prompt-type": "TTS",
    "voicemail-response": "Ignore",
    "max-replays": 2,
    "auto-replay": false,
    "replay-prompt": "Press 1 to repeat this message.",
}'

JSON

{
  "callee": "00316xxxxxxxx",
  "caller": "003176xxxxxxx",
  "prompt": "This is a test notification call using the C M voice A P I.",
  "prompt-type": "TTS",
  "voicemail-response": "Ignore",
  "max-replays": 2,
  "auto-replay": false,
  "replay-prompt": "Press 1 to repeat this message."
}

Notification App callback

When the call is completed, the CM Server(s) will send a POST command to your server (at the supplied callback url), with a JSON body, with the following content:

Variable definition

Variable Data type Length Description
type Alphanumeric 32 The type of the instruction. Always “notification-finished” when a Text-to-speech or a Audio message has been sent.
call-id UUID / GUID 36 The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id Alphanumeric 64 The instruction identifier as supplied with the instruction this event belongs to.
caller Alphanumeric 25 This is the phone number of the caller, if known, “anonymous” otherwise. Phone numbers are always in international format E.164.
callee Alphanumeric 25 This is the phone number of the callee. Phone numbers are always in international format E.164.
result object -- This is the result object which contains the status of the call and its description.
started-on DateTime 24 The moment when the call has been started.
answered-on DateTime 24 The moment when the call has been answered.
finished-on DateTime 24 The moment when the call has been finished.
JSON

    "type": "notification-finished",
    "call-id": "6d0f176e-00ac-4de2-a04d-b3f7c895adb0",
    "instruction-id": "aeba8cae-eadd-4b49-9350-8061893b3d66",
    "caller": "003176xxxxxxx",
    "callee": "00316xxxxxxxx",
    "result": {
        "code": 10,
        "description": "Finished"
    },
    "started-on": "2018-02-09T11:00:31.752Z",
    "answered-on": "2018-02-09T11:00:37.972Z",
    "finished-on": "2018-02-09T11:00:48.112Z"
}

One Time Password (OTP) App

In order to initiate a OTP call, you can use the CM endpoint at:

https://api.cm.com/voiceapi/v2/OTP

The flow of the app is as following:

  1. Call the callee
  2. Wait for answer
  3. Play the intro-prompt (i.e. This is the CM OTP Service)
  4. Play the code-prompt (i.e. Your login code is)
  5. Play the code (i.e. A B C 1 2 3)
  6. Play the replay-prompt (i.e. Press 1 to repeat the code)
  7. Play the outro-prompt (i.e. Thank you for using this service, the call will now be disconnected.)
  8. Hangup

If the callee presses 1 during step 6, the flow will repeat from step 4.

Variable definition

Variable Data type Length Required Description
instruction-id Alphanumeric 64 No A string to identify the instruction, useful to match events to the instruction they belong to, generated by the customer’s server.
callee Alphanumeric 24 Yes The number to dial in international format.
caller Alphanumeric 24 Yes The number to show as the caller in international format.*
anonymous Boolean 1 No (Default = false) The caller number is hidden when set to true.
intro-prompt Alphanumeric 500 No The text to say (TTS / TTS_SSML) or the (path and) name of the file to play as the intro. The path is always relative to the root of the folder of the customer.
intro-prompt-type Alphanumeric 4 No (Default = File) The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
code-prompt Alphanumeric 500 No The text to say (TTS / TTS_SSML) or the (path and) name of the file to play before reading the code. This prompt is repeated when the code is repeated. The path is always relative to the root of the folder of the customer.
code-prompt-type Alphanumeric 4 No (Default = File) The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
code Alphanumeric 64 Yes The code to read to the caller. Note that this code is read character per character, not as a word or number.
code-type Alphanumeric 8 No (Default = Default) The type of audio to use, either default prompts (Default), your own prompts (Custom) or a TTS voice (TTS).
replay-prompt Alphanumeric 500 No The text to say (TTS / TTS_SSML) or the (path and) name of the file to play, to instruct the callee to press 1 to repeat the code. The path is always relative to the root of the folder of the customer.
replay-prompt-type Alphanumeric 4 No (Default = File) The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
outro-prompt Alphanumeric 500 No The text to say (TTS / TTS_SSML) or the (path and) name of the file to play before ending the call. The path is always relative to the root of the folder of the customer.
outro-prompt-type Alphanumeric 4 No (Default = File) The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
max-replays Numeric 1 No (Default = 3) The maximum number of times the code can be repeated. Maximum value is 3.
auto-replay Boolean 1 No (Default = false) The code-prompt and code will replay automatically repeat if true, it will play replay-prompt and wait for a press on the "1" otherwise.
voice JSON * No The voice to use if using TTS or TTS_SSML. See Text-To-Speech.
callback-url Alphanumeric 256 No The url (including http(s)://) for the callback. Defaults to the configured callback url if this variable is not supplied.

* Please note that it is technically possible to supply any caller id, but you are not allowed (by law) to (ab)use telephone numbers not owned by you.

C#

var myApiKey = Guid.Parse("00000000-0000-0000-0000-000000000000");
var httpClient = new HttpClient();
var client = new VoiceApiClient(httpClient, myApiKey);
var instruction = new OtpInstruction
{
    Callee = "+316xxxxxxxx",
    Caller = "+3176xxxxxxx",
    IntroPrompt = "Welcome to the C M password service.",
    CodePrompt = "Your code is:",
    Code = "abc123",
    MaxReplays = 2,
    ReplayPrompt = "Press 1 to repeat your code",
    OutroPrompt = "Thank you for using this service."
};
var result = await client.SendAsync(instruction).ConfigureAwait(false);

cURL

curl -X POST \
  https://api.cm.com/voiceapi/v2/OTP \
  -H 'Content-Type: application/json' \
  -H 'X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000' \
  -d '{
    "callee": "+316xxxxxxxx",
    "caller": "+3176xxxxxxx",
    "intro-prompt": "Welcome to the C M password service.",
    "intro-prompt-type": "TTS",
    "code": "123abc",
    "code-type": "TTS",
    "replay-prompt": "Press 1 to replay your code.",
    "replay-prompt-type": "TTS",
    "outro-prompt": "Thank you for using this service.",
    "outro-prompt-type": "TTS",
    "voicemail-response": "Ignore"
}'

JSON

{
    "callee": "+316xxxxxxxx",
    "caller": "+3176xxxxxxx",
    "intro-prompt": "Welcome to the C M password service.",
    "intro-prompt-type": "TTS",
    "code": "123abc",
    "code-type": "TTS",
    "replay-prompt": "Press 1 to replay your code.",
    "replay-prompt-type": "TTS",
    "outro-prompt": "Thank you for using this service.",
    "outro-prompt-type": "TTS",
    "voicemail-response": "Ignore"
}

One Time Password (OTP) App callback

When the call is completed, the CM Server(s) will send a POST command to your server (at the supplied callback url), with a JSON body, with the following content:

Variable definition

Variable Data type Length Description
type Alphanumeric 32 The type of the instruction. Always “otp-finished” when a OTP message has been sent.
call-id UUID / GUID 36 The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id Alphanumeric 64 The instruction identifier as supplied with the instruction this event belongs to.
caller Alphanumeric 25 This is the phone number of the caller, if known, “anonymous” otherwise. Phone numbers are always in international format E.164.
callee Alphanumeric 25 This is the phone number of the callee. Phone numbers are always in international format E.164.
result object -- This is the result object which contains the status of the call and its description.
started-on DateTime 24 The moment when the call has been started.
answered-on DateTime 24 The moment when the call has been answered.
finished-on DateTime 24 The moment when the call has been finished.
JSON
{
    "type": "otp-finished",
    "call-id": "6d0f176e-00ac-4de2-a04d-b3f7c895adb0",
    "instruction-id": "aeba8cae-eadd-4b49-9350-8061893b3d66",
    "callee": "+316xxxxxxxx",
    "caller": "+3176xxxxxxx",
    "result": {
        "code": 10,
        "description": "Finished"
    },
    "started-on": "2018-02-09T11:00:31.752Z",
    "answered-on": "2018-02-09T11:00:37.972Z",
    "finished-on": "2018-02-09T11:00:48.112Z"
}

Request-DTMF App

In order to initiate a Request-DTMF call, you can use the CM endpoint at:

https://api.cm.com/voiceapi/v2/DTMF

The flow of a call is as following:

  1. Call the callee
  2. Wait for answer
  3. Play the prompt (i.e. Please enter some digits)
  4. Play the valid-prompt or the invalid-prompt, depending of the input compared to the regex and minimum and maximum digits. (i.e. Thank you for your input, or That's not right)
  5. Hang up

If the input was not valid, step 3 will repeat after step 4, until either the callee entered some valid input, or there were max-attempts attempts.

Variable definition

Variable Data type Length Required Description
instruction-id Alphanumeric 64 No A string to identify the instruction, useful to match events to the instruction they belong to, generated by the customer’s server.
callee Alphanumeric 24 Yes The number to dial in international format.
caller Alphanumeric 24 Yes The number to show as the caller in international format.*
anonymous Boolean 1 No (Default = false) The caller number is hidden when set to true.
prompt Alphanumeric 1000 No The text to say (TTS / TTS_SSML) or the (path and) name of the file to play. The path is always relative to the root of the folder of the customer.
prompt-type Alphanumeric 4 No (Default = File) The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
valid-prompt Alphanumeric 1000 No The text to say (TTS / TTS_SSML) or the (path and) name of the file to play when received valid input. This prompt is repeated when the code is repeated. The path is always relative to the root of the folder of the customer.
valid-prompt-type Alphanumeric 4 No (Default = File) The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
invalid-prompt Alphanumeric 1000 No The text to say (TTS / TTS_SSML) or the (path and) name of the file to play when received invalid input. This prompt is repeated when the code is repeated. The path is always relative to the root of the folder of the customer.
invalid-prompt-type Alphanumeric 4 No (Default = File) The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
min-digits Numeric 2 Yes The minimum number of digits required as input from the callee.
max-digits Numeric 2 Yes The maximum number of digits required as input from the callee.
max-attempts Numeric 2 Yes The maximum number of attempts the callee gets to supply valid input.
timeout Numeric 8 No (Default = 5000) The max. time in ms between the end of the prompt audio and the first digit, or between digits. If no digit is received before this timeout, it is counted as an attempt and the prompt is restarted. Value must be between 1000 and 10000 ms.
terminators Alphanumeric 8 No (Default = #) A list of digits that cause the input to be terminated. Used in cases where you want to state “Enter your … number, ending with a #”.
regex Alphanumeric 64 No (Default is [0-9]*) The regex to match the input against. An attempt will fail if the input does not match this regular expression. Please note that you may need to escape certain characters in JSON.
voice JSON * No The voice to use if using TTS or TTS_SSML. See Text-To-Speech.
callback-url Alphanumeric 256 No The url (including http(s)://) for the callback. Defaults to the configured callback url if this variable is not supplied.

* Please note that it is technically possible to supply any caller id, but you are not allowed (by law) to (ab)use telephone numbers not owned by you.

C#

var myApiKey = Guid.Parse("00000000-0000-0000-0000-000000000000");
var httpClient = new HttpClient();
var client = new VoiceApiClient(httpClient, myApiKey);
var instruction = new RequestDtmfInstruction
{
    Callee = "+316xxxxxxxx",
    Caller = "+3176xxxxxxx",
    Prompt = "Please enter some digits.",
    MinDigits = 2,
    MaxDigits = 5,
    MaxAttempts = 3,
    ValidPrompt = "Thank you for your input.",
    InvalidPrompt = "That is not right"
};
var result = await client.SendAsync(instruction).ConfigureAwait(false);

cURL

curl -X POST \
  https://api.cm.com/voiceapi/v2/DTMF \
  -H 'Content-Type: application/json' \
  -H 'X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000' \
  -d '{
    "callee": "+316xxxxxxxx",
    "caller": "+3176xxxxxxx",
    "prompt": "This is an automated voice response system from C M. Please enter some digits.",
    "prompt-type": "TTS",
    "valid-prompt": "Thank you for your input.",
    "valid-prompt-type": "TTS",
    "invalid-prompt": "That'\''s not right!",
    "invalid-prompt-type": "TTS",
    "min-digits": 2,
    "max-digits": 5,
    "max-attempts": 3
}'

JSON

{
    "callee": "+316xxxxxxxx",
    "caller": "+3176xxxxxxx",
    "prompt": "This is an automated voice response system from C M. Please enter some digits.",
    "prompt-type": "TTS",
    "valid-prompt": "Thank you for your input.",
    "valid-prompt-type": "TTS",
    "invalid-prompt": "That'\''s not right!",
    "invalid-prompt-type": "TTS",
    "min-digits": 2,
    "max-digits": 5,
    "max-attempts": 3
}

Request-DTMF App callback

When the call is completed, the CM Server(s) will send a POST command to your server (at the supplied callback url), with a JSON body, with the following content:

Variable definition

Variable Data type Length Description
type Alphanumeric 32 The type of the instruction. Always “dtmf-finished” for an event that returns the dtmf digits received as the result of a get-dtmf instruction.
call-id UUID / GUID 36 The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id Alphanumeric 64 The instruction identifier as supplied with the instruction this event belongs to.
caller Alphanumeric 25 This is the phone number of the caller, if known, “anonymous” otherwise. Phone numbers are always in international format E.164.
callee Alphanumeric 25 This is the phone number of the callee. Phone numbers are always in international format E.164.
result object -- This is the result object which contains the status of the call and its description.
started-on DateTime 24 The moment when the call has been started.
answered-on DateTime 24 The moment when the call has been answered.
finished-on DateTime 24 The moment when the call has been finished.
digits Alphanumeric 64 This is the DTMF data that was received, excluding the terminator symbol if it was used (usually #). Empty if no (correct) dtmf input was received from the caller.
JSON
{
    "type": "dtmf-finished",
    "call-id": "6d0f176e-00ac-4de2-a04d-b3f7c895adb0",
    "instruction-id": "aeba8cae-eadd-4b49-9350-8061893b3d66",
    "callee": "+316xxxxxxxx",
    "caller": "+3176xxxxxxx",
    "result": {
        "code": 10,
        "description": "Finished"
    },
    "started-on": "2018-02-09T11:00:31.752Z",
    "answered-on": "2018-02-09T11:00:37.972Z",
    "finished-on": "2018-02-09T11:00:48.112Z",
    "digits": "1234"
}

Result codes

When you receive a result on a callback url, you will find a part of the message contains the result of the call.

The result is a piece of JSON code, containing a code and a description.

Variable definition

Variable Data type Length Required Description
code Numeric 2 Yes The code of the result
description Alphanumeric 128 Yes The description of the result

Possible results

Code Description Explanation
9 Cancelled The call was not answered and was cancelled after a timeout hit (60 seconds)
10 Finished suncessfully The call was placed and answered before ending.
11 Failed The call could not be made.
12 Call rejected The callee actively refused the call, this could also mean the telecom provider owning the number did, so please check the validity of the number.

JSON

"result": {
    "code": 10,
    "description": "Finished successfully"
}

Audio and voices

Custom audio files

If custom audio files are to be used, they should preferably meet the following specification:

Bit rate: 128 kbps
Sample size: 16 bit
Channels: Mono
Audio sample rate: 8 kHz (8000 Hz)
Audio codec: PCM
Filename: *.wav

Other formats will be transcoded to the above.

In order to use custom audio files, they need to be available to the Voice API. This is facilitated using the Audio Manager, which allows you to upload your custom audio files onto our servers.

You are free to create any directory structure on this server, just make sure you supply the whole path from the root of your account when sending an instruction that requires an audio file.

If you want to use custom spelling audio, these files must be placed in the correct structure, as explained in the next chapter.

Custom audio files for the OTP app

In order to use custom audio files with the OTP app, you need to upload a set of audio files in the following directory structure using the Audio Manager:

/spelling/en-GB/*.wav

Where ‘en-GB’ is the language (including locale) of the set. Inside this folder, you need to upload a .wav file for every number or letter you want to be able to read aloud, like:

0.wav
1.wav
2.wav
a.wav
b.wav
c.wav

Note that these file names are all lower case.

Text-To-Speech

The Voice API supports Text-To-Speech (or TTS) in all instructions where you can provide a prompt to the caller/callee. When using TTS, you can provide the voice you want to use. Currently we support the following voices:

Language / Locale Code Gender Number of voices available
Welsh English cy-GB Female 1
Danish da-DK Female 1
Danish da-DK Male 1
German de-DE Female 2
German de-DE Male 1
Australian English en-AU Female 1
Australian English en-AU Male 1
UK English en-GB Female 2
UK English en-GB Male 2
Indian English en-IN Female 1
US English en-US Female 5
US English en-US Male 2
Spanish es-ES Female 1
Spanish es-ES Male 1
Spanish English es-US Female 1
Spanish English es-US Male 1
Canadian French fr-CA Female 1
French fr-FR Female 1
French fr-FR Male 1
Hindi hi-IN Female 1
Icelandic is-IS Female 1
Icelandic is-IS Male 1
Italian it-IT Female 1
Italian it-IT Male 1
Japanese ja-JP Female 1
Japanese ja-JP Male 1
Korean ko-KR Female 1
Norwegian Bokmal nb-NO Female 1
Dutch nl-NL Female 1
Dutch nl-NL Male 1
Polish pl-PL Female 2
Polish pl-PL Male 2
Brazilian Portuguese pt-BR Female 1
Brazilian Portuguese pt-BR Male 1
Portuguese pt-PT Female 1
Portuguese pt-PT Male 1
Romanian ro-RO Female 1
Russian ru-RU Female 1
Russian ru-RU Male 1
Swedish sv-SE Female 1
Turkish tr-TR Female 1
Chinese zh-CHS Female 1

When using TTS (or the Spelling Instruction), you can provide the voice to use in the JSON body. The voice part of the JSON body has the following variables:

C#

instruction.Voice.Language = "nl-NL";
instruction.Voice.Gender = Gender.Male;
instruction.Voice.Number = 1;
instruction.Voice.Volume = 2;

JSON

"voice": {
    "language": "nl-NL",
    "gender": "Male",
    "number": 1,
    "volume": 2
}

Variable definition

Variable Data type Length Required Description
language Alphanumeric 5 No (Default: en-GB) The language of the voice to use.
gender Alphanumeric 6 No (Default: Female) The gender of the voice, either 'Male' or 'Female'.
number Numeric 3 No (Default: 1) The number of the voice to use, if the given combination of language and gender provides multiple voices.
volume Numeric 1 No (Default: 0) The volume level of the voice. Must be between -4 and 4.

SSML

With Speech Synthesis Markup Language (SSML) you can enhance your TTS prompts. For example, you can include pause within a prompt or change the speech rate or pitch.

Example

{
    "prompt": "<speak>Hi! I will wait for 2 seconds. <break time='2s'/> Now I will spell the word hello: <break time='1s'/> <say-as interpret-as='characters'>hello</say-as>. <prosody rate='-50%' pitch='-25%' volume='+2dB'>I am speaking a bit loudly, slowly and with a lower pitch.</prosody></speak>"
}

Attributes

Type Description Parameters Values
<speak> The root where the SSML start. Required in order to use SSML. -- --
<break> Adds a pause between words. time
time in milliseconds (ms) or seconds(s)
Ns or Nms

Maximum total duration is 10 seconds per API call.
<say-as> Control how special types of words are spoken. interpret-as
Determines how to say certain characters, words, numbers
cardinal, characters, ordinal, fraction, unit, date, time, expletive
<prosody> Control the volume, speaking rate and the pitch rate
Determines how fast or slow the text should be spoken.

pitch
Determines the pitch of the voice.

volume
Change the volume for the text.
rate
+/- n%

pitch
+/- N%

volume
+/- NdB
<emphasis> Emphasize words. level
Specify the degree of emphasis
strong, moderate, reduced

More advanced information about SSML and the attributes can be found in the W3C SSML Specification.

Voicemail detection

You can also determine the action when voicemail has been detected, by setting the property voicemail-response in your request. The following settings are supported:

Value Description
Ignore Do not detect voicemail. Default value when voicemail-response is not set in your request.
Restart Restarts the whole prompt.
Stop Stops the call.

Please note that voicemail detection is not supported for OTP & DTMF!