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:

Call callee
Wait for answer
Play prompt
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 Audio-And-Voices.
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.
voicemail	Boolean	1	True, if the call triggered the automatic voicemail detection.

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:

Call the callee
Wait for answer
Play the intro-prompt (i.e. This is the CM OTP Service)
Play the code-prompt (i.e. Your login code is)
Play the code (i.e. A B C 1 2 3)
Play the replay-prompt (i.e. Press 1 to repeat the code)
Play the outro-prompt (i.e. Thank you for using this service, the call will now be disconnected.)
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 Audio and Voices .
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:

Call the callee
Wait for answer
Play the prompt (i.e. Please enter some digits)
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)
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 Audio and Voices.
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"
}