Voice Messaging

Initiate a call

Initiate a call

In order to initiate a call, a number of parameters should be passed in the body of the API request sent to the API. Eventually, all destinations provided in the requested are called. The request should be encoded in JSON.

Check the samples section for a sample JSON request.

The table below defines the body of the request.

Legend for “Optional” → “Opt” column: N → No; Y → Yes; C → Conditional;

 

Request Body

Key Type Opt Description
destinations DESTINATION_INFO[] N No default value.

This defines the list of destinations which will be called. Maximum number of destination depends on the Routing Preference chosen.

Voice: Allows up to 500 destinations

Voice Plus: Only 1 destination

job_id String Y Default Value: Null

This is an optional custom identifier, which when provided will be included in all call backs.

voice_content VOICE_CONTENT N No default value.

Includes several parameters which are used to initiate a job.

callback_url String Y Default Value: Use the value specified in Token

If provided, the system will send several log information in real time about each call through HTTP POST (i.e. ringing, hang up etc.)
If there is no Callback URL specified, all job statistics have to be manually checked from the Client Control Panel.(i.e. http://example.com/callback)

 

DESTINATION_INFO[]

Key Type Opt Description
custom_id String Y Default Value: Null

This is a custom identifier used to distinguish each call within a job. In the same job, this field should be unique per destination.

number String Y No default value.

This is a mandatory field which defines the recipient of the call.

  • Must not have any plus signs or leading 0
  • Must be supplied with a prefix (e.g 35699000000)
  • Minimum Length: 7
  • Maximum Length: 20
  • Only numeric characters

 

VOICE_CONTENT

To determine whether a call is a Text-To-Speech or an audio file job, the appropriate parameters must be supplied

  • For Text-To-Speech jobs use the parameter called “tts_text”, “tts_voice” and “tts_lang”
  • For audio file jobs use the parameter called “audio_file_url”
Key Type Opt Description
sender_id String N Default Value: Value specified in Token.

This is the source number from where the call will show as originating from.

  • Minimum Length: 7
  • Maximum Length: 20
  • Must not have any plus signs or leading 0
  • Must be only numeric
tts_text String C No Default Value

If text-to-speech functionality is to be used, this field is mandatory. This will determine the text that will be read during the call.

Be sure to use standard characters when passing the tts_text parameter for better legibility.

  • Minimum Length: 10
  • Maximum Length: 500

NB. When using Audio jobs, this parameter must not be used

tts_lang String C Default Value: Value specified in Token.

If text-to-speech functionality is to be used, this field is mandatory.

Determines the language that is spoken in the text-to-speech. Options

  • da-DK (Danish)
  • nl-NL (Dutch)
  • en-AU (English Australian)
  • en-GB (English – British)
  • en-US (English – USA)
  • fr-FR (French)
  • fr-CA (French – Canadian)
  • de-DE (German)
  • it-IT (Italian)
  • pl-PL (Polish)
  • pt-PT (Portuguese)
  • ru-RU (Russian)
  • es-ES (Spanish)
  • es-US (Spanish – USA)
  • sv-SE (Swedish)
tts_voice String C Default Value: Value specified in Token.

If text-to-speech functionality is to be used, this field is mandatory. This will determine the gender for text-to-speech’s voice used in the call.

  • man
  • woman

There are some voice limitations on certain languages with regards to voices (e.g ru-RU
only supports female voice)

audio_file_url String C No Default Value

This is a mandatory field if Audio File functionality is to be used for a job.

This parameter is used to determine the audio file to be played during the call. This Audio File URL must be publicly available on the internet.

(i.e. http://example.com/audio_clip_001.mp3)

Audio File Details

File Formats: MP3 or WAV files (only HTTP requests with header content-type set to audio/mpeg & audio/x-wav are accepted).

Duration: There is no actual duration length, however a bigger file might take more time to load during the call.

Quality: There is no limitation on the bit rate of the file, since it will be transcoded automatically into an adequate bit rate for PSTN.

When using Text-To-Speech jobs, this parameter must not be used

hangup_ring_seconds Integer Y Default Value: Use the value specified in token

Hangs up the call after X seconds (even if the call is ringing or currently in progress) from when the call was initiated.

If this is parameter is not passed, then there will be no time out.

The value must be in seconds (i.e. 50)

This value in seconds, is not accurate due to the delay between the call and the carrier itself. In technical terms, if 20 seconds is supplied, it may be that this varies by a few seconds.

Minimum : 20 seconds

time_limit_seconds Integer Y Default Value: Use the value specified in token (if set)

Hang up the call after X seconds after the call was answered

If this is parameter is not passed, then there will be no time out.

The value must be in seconds (i.e. 50)

This value in seconds is not accurate due to the delay between the call and the carrier itself. In technical terms,  if 20 seconds is supplied, it may be that this varies by a few seconds.

Minimum : 20 seconds

ring_timeout_seconds Integer Y Default Value: Use the value specified in Token (if set)

Determines the number of seconds that a call should ring. If the call is not answered within this period, the call is cancelled.

If this is parameter is not passed, then there will be no time out.

The value must be in seconds (i.e. 50)

This value in seconds is not accurate due to the delay between the call and the carrier itself. In technical terms, if 20 seconds is supplied, it may be that this varies by a few seconds.

Minimum : 20 seconds

enable_menu_response Boolean Y Default Value: Use the value specified in token (set to “True” upon token creation)

When this is set to “true”, it will allow the user to press any digit (keypresses) between 0-9 during the call. This response will be then logged and immediately followed by a call hang up. This response can be viewed later on in the Client Control Panel or through real-time callbacks.

If this is set to “False”, any key-presses during the call are ignored.

Get Started