Skip to main content
Versionv2

Voice API (v2)

Download OpenAPI specification:Download

Dtmf

DTMF

Send out a call that requests DTMF input from the callee. For more information, see the Voice DTMF documentation.

Authorizations:
X-CM-PRODUCTTOKEN
Request Body schema:

Details of the DTMF instruction.

instruction-id
string or null <= 64 characters

Optional string that allows you to uniquely identify the placed outbound call. Its value is also included in the callback and Call Detail Records (CDRs).

callee
string or null <= 24 characters ^(\+|00)?[1-9]\d{6,14}$

The number to dial. When the number is invalid, the request will be rejected. Must be in valid international E.164 format.

callees
Array of strings or null <= 100 items ^(\+|00)?[1-9]\d{6,14}$

List of multiple numbers to dial. When the list contains one or more invalid numbers, the request will be rejected. Must be in valid international E.164 format.

caller
required
string [ 1 .. 24 ] characters ^(\+|00)?[1-9]\d{6,14}$

The caller ID to display on the recipient's phone. Must be in valid international E.164 format.

anonymous
boolean

Indicates whether the caller ID should be hidden. Defaults to false.

callback-url
string or null <uri>

URL that will be called when the call is finished. The body of this POST request will contain details about the call or calls.

max-ringing-timeout
integer or null <int32> [ 10 .. 60 ]

Determines how long the Voice API will wait for the callee to answer the call. Cancels the ringing call after the timeout period exceeded. Defaults to 60.

prompt
required
string [ 1 .. 1000 ] characters

The prompt to play which describes what DTMF input is requested from the callee. This can be either TTS or SSML, or the path to an audio file in your Voice Audio Manager.

prompt-type
string (Prompt Type)
Enum: "File" "TTS" "TTS_SSML"

The type of the prompt, to distinguish between a filename and a string that needs to be tts-ed.

valid-prompt
required
string [ 1 .. 1000 ] characters

The prompt to play when the . This can be either TTS or SSML, or the path to an audio file in your Voice Audio Manager.

valid-prompt-type
string (Prompt Type)
Enum: "File" "TTS" "TTS_SSML"

The type of the prompt, to distinguish between a filename and a string that needs to be tts-ed.

invalid-prompt
string or null

The prompt, which is either the path and name of the file to play, or the string that needs to be tts-ed.

invalid-prompt-type
string (Prompt Type)
Enum: "File" "TTS" "TTS_SSML"

The type of the prompt, to distinguish between a filename and a string that needs to be tts-ed.

min-digits
integer or null <int32> [ 1 .. 64 ]

The minimum number of digits for the dtmf input.

max-digits
integer or null <int32> [ 1 .. 64 ]

The maximum number of digits for the dtmf input.

max-attempts
integer or null <int32> [ 1 .. 10 ]

The maximum number of attempts to input valid dtmf.

timeout
integer or null <int32> [ 1000 .. 10000 ]

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. Defaults to 5000.

terminators
string or null

The keys that will end dtmf input. Usually # or *. Defaults to #.

regex
string or null

The regex to match the input against. An attempt will fail if the input does not match this regular expression. Defaults to [0-9]*.

object (Voice)

The properties in this class are used to select the required TTS voice.

voicemail-response
string (Voicemail Response)
Enum: "Ignore" "Restart" "Stop" "Disconnect"

The type that determines the flow of Voicemail detection.

Responses

Request samples

Content type
{
  • "instruction-id": "mycustomid",
  • "callee": "+31612345678",
  • "callees": [
    ],
  • "caller": "+31612345678",
  • "anonymous": false,
  • "callback-url": "http://example.com",
  • "max-ringing-timeout": 60,
  • "prompt": "Please enter some digits.",
  • "prompt-type": "File",
  • "valid-prompt": "Thank you for your answer, the call will now be ended.",
  • "valid-prompt-type": "File",
  • "invalid-prompt": "This is not a valid input, please try again.",
  • "invalid-prompt-type": "File",
  • "min-digits": 3,
  • "max-digits": 15,
  • "max-attempts": 3,
  • "timeout": 5000,
  • "terminators": "#",
  • "regex": "[0-9]*",
  • "voice": {
    },
  • "voicemail-response": "Ignore"
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "call-id": "19b3153e-09e5-40c5-8394-9bb42ff64302",
  • "instruction-id": "string",
  • "queue-id": "string",
  • "caller": "string",
  • "callee": "string",
  • "success": true,
  • "error": "string"
}

Flow Builder

FlowBuilder

Initiate an outbound FlowBuilder call. For more information, see the Voice FlowBuilder documentation.

Authorizations:
X-CM-PRODUCTTOKEN
Request Body schema:

Details of the FlowBuilder instruction.

instruction-id
string or null <= 64 characters

Optional string that allows you to uniquely identify the placed outbound call. Its value is also included in the callback and Call Detail Records (CDRs).

callee
string or null <= 24 characters ^(\+|00)?[1-9]\d{6,14}$

The number to dial. When the number is invalid, the request will be rejected. Must be in valid international E.164 format.

callees
Array of strings or null <= 100 items ^(\+|00)?[1-9]\d{6,14}$

List of multiple numbers to dial. When the list contains one or more invalid numbers, the request will be rejected. Must be in valid international E.164 format.

caller
required
string [ 1 .. 24 ] characters ^(\+|00)?[1-9]\d{6,14}$

The caller ID to display on the recipient's phone. Must be in valid international E.164 format.

anonymous
boolean

Indicates whether the caller ID should be hidden. Defaults to false.

callback-url
string or null <uri>

URL that will be called when the call is finished. The body of this POST request will contain details about the call or calls.

max-ringing-timeout
integer or null <int32> [ 10 .. 60 ]

Determines how long the Voice API will wait for the callee to answer the call. Cancels the ringing call after the timeout period exceeded. Defaults to 60.

callflow-id
required
string non-empty

This property represents the unique identifier for a FlowBuilder flow. For guidance on locating the callflow ID of a specific flow, please refer to the FlowBuilder documentation.

object or null

Optional list of flow variables that will be set. For more information on FlowBuilder variables, please see the FlowBuilder documentation.

voicemail-response
string (Voicemail Response)
Enum: "Ignore" "Restart" "Stop" "Disconnect"

The type that determines the flow of Voicemail detection.

Responses

Request samples

Content type
{
  • "instruction-id": "mycustomid",
  • "callee": "+31612345678",
  • "callees": [
    ],
  • "caller": "+31612345678",
  • "anonymous": false,
  • "callback-url": "http://example.com",
  • "max-ringing-timeout": 60,
  • "callflow-id": "00000000-0000-0000-0000-000000000000",
  • "flow-variables": {
    },
  • "voicemail-response": "Ignore"
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "call-id": "19b3153e-09e5-40c5-8394-9bb42ff64302",
  • "instruction-id": "string",
  • "queue-id": "string",
  • "caller": "string",
  • "callee": "string",
  • "success": true,
  • "error": "string"
}

Notification

Notification

Send out a Voice Notification message. For more information, see the Voice Notification documentation.

Authorizations:
X-CM-PRODUCTTOKEN
Request Body schema:

Details of the notification instruction.

instruction-id
string or null <= 64 characters

Optional string that allows you to uniquely identify the placed outbound call. Its value is also included in the callback and Call Detail Records (CDRs).

callee
string or null <= 24 characters ^(\+|00)?[1-9]\d{6,14}$

The number to dial. When the number is invalid, the request will be rejected. Must be in valid international E.164 format.

callees
Array of strings or null <= 100 items ^(\+|00)?[1-9]\d{6,14}$

List of multiple numbers to dial. When the list contains one or more invalid numbers, the request will be rejected. Must be in valid international E.164 format.

caller
required
string [ 1 .. 24 ] characters ^(\+|00)?[1-9]\d{6,14}$

The caller ID to display on the recipient's phone. Must be in valid international E.164 format.

anonymous
boolean

Indicates whether the caller ID should be hidden. Defaults to false.

callback-url
string or null <uri>

URL that will be called when the call is finished. The body of this POST request will contain details about the call or calls.

max-ringing-timeout
integer or null <int32> [ 10 .. 60 ]

Determines how long the Voice API will wait for the callee to answer the call. Cancels the ringing call after the timeout period exceeded. Defaults to 60.

prompt
required
string [ 1 .. 750 ] characters

The prompt to play. This can be either TTS or SSML, or the path to an audio file in your Voice Audio Manager.

prompt-type
string (Prompt Type)
Enum: "File" "TTS" "TTS_SSML"

The type of the prompt, to distinguish between a filename and a string that needs to be tts-ed.

object (Voice)

The properties in this class are used to select the required TTS voice.

voicemail-response
string (Voicemail Response)
Enum: "Ignore" "Restart" "Stop" "Disconnect"

The type that determines the flow of Voicemail detection.

max-replays
integer or null <int32> [ 0 .. 3 ]

The number of times the Notification can be replayed.

auto-replay
boolean or null

Whether to automatically replay the Notification. Defaults to false.

replay-prompt
string or null <= 750 characters

Optional prompt instructing the callee to press 1 to replay the Notification. This can be either TTS or SSML, or the path to an audio file in your Voice Audio Manager.

replay-prompt-type
string (Prompt Type)
Enum: "File" "TTS" "TTS_SSML"

The type of the prompt, to distinguish between a filename and a string that needs to be tts-ed.

Responses

Request samples

Content type
{
  • "instruction-id": "mycustomid",
  • "callee": "+31612345678",
  • "callees": [
    ],
  • "caller": "+31612345678",
  • "anonymous": false,
  • "callback-url": "http://example.com",
  • "max-ringing-timeout": 60,
  • "prompt": "This is my Voice Notification message.",
  • "prompt-type": "File",
  • "voice": {
    },
  • "voicemail-response": "Ignore",
  • "max-replays": 3,
  • "auto-replay": false,
  • "replay-prompt": "Press 1 to replay the message.",
  • "replay-prompt-type": "File"
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "call-id": "19b3153e-09e5-40c5-8394-9bb42ff64302",
  • "instruction-id": "string",
  • "queue-id": "string",
  • "caller": "string",
  • "callee": "string",
  • "success": true,
  • "error": "string"
}

Otp

OTP

Send out a Voice OTP (one time password). For more information, see the Voice OTP documentation.

Authorizations:
X-CM-PRODUCTTOKEN
Request Body schema:

Details of the OTP instruction.

instruction-id
string or null <= 64 characters

Optional string that allows you to uniquely identify the placed outbound call. Its value is also included in the callback and Call Detail Records (CDRs).

callee
string or null <= 24 characters ^(\+|00)?[1-9]\d{6,14}$

The number to dial. When the number is invalid, the request will be rejected. Must be in valid international E.164 format.

callees
Array of strings or null <= 100 items ^(\+|00)?[1-9]\d{6,14}$

List of multiple numbers to dial. When the list contains one or more invalid numbers, the request will be rejected. Must be in valid international E.164 format.

caller
required
string [ 1 .. 24 ] characters ^(\+|00)?[1-9]\d{6,14}$

The caller ID to display on the recipient's phone. Must be in valid international E.164 format.

anonymous
boolean

Indicates whether the caller ID should be hidden. Defaults to false.

callback-url
string or null <uri>

URL that will be called when the call is finished. The body of this POST request will contain details about the call or calls.

max-ringing-timeout
integer or null <int32> [ 10 .. 60 ]

Determines how long the Voice API will wait for the callee to answer the call. Cancels the ringing call after the timeout period exceeded. Defaults to 60.

intro-prompt
string or null <= 500 characters

Optional prompt to play when the call is first answered. This can be either TTS or SSML, or the path to an audio file in your Voice Audio Manager.

intro-prompt-type
string (Prompt Type)
Enum: "File" "TTS" "TTS_SSML"

The type of the prompt, to distinguish between a filename and a string that needs to be tts-ed.

code-prompt
string or null <= 500 characters

Optional prompt to play right before playing the actual OTP code. This can be either TTS or SSML, or the path to an audio file in your Voice Audio Manager. This prompt is also replayed when the code is replayed.

code-prompt-type
string (Prompt Type)
Enum: "File" "TTS" "TTS_SSML"

The type of the prompt, to distinguish between a filename and a string that needs to be tts-ed.

code
required
string [ 1 .. 64 ] characters

The code to read to the caller. Note that this code is read character per character, not as a word or number.

code-type
string (Code Type)
Enum: "Default" "TTS" "Custom"

The type of the OTP code

replay-prompt
string or null <= 500 characters

Optional prompt instructing the callee to press 1 to replay the OTP. This can be either TTS or SSML, or the path to an audio file in your Voice Audio Manager.

replay-prompt-type
string (Prompt Type)
Enum: "File" "TTS" "TTS_SSML"

The type of the prompt, to distinguish between a filename and a string that needs to be tts-ed.

outro-prompt
string or null <= 500 characters

Optional prompt instructing the callee to press 1 to replay the Notification. This can be either TTS or SSML, or the path to an audio file in your Voice Audio Manager.

outro-prompt-type
string (Prompt Type)
Enum: "File" "TTS" "TTS_SSML"

The type of the prompt, to distinguish between a filename and a string that needs to be tts-ed.

max-replays
integer or null <int32> [ 0 .. 3 ]

The number of times the OTP can be replayed.

auto-replay
boolean or null

Whether to automatically replay the OTP. Defaults to false.

object (Voice)

The properties in this class are used to select the required TTS voice.

voicemail-response
string (Voicemail Response)
Enum: "Ignore" "Restart" "Stop" "Disconnect"

The type that determines the flow of Voicemail detection.

Responses

Request samples

Content type
{
  • "instruction-id": "mycustomid",
  • "callee": "+31612345678",
  • "callees": [
    ],
  • "caller": "+31612345678",
  • "anonymous": false,
  • "callback-url": "http://example.com",
  • "max-ringing-timeout": 60,
  • "intro-prompt": "This is the CM.com OTP Service.",
  • "intro-prompt-type": "File",
  • "code-prompt": "Your one time password is:",
  • "code-prompt-type": "File",
  • "code": "1234abc",
  • "code-type": "Default",
  • "replay-prompt": "Press 1 to replay the message.",
  • "replay-prompt-type": "File",
  • "outro-prompt": "Press 1 to replay the message.",
  • "outro-prompt-type": "File",
  • "max-replays": 3,
  • "auto-replay": false,
  • "voice": {
    },
  • "voicemail-response": "Ignore"
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "call-id": "19b3153e-09e5-40c5-8394-9bb42ff64302",
  • "instruction-id": "string",
  • "queue-id": "string",
  • "caller": "string",
  • "callee": "string",
  • "success": true,
  • "error": "string"
}