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

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

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

X-CM-PRODUCTTOKEN

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

For outbound calls, only the URL of your server has to be known.

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

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

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

Other formats might work, but mileage may vary.

Uploading files using Audio Manager
In order to use custom audio files, they need to be available to the Voice API. You can use the Audio Manager CM Platform app for this (https://audiomanager.cmtelecom.com). This app is available to all customers with a Voice API / apps account. If in any case you have no access to the app, please contact support@cm.nl

You are free to create any directory structure on this server, just make sure you supply the whole path from the root of the Audio Manager when sending an instruction that requires an audio file. E.g. /test-folder/testaudio.wav

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

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/en-GB/*.wav

Where ‘en-GB’ is the language (including locale) of the set. This must be a 5-character string. 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.

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

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

Variable definition

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 body.

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.

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

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

Variable definition

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

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. Please note that the recording might not be immediately available on the server, the event simply indicates that the end user has finished the recording and should be presented with the next step in the flow.

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

This HTTP POST is sent after a bridge has been attempted.

Variable definition

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

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.

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.

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

Notice

Due to the fact that voicemail detection was not up to CM standard, it has been switched off for the time being. We are working on a new solution.

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

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

The supported languages for the Default prompt-type at the time of writing are:

If you want to use your own custom prompts, see chapter Custom audio files for spell instruction for more information.

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

Variable definition

This instructs the Voice API server to bridge (forward) the call to another callee.

Variable definition

* 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.

This instructs the Voice API server to just wait and do nothing. Usually only used to have a bridged call just go for a given time.

Variable definition

The wait instruction will result in a Done event.

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

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.

In order to initiate an outbound call, you can send a place-call instruction to the Voice API server(s). The API-call will immediately return, returning the call-id for the new call (if the instruction is accepted). When (and if) the phone call is answered, a POST command will be sent to your server, equal to the flow of an incoming call. Basically the only difference is the field direction, which will now contain the word outbound rather than inbound.

Variable definition

In contrast to the other instructions, the place-call instruction does not have a type field - since the type is determined by the endpoint used - and the instruction-id is not required - since the resulting event is logically linked to the instruction.

There are also other instructions you can send to the CM server(s) like the place-call instruction, which will initiate a pre-configured flow, without the need of a server to handle POST-commands. These instructions are explained in the Voice API Apps documents.

* 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.

The call-queued event is the only event that is actually sent as a response to a POST command (namely the place-call instruction). The call-queued instruction only informs your software of the fact that the call has been accepted, is currently queued to be dialled and has the given call-id assigned to it. Further processing is done in the exact same way as for inbound calls, with the only difference being the value of the direction field in the new-call event, which is now outbound of course.

Variable definition

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

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.

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

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

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

In order to test your authentication logic, the VoiceAPI hosts a special "Check authentication" endpoint at:

https://voiceapi.cmtelecom.com/v2.0/CheckAuthentication

This endpoint accepts POST requests, containing any body you like. You have to add the Authorization header as described in this chapter, signing the chosen body for the request.

The service will respond with either a 200 - OK (in case the signature is correct) or a 401 - Unauthorized message.

For this example, let us assume your username is 'myusername' and your HMAC key (Shared Key) is KWWppDsf1bm8nZZqmnCtl/RZR&CB2wHq.

So, for instance, you might send the following body:

check authentication

Using this body as the HMAC body and your shared key as the HMAC Key, we get the following hash:

dc05cbba45eb2276fecc3e723413113e7edd6721ff2df8ce12c5828ef513a57e

Combining that with your username, this will give the following Authorization header:

username=myusername;signature=dc05cbba45eb2276fecc3e723413113e7edd6721ff2df8ce12c5828ef513a57e

Sending this to the endpoint will result in a 200 - OK (which it actually does not, since this user does not exist). If you change anything to either the body or the code, the endpoint will return a 401 - Unauthorized.