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

VariableData typeLengthRequiredDescription
instruction-idAlphanumeric64NoA string to identify the instruction, useful to match events to the instruction they belong to, generated by the customer’s server.
calleeAlphanumeric24YesThe number to dial in international format.
callerAlphanumeric24YesThe number to show as the caller in international format.*
anonymousBoolean1No (Default = false)The caller number is hidden when set to true.
promptAlphanumeric750YesThe 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-typeAlphanumeric4No (Default = File)The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
replay-promptAlphanumeric750NoThe 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-typeAlphanumeric4No (Default = TTS)The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
max-replaysNumeric1No (default = 0)The maximum number of times the prompt can be repeated. Maximum value is 3.
auto-replayBoolean1No (default = false)The prompt will automatically repeat if true, it will play replay-prompt and wait for a press on the "1" otherwise.
voiceJSON*NoThe voice to use if using TTS or TTS_SSML. See Audio-And-Voices.
callback-urlAlphanumeric256NoThe url (including http(s)://) for the callback. Defaults to the configured callback url if this variable is not supplied.
voicemail-responseAlphanumeric256NoThe 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

VariableData typeLengthDescription
typeAlphanumeric32The type of the instruction. Always “notification-finished” when a Text-to-speech or a Audio message has been sent.
call-idUUID / GUID36The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-idAlphanumeric64The instruction identifier as supplied with the instruction this event belongs to.
callerAlphanumeric25This is the phone number of the caller, if known, “anonymous” otherwise. Phone numbers are always in international format E.164.
calleeAlphanumeric25This is the phone number of the callee. Phone numbers are always in international format E.164.
resultobject--This is the result object which contains the status of the call and its description.
started-onDateTime24The moment when the call has been started.
answered-onDateTime24The moment when the call has been answered.
finished-onDateTime24The 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

VariableData typeLengthRequiredDescription
instruction-idAlphanumeric64NoA string to identify the instruction, useful to match events to the instruction they belong to, generated by the customer’s server.
calleeAlphanumeric24YesThe number to dial in international format.
callerAlphanumeric24YesThe number to show as the caller in international format.*
anonymousBoolean1No (Default = false)The caller number is hidden when set to true.
intro-promptAlphanumeric500NoThe 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-typeAlphanumeric4No (Default = File)The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
code-promptAlphanumeric500NoThe 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-typeAlphanumeric4No (Default = File)The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
codeAlphanumeric64YesThe code to read to the caller. Note that this code is read character per character, not as a word or number.
code-typeAlphanumeric8No (Default = Default)The type of audio to use, either default prompts (Default), your own prompts (Custom) or a TTS voice (TTS).
replay-promptAlphanumeric500NoThe 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-typeAlphanumeric4No (Default = File)The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
outro-promptAlphanumeric500NoThe 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-typeAlphanumeric4No (Default = File)The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
max-replaysNumeric1No (Default = 3)The maximum number of times the code can be repeated. Maximum value is 3.
auto-replayBoolean1No (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.
voiceJSON*NoThe voice to use if using TTS or TTS_SSML. See Audio and Voices .
callback-urlAlphanumeric256NoThe 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

VariableData typeLengthDescription
typeAlphanumeric32The type of the instruction. Always “otp-finished” when a OTP message has been sent.
call-idUUID / GUID36The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-idAlphanumeric64The instruction identifier as supplied with the instruction this event belongs to.
callerAlphanumeric25This is the phone number of the caller, if known, “anonymous” otherwise. Phone numbers are always in international format E.164.
calleeAlphanumeric25This is the phone number of the callee. Phone numbers are always in international format E.164.
resultobject--This is the result object which contains the status of the call and its description.
started-onDateTime24The moment when the call has been started.
answered-onDateTime24The moment when the call has been answered.
finished-onDateTime24The 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

VariableData typeLengthRequiredDescription
instruction-idAlphanumeric64NoA string to identify the instruction, useful to match events to the instruction they belong to, generated by the customer’s server.
calleeAlphanumeric24YesThe number to dial in international format.
callerAlphanumeric24YesThe number to show as the caller in international format.*
anonymousBoolean1No (Default = false)The caller number is hidden when set to true.
promptAlphanumeric1000NoThe 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-typeAlphanumeric4No (Default = File)The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
valid-promptAlphanumeric1000NoThe 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-typeAlphanumeric4No (Default = File)The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
invalid-promptAlphanumeric1000NoThe 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-typeAlphanumeric4No (Default = File)The type of the prompt: TTS (Text-To-Speech), TTS_SSML (Text-To-Speech SSML) or File.
min-digitsNumeric2YesThe minimum number of digits required as input from the callee.
max-digitsNumeric2YesThe maximum number of digits required as input from the callee.
max-attemptsNumeric2YesThe maximum number of attempts the callee gets to supply valid input.
timeoutNumeric8No (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.
terminatorsAlphanumeric8No (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 #”.
regexAlphanumeric64No (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.
voiceJSON*NoThe voice to use if using TTS or TTS_SSML. See Audio and Voices.
callback-urlAlphanumeric256NoThe 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

VariableData typeLengthDescription
typeAlphanumeric32The 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-idUUID / GUID36The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-idAlphanumeric64The instruction identifier as supplied with the instruction this event belongs to.
callerAlphanumeric25This is the phone number of the caller, if known, “anonymous” otherwise. Phone numbers are always in international format E.164.
calleeAlphanumeric25This is the phone number of the callee. Phone numbers are always in international format E.164.
resultobject--This is the result object which contains the status of the call and its description.
started-onDateTime24The moment when the call has been started.
answered-onDateTime24The moment when the call has been answered.
finished-onDateTime24The moment when the call has been finished.
digitsAlphanumeric64This 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

VariableData typeLengthRequiredDescription
codeNumeric2YesThe code of the result
descriptionAlphanumeric128YesThe description of the result

Possible results

CodeDescriptionExplanation
9CancelledThe call was not answered and was cancelled after a timeout hit (60 seconds)
10Finished suncessfullyThe call was placed and answered before ending.
11FailedThe call could not be made.
12Call rejectedThe 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"
}

Did this page help you?