Voice API

Introduction

The Voice API is a system that enables you to easily write IVR (Interactive Voice Response) applications without setting up complicated telephone systems. The Voice API is actually not a web API, but rather a client, as it will call your server to inform it of updates and ask for the next step(s) to perform. The Voice API server will call your http(s) server using a POST command and it will send JSON data containing information on a new incoming call, a newly setup outgoing call (not supported yet) or a status update on a call (done playing audio file for instance). Your server will have to acknowledge this new information and reply with the next steps, such as "play an audio file", "make a voice recording" or "get DTMF (number) input". When the Voice API has performed these steps, it will again contact your server with updates on these steps and your server will again give it the next step(s), etc. Only when the Voice API sends a "disconnected" message will it not be expecting a new step to take, it will just expect a 200 - OK message.

Prerequisites

Connection Details

The location (URL) of your server needs to be configured in the system, along with the (inbound) phone number associated. Using this information, the Voice API knows what incoming phone call to connect to what server.

Right now, this is something that CM has to do, but a portal is on its way!

Custom audio files

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

  • Bit rate: 64 kbps
  • Sample size: 8 bit
  • Channels: Mono
  • Audio sample rate: 8 kHz (8000 Hz)
  • Audio codec: G711-A-law (PCM)
  • Filename: *.wav

In order to use custom audio files, they need to be available to the Voice API. This is facilitated using an SFTP server, which allows you to upload your custom audio files onto our servers. The URL and credentials for this server will be supplied upon registration.

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

Custom audio files for Spell instruction

In order to use files with the Spell instruction (See chapter Spell instruction), you need to upload a set of audio files in the following directory structure on the SFTP server:

/spelling/00/*.wav

Where ‘00’ is the number of the set, being anything between 00 to 99. 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.

Your server

Your server, which handles the POST commands of the Voice API should be a HTTP(S) server with a basic POST handler. If you want to encrypt the data sent between the Voice API and your server (which we highly recommend), this server has to be a HTTPS server, using its own SSL certificate.

All the different POST commands will be sent to the same endpoint (same URL), no matter the contents. The difference is purely in the contents of the JSON.

The server must respond as quickly as possible (ideally within 300 ms), any delay makes the call feel awkward and unnatural to the caller. If the server does not respond within 5000 ms (5 seconds), an error prompt will be played to the caller and the call will be disconnected. A Disconnected Event will also be sent to your server.

Events (POST Commands)

Every communication between the Voice API server and your server is initiated by the Voice API Server, which sends a POST command your server. The next step(s) is/are specified in the response to this POST command.

The following events are supported by the Voice API:

  • New call (a new call is available)
  • Done (an instruction without return value has been completed)
  • DTMF received (following a get-dtmf instruction, returns the received DTMF digits)
  • Recorded (a new voice recording has been made)
  • Disconnected (the call has been disconnected, either following a disconnect instruction, or because the caller disconnected)

Since the Voice API supports sending and receiving multiple events and instructions at once, events are always wrapped in an array named 'events'.

{
  "events": []
}

New call event

When a call is received for your phone number, a HTTP POST will be sent to your server, basically informing it of the new call and asking for a first instruction to perform on this call.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the instruction. Always “new-call” when a new call is received.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
caller Alphanumeric 25 Yes This is the phone number of the caller, if known, “anonymous” otherwise. Phone numbers are always in international format E.164.
called Alphanumeric 25 Yes The phone number called by the caller. Phone numbers are always in international format E.164.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.

{
  "events": [
    {
      "type": "new-call",
      "call-id": "586b1c6a-3e7c-41a6-bc27-80c2360f842e",
      "caller": "+31...",
      "called": "+31...",
      "direction": "inbound",
      "signature": "f9d0be502f3e76c2539097891b7fd6c25470dab07c02dae688eb38172d3da44d"
    }
  ]
}

Done event

This HTTP POST is sent after the last instruction has been completed, for instance the audio file has been played to the caller, as requested.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the instruction. Always “done” for events that simply indicate that an instruction has been performed.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.

{
  "events": [
    {
      "type": "done",
      "call-id": "586b1c6a-3e7c-41a6-bc27-80c2360f842e",
      "instruction-id": "089881ad-fc03-47ab-bad6-e558eb7e3891",
      "signature": "f56cb457f75bd117a9619e4f59af325234a1e9c4d056f81b1a9afaa7370290a6"
    }
  ]
}

DTMF received event

This HTTP POST will be sent as a response to a ‘get-dtmf’ instruction, after we have received DTMF data from the caller.

In case no input, or no correct input was received, the field “digits” will contain an empty string.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the instruction. Always “dtmf” for an event that returns the dtmf digits received as the result of a get-dtmf instruction.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier.
digits Alphanumeric 64 Yes 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.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.

{
  "events": [
    {
      "type": "dtmf",
      "call-id": "586b1c6a-3e7c-41a6-bc27-80c2360f842e",
      "instruction-id": "4a5114dd-4fb3-47d2-947a-1d4599a5023f",
      "digits": "1234",
      "signature": "21e0f584f98199410dfb5b112cc5ab4e29363526ec452f2ad093dafd9de6c99b"
    }
  ]
}

Recorded event

This HTTP POST is sent after a recording has been made. It sends the name of the file (a UUID + .wav), which can be downloaded from the FTPS server in the /recordings folder. Note that you can easily read back the recording to the user by issuing a Play File instruction using the just recorded file (i.e. /recordings/filename.wav) as the file to be played.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the instruction. Always “recorded” for the event informing the server that a recording has been made.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier.
file-name Alphanumeric 40 Yes The filename, which is made up as a UUID + .wav.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.

{
  "events": [
    {
      "type": "recorded",
      "call-id": "586b1c6a-3e7c-41a6-bc27-80c2360f842e",
      "instruction-id": "75144728-f613-435c-bbe3-45b682fe43f3",
      "file-name": "96c6cf33-5da0-4612-870a-00e7ba6dddc2.wav",
      "signature": "5b701f90929a865967b166801c2d631f9546fd482efd8be124c1f70d70896e2b"
    }
  ]
}

Disconnected event

This HTTP POST is sent whenever the connection with the caller is lost. Only if it is a result of a disconnect instruction by the customer will it include an instruction-id.

Be advised, this event can happen at any time during the call so please make sure your software can handle this event at any moment.

Whenever a caller disconnects before an instruction has been completed, a disconnect will be sent to the server, but no done or other event indicating that the last instruction was completed.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the instruction. Always “disconnected” for the event informing the server that the call has been disconnected.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 No The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier, if this disconnect is the result of such an instruction. Omitted if the disconnect was initiated by the caller or the result of an error.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.

{
  "events": [
    {
      "type": "disconnected",
      "call-id": "586b1c6a-3e7c-41a6-bc27-80c2360f842e",
      "instruction-id": "85f16991-5a73-4979-8da0-d48f6752f673",
      "signature": "5bc12fc6860143f6bf4f1eca1d09e0736ce7d0e0651649b6fa85d3142d27c0e0"
    }
  ]
}

Combining multiple events in one POST

When the Voice API received multiple instructions in a single reply from the server at the customer, the resulting events of these instructions will be combined in a single POST afterwards. For instance:

This could be a POST after receiving instructions for playing a file, retrieving some dtmf and disconnecting afterwards.

Please note that even though the instructions are combined, they still each have their unique instruction-id and signature.

For a series of instructions, if the caller disconnects during the execution of the instructions, only the completed ones will have an event in the POST, together with the disconnect event.

{
  "events": [
    {
      "type": "done",
      "call-id": "586b1c6a-3e7c-41a6-bc27-80c2360f842e",
      "instruction-id": "089881ad-fc03-47ab-bad6-e558eb7e3891",
      "signature": "f56cb457f75bd117a9619e4f59af325234a1e9c4d056f81b1a9afaa7370290a6"
    },
    {
      "type": "dtmf",
      "call-id": "586b1c6a-3e7c-41a6-bc27-80c2360f842e",
      "instruction-id": "4a5114dd-4fb3-47d2-947a-1d4599a5023f",
      "digits": "1234",
      "signature": "21e0f584f98199410dfb5b112cc5ab4e29363526ec452f2ad093dafd9de6c99b"
    },
    {
      "type": "disconnected",
      "call-id": "586b1c6a-3e7c-41a6-bc27-80c2360f842e",
      "instruction-id": "85f16991-5a73-4979-8da0-d48f6752f673",
      "signature": "5bc12fc6860143f6bf4f1eca1d09e0736ce7d0e0651649b6fa85d3142d27c0e0"
    }
  ]
}

Instructions (POST responses)

Upon receiving a POST command from the Voice API server, your server needs to reply with the next step to take. This chapter describes the possible steps and their possible parameters.

Please note that the instruction-id’s have to be generated on your server and will be used in the result that will be sent once the instruction has been performed by the API. Also note that all UUID’s must be communicated in lowercase.

The following instructions are supported:

  • Play file (plays an audio file to the caller)
  • Get DTMF (plays an audio file and retrieves DTMF (number pad) input from the caller)
  • Spell (Spells out a given code to the caller)
  • Record (makes a voice recording of the caller)
  • Disconnect (disconnects the call – or “hangs up”)

Since the Voice API is capable of sending arrays of events and instructions, instructions are always encapsulated by an array called 'instructions'.

{
  "instructions": []
}
Play file instruction

This instructs the Voice API server to play an audio file to the caller. The file needs to be available on the FTP server at CM.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the instruction. Always “play-file” for an instruction to play an audio file to the caller.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier, generated by the customer’s server.
filename Alphanumeric 128 Yes The (path and) name of the file to play. The path is always relative to the root of the FTP folder of the customer.
terminators Alphanumeric 8 No (default = *) The key(s) that can be pressed to stop the playback.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.
{
  "instructions": [
    {
      "type": "play-file",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "9510d84e-58e8-4836-839b-c05ba4615571",
      "filename": "prompts/en/hello.wav",
      "terminators": "#",
      "signature": "b19ce26b5e5a85e21a619c8f9af47365ee460ce37350afb4493bdf5e79814587"
    }
  ]
}
Get DTMF instruction

This instructs the Voice API server to ask for and receive DTMF input from the caller. It will play the given prompt file, which should contain the instruction for the caller and records the DTMF that the caller sends during or after this instruction. Note that the instruction will stop playing on input by the caller.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the instruction. Always “get-dtmf” for an instruction to ask the caller for dtmf input.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier, generated by the customer’s server.
min-digits Numeric 8 No (default = 1) Minimum number of digits to receive. Value must be between 1 and 64.
max-digits Numeric 8 No (default = 1) Maximum number of digits to receive. Value must be between 1 and 64, but greater than or equal to min-digits.
max-attempts Numeric 8 No (default = 1) Maximum number of retries before receiving DTMF is cancelled. A fail can be when the user enters too few digits before pressing the terminator, or the input does not match with the regex. Value must be between 1 and 10.
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 #”.
prompt-filename Alphanumeric 128 Yes The (path and) name of the file to play. The path is always relative to the root of the FTP folder of the customer.
input-error-filename Alphanumeric 128 No (default = empty) The (path and) name of the file to play after a failed attempt. If none supplied, the prompt is just played again. The path is always relative to the root of the FTP folder of the customer.
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.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.
{
  "instructions": [
    {
      "type": "get-dtmf",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "8a39e321-e832-4dd5-8c73-d244e0fff7b4",
      "min-digits": 1,
      "max-digits": 4,
      "max-attempts": 3,
      "timeout": 1000,
      "terminators": "#*",
      "prompt-filename": "prompts/en/EnterSomething.wav",
      "input-error-filename": "prompts/en/Retry.wav",
      "regex": "[1-9]\\d*",
      "signature": "d39b01c5dbea827c266675850d814f22bbfbc9f9b799d5bfd78f8b011fb3adb2"
    }
  ]
}
Spell instruction

This instruction spells out a given code to the caller. Please note that the code is read character per character, so 123 is read as “one, two, three”, not as “one hundred and twenty-three”.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the instruction. Always “spell” for an instruction to spell out a code to the caller.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier, generated by the customer’s server.
language Alphanumeric 2 No (default = en) The language to use for reading the code. Please check with CM which languages are available*.
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.
time-between Numeric 8 No (default = 500) The time (in ms) between each character while reading them to the caller. Value must be between 1 and 10000.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.

* The supported languages at the time of writing are:

Language Parameter Value Available Characters
English (Default) en 0-9, A-Z
Dutch nl 0-9, A-Z
Spanish es 0-9
Italian it 0-9
German de 0-9
French fr 0-9
Custom 00, 01, 02, etc.** 0-9, A-Z***

** Every custom set of voice files is numbered 00, 01, 02, etc. See chapter Custom audio files for spell instruction for more information.

*** The availability depends on the voice files uploaded for the selected set.

{
  "instructions": [
    {
      "type": "spell",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "7b00c56c-b84d-425d-a36a-42317a28e5b1",
      "language": "en",
      "code": "12357",
      "time-between": 650,
      "signature": "fde9063276b73efc53a71fba1a252109eb2dac1beb54ea4ffd81cc0bef598eea"
    }
  ]
}
Record instruction

This instruction makes a recording of the voice of the caller. This can be used to have the caller say his or her name, or her place of residence.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the instruction. Always “record” for an instruction to make a recording.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier, generated by the customer’s server.
max-recording-time Numeric 8 Yes The maximum time (in seconds) to record. The value must be between 1 and 120 seconds.
silence-time Numeric 8 No (default = 3) The time (in seconds) the caller needs to be silent for the recording to stop. Value must be between 1 and 30 seconds.
silence-threshold Numeric 8 No (default = 200) The "sound energy" below which audio is seen as "silent". A higher value will help ending the recording with silence-time in noisy environments. Value must be between 1 and 1000.
terminators Alphanumeric 8 No (default = *) The key(s) that can be pressed to stop the recording.
prompt-filename Alphanumeric 128 No The (path and) name of the file to play before starting the recording. The path is always relative to the root of the FTP folder of the customer. Tip: make this prompt end with a 'bing' sound as a cue to the caller to start talking.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.
{
  "instructions": [
    {
      "type": "record",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "c3be328d-f037-4b83-a567-46f9b9d0b7a1",
      "max-recording-time": 30,
      "silence-time": 3,
      "silence-threshold": 500,
      "terminators": "#",
      "prompt-filename": "prompts/en/SayName.wav",
      "signature": "d879613e4330d4e667aee58775addea4a0b60d8615b9ec35e1d0d5ad002d0519"
    }
  ]
}
Disconnect instruction

This instruction ends the connection with the caller. This should normally only be done when the IVR flow has completed and preferably following an audio file that explains the fact that the conversation is over and the connection will be ended, giving the caller the opportunity to do so before the system does.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the instruction. Always “disconnect” for an instruction to disconnect the call.
call-id UUID / GUID 36 Yes The 36 character (lowercase including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier, generated by the customer’s server.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.
{
  "instructions": [
    {
      "type": "disconnect",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "86d8e963-d96a-40e4-be37-e7bb5ef8d45c",
      "signature": "41cde2f2b43ec78fa63834b7bb3798f652e8fc80043a4084565d181c7576c761"
    }
  ]
}
Combine multiple instructions in one response

In order to send a sequence of instructions that need to be executed in the given order, you can combine multiple instructions in a JSON array when replying to a POST command. For instance:

Please note that even though the instructions are bundled, they still each need their own (unique) instruction-id and signature.

{
  "instructions": [
    {
      "type": "play-file",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "9510d84e-58e8-4836-839b-c05ba4615571",
      "filename": "prompts/en/hello.wav",
      "signature": "0ff791e25c3b76161b429d476e694878de0135e18ad61ea3b494bb6c3a42e0d5"
    },
    {
      "type": "get-dtmf",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "8a39e321-e832-4dd5-8c73-d244e0fff7b4",
      "min-digits": 1,
      "max-digits": 4,
      "max-attempts": 3,
      "timeout": 1000,
      "terminators": "#*",
      "prompt-filename": "prompts/en/EnterSomething.wav",
      "input-error-filename": "prompts/en/Retry.wav",
      "regex": "[1-9]d*",
      "signature": "d39b01c5dbea827c266675850d814f22bbfbc9f9b799d5bfd78f8b011fb3adb2"
    },
    {
      "type": "disconnect",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "86d8e963-d96a-40e4-be37-e7bb5ef8d45c",
      "signature": "41cde2f2b43ec78fa63834b7bb3798f652e8fc80043a4084565d181c7576c761"
    }
  ]
}

Exceptions

When an exception occurs in the Voice API, it will send a POST command informing the server at the customer of this exception.

Invalid JSON exception

Whenever the Voice API receives an instruction that could not be properly parsed from the JSON text, it will send a new POST command with an Invalid JSON exception.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the event. Always exception for an exception.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 No The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier.
code Numeric 8 Yes Code for the exception, for an Invalid JSON exception, this is always 400.
title Alphanumeric 32 Yes Title of the exception. For an Invalid JSON exception this will always read “invalid json”.
message Alphanumeric 1000 Yes Readable description of the exception.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.

Please note that – in contrast to all other exceptions – the field instruction-id is optional for this exception. If the received JSON was so malformed that the Voice API could not get this value from the JSON string, this field will be omitted.

{
  "events": [
    {
      "type": "exception",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "9510d84e-58e8-4836-839b-c05ba4615571",
      "code": 400,
      "title": "invalid json",
      "message": "The JSON could not be properly parsed.",
      "signature": "fd040550c72fcb76f2396d2c6a5602f01ae8995e564fdfcc0004ff78e49b71c6"
    }
  ]
}
Invalid instruction exception

Whenever the JSON string can be parsed, but the contents do not represent a valid instruction, i.e. the type of instruction is unknown, the Voice API will send a new POST command with an invalid instruction exception.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the event. Always exception for an exception.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier.
code Numeric 8 Yes Code for the exception, for an invalid instruction exception, this is always 405.
title Alphanumeric 32 Yes Title of the exception. For an Invalid Instruction exception this will always read “invalid instruction”.
message Alphanumeric 1000 Yes Readable description of the exception.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.
{
  "events": [
    {
      "type": "exception",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "9510d84e-58e8-4836-839b-c05ba4615571",
      "code": 405,
      "title": "invalid instruction",
      "message": "The type of instruction could not be mapped.",
      "signature": "68a904f69689b7a84c6d844b9cc43322c1e7ffac2f361074dd27fc0ade339d5b"
    }
  ]
}
Invalid parameter exception

When the Voice API misses a required parameter for an instruction, or finds an invalid value for a parameter, it will send a new POST command with an Invalid Parameter exception.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the event. Always exception for an exception.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier.
code Numeric 8 Yes Code for the exception, for an invalid parameter exception, this is always 406.
title Alphanumeric 32 Yes Title of the exception. For an Invalid Instruction exception this will always read “invalid parameter”.
message Alphanumeric 1000 No Readable description of the exception.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.
{
  "events": [
    {
      "type": "exception",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "9510d84e-58e8-4836-839b-c05ba4615571",
      "code": 406,
      "title": "invalid parameter",
      "message": "The value for min-digits needs to be numeric.",
      "signature": "a5cad06d4a781803e53177169d885d1c3f6c1fc4120758a66bee2db0763570c4"
    }
  ]
}
Signature exception

When the signature given in an instruction does not fit the type of the instruction and its parameters, the Voice API will send a new POST command with a signature exception. See chapter Security for more information on the signature field.

Note that the signature field here contains a new signature for the exception event, not the signature that was wrong.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the event. Always exception for an exception.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier.
code Numeric 8 Yes Code for the exception, for a signature exception, this is always 401.
title Alphanumeric 32 Yes Title of the exception. Always “signature error” for a Signature exception.
message Alphanumeric 1000 Yes Readable description of the exception.
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter 6 Security for more info.
{
  "events": [
    {
      "type": "exception",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "9510d84e-58e8-4836-839b-c05ba4615571",
      "code": 401,
      "title": "signature error",
      "message": "The given signature is not correct.",
      "signature": "ef392ef871eddfbebdedccf5513f747b38840ba5ecafadf4c7e32092802176ee"
    }
  ]
}
File not found exception

When the Voice API receives an instruction to play a file, but it cannot find the file specified, it will send a new POST command with information on what file could not be found.

Variable definition

Variable Data type Length Required Description
type Alphanumeric 32 Yes The type of the event. Always exception for an exception.
call-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests.
instruction-id UUID / GUID 36 Yes The 36 character (lowercase, including dashes) hexadecimal representation of the instruction identifier.
code Numeric 8 Yes Code for the exception, for a file not found exception, this is always 404.
title Alphanumeric 32 No Title of the exception. Always “file not found” for a File Not Found exception.
message Alphanumeric 1000 Yes Readable description of the exception
signature Alphanumeric 64 Yes Contains the signature, making sure the message cannot be tampered with. See chapter Security for more info.
{
  "events": [
    {
      "type": "exception",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "9510d84e-58e8-4836-839b-c05ba4615571",
      "code": 404,
      "title": "file not found",
      "message": "The following file could not be found: prompts/en/helo.wav.",
      "signature": "ed9b65b8d4ff99c431c2caa3a2628d1c105796a4ce9c47c087debf12b4d5e7d6"
    }
  ]
}

Security

In order to provide security, every single message sent between the Voice API and your server is signed with a SHA-256 signature.

This signature is constructed using a shared password and every parameter key and value in the event or instruction that is sent, as following:

<password><key1><value1><key2><value2><key3><value3>...

Where:

  • <password> is the shared password
  • <keyX> and <valueX> are the key and value of the Xth variable in the JSON string

Important notices:

  • Concatenate all the keys and values as they are, from quote to quote (but without the quotes themselves)
  • Maintain the order of the parameters as described in this document. If the order of the keys and values in the hash does not match the order described in this document, a signature exception will be sent to your server.
Examples
Example 1 - a single dtmf event

The signature for this example is constructed as the SHA-256 hash over the following, where the shared password = ‘password’:

passwordtypedtmfcall-id586b1c6a-3e7c-41a6-bc27-80c2360f842einstruction-id4a5114dd-4fb3-47d2-947a-1d4599a5023fdigits1234

Resulting in the following hash:

21e0f584f98199410dfb5b112cc5ab4e29363526ec452f2ad093dafd9de6c99b

{
  "events": [
    {
      "type": "dtmf",
      "call-id": "586b1c6a-3e7c-41a6-bc27-80c2360f842e",
      "instruction-id": "4a5114dd-4fb3-47d2-947a-1d4599a5023f",
      "digits": "1234",
      "signature": "21e0f584f98199410dfb5b112cc5ab4e29363526ec452f2ad093dafd9de6c99b"
    }
  ]
}
Example 2 - a single get-dtmf instruction

The signature for this example is constructed as the SHA-256 hash over (again using ‘password’ as the shared password):

passwordtypeget-dtmfcall-id81536d6f-6a9f-4906-8ef8-cb1e5643f885instruction-id8a39e321-e832-4dd5-8c73-d244e0fff7b4min-digits1max-digits4max-attempts3timeout1000terminators#*prompt-filenameprompts/en/EnterSomething.wavinput-error-filenameprompts/en/Retry.wavregex[1-9]\\d*

Resulting in the following hash:

d39b01c5dbea827c266675850d814f22bbfbc9f9b799d5bfd78f8b011fb3adb2

{
  "instructions": [
    {
      "type": "get-dtmf",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "8a39e321-e832-4dd5-8c73-d244e0fff7b4",
      "min-digits": 1,
      "max-digits": 4,
      "max-attempts": 3,
      "timeout": 1000,
      "terminators": "#*",
      "prompt-filename": "prompts/en/EnterSomething.wav",
      "input-error-filename": "prompts/en/Retry.wav",
      "regex": "[1-9]\\d*",
      "signature": "d39b01c5dbea827c266675850d814f22bbfbc9f9b799d5bfd78f8b011fb3adb2"
    }
  ]
}
Example 3 - omitted parameters

This is an example with omitted parameters. The signature is constructed as the SHA-256 hash over (again using ‘password’ as the shared password):

passwordtypeget-dtmfcall-id81536d6f-6a9f-4906-8ef8-cb1e5643f885instruction-id8a39e321-e832-4dd5-8c73-d244e0fff7b4prompt-filenameprompts/en/EnterSomething.wav

Resulting in the following hash:

6c7ea1f1c0ca297dc4803c0b462fc7eec668cb0421a31904b9aea0618a234fee

Note that it has 5 parameters omitted between instruction-id and prompt-filename and two omitted parameters after prompt-filename.

{
  "instructions": [
    {
      "type": "get-dtmf",
      "call-id": "81536d6f-6a9f-4906-8ef8-cb1e5643f885",
      "instruction-id": "8a39e321-e832-4dd5-8c73-d244e0fff7b4",
      "prompt-filename": "prompts/en/EnterSomething.wav",
      "signature": "6c7ea1f1c0ca297dc4803c0b462fc7eec668cb0421a31904b9aea0618a234fee"
    }
  ]
}