Messages

Voice messages

Whispir’s API provides you with the ability to send a voice message to any landline phone or mobile phone around the world.

Whispir supports both text-to-speech and pre-recorded WAV file approaches to sending voice calls.

Using Whispir’s Voice module, you can easily connect all recipients to a single bridged call, simplifying your teleconferences and ensuring your message gets through.

Notes:

  • The Subject field is mandatory.
  • The Body field is mandatory.
  • The Type field is mandatory and, at a minimum, it must specify the following string: <type>ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:</type>
  • The Type field is mandatory even when no conference call is being used.
  • Pauses can be added to conference call details using the plus (+) character. Each + represents 1 second. (Pauses allow some wait time to ensure the conference call service is ready to accept the account number and PIN.)

Your account must be enabled to use the Voice capability within Whispir for this to function. If you're unsure whether you can use Voice, contact the Whispir Support Team

Custom variables for voice calls

@@teleconf_number@@

When teleconferencing services are used as part of voice calls, the teleconference line that is used in the voice call can be accessed via this variable.

For example, 1800 123 123.

@@teleconf_account@@

When teleconferencing services are used as part of voice calls, the teleconference account or room number that is used in the voice call can be accessed via this variable.

For example, 098711234.

@@teleconf_pin@@

When teleconferencing services are used as part of voice calls, the teleconference room PIN that is used in the voice call can be accessed via this variable.

For example, 8181.

@@teleconf_mod_pin@@

When teleconferencing services are used as part of voice calls, the teleconference moderator PIN that is used in the voice call can be accessed via this variable.

For example, 8181.

Whispir’s Voice module doesn’t include a conference call service. Users can easily integrate existing conference call services using the fields provided.

Using custom WAV files as the content for voice calls

The Whispir API provides users with the ability to compose voice calls using text-to-speech (TTS) functionality as well as allowing users to provide custom WAV files to be played over the phone.

Attachments must be WAV files and can be up to 10 MB in size (that is, the maximum size of all attached files combined is 10 MB).

Each voice call is made up of four parts:

  • Message introduction: Either TTS or a WAV file. Mandatory for all messages.
  • Message acceptance: Asks the recipient to press a button to accept the message.
  • Message content: The concatenation of the message subject and message body (either TTS or a WAV file).
  • Message response: Allows the recipient to acknowledge the message, via either the default options or based on a response rule.

WAV file criteria

Before a WAV file can be played, it needs to conform to certain criteria:

  • All WAV files must be a maximum of 8 bit, 8000 Hz, 1ch, 64 kbps.
  • If a WAV file is outside these criteria, TTS will be used instead. It’s vital that TTS is provided even when using WAV files.
  • All of the WAV files combined must not exceed 10 MB in total file size.

Notes:

  • attachmentName: The name of the file being attached (mandatory).
  • attachmentDesc: For the WAV file to be played as the introduction, it must be voiceintro.wav.
  • attachmentDesc: For the WAV file to be played as the body, it must be voicebody.wav.
  • deferUri: The base64 representation of the WAV file being played.
  • Important! In the case of JSON, the attachment element is also an array, so be sure to add the square brackets!
  • JSON
  • XML

Sending voice messages

{{codeStart}}

HTTP 1.1 POST https://api.<region>.whispir.com/messages?apikey=[your_api_key]

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

Content-Type: application/vnd.whispir.message-v1+json

{

"to" : "+1000000000",

"subject" : "Test Voice Call",

"voice" : {

"header" : "This is the introduction of the voice call",

"body" : "This is the body of the message",

"type" : "ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:"

}

}

{{codeEnd}}

 

Sending voice messages with teleconferences

{{codeStart}}

HTTP 1.1 POST https://api.<region>.whispir.com/messages?apikey=[your_api_key]

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

Content-Type: application/vnd.whispir.message-v1+json

{

"to" : "+1000000000",

"subject" : "Test Voice Call",

"voice" : {

"header" : "This is the introduction of the voice call",

"body" : "This is body of the message",

"footer" : "This is the footer of the message",

"type" : "ConfCall:1800500536,

ConfAccountNo:12345678,

ConfPinNo:1234,

ConfModPinNo:1234,

Pin:"

}

}

{{codeEnd}}

 

 

{{codeStart}}

HTTP 1.1 POST https://api.<region>.whispir.com/messages?apikey=[your_api_key]

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

Content-Type: application/vnd.whispir.message-v1+json

{

"to" : "61423568958",

"subject" : "Test voice call with attachments",

"voice" : {

"body" : "Will be replaced by the voicebody.wav file",

"header" : "Will be replaced by the voiceintro.wav file",

"type" : "ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:",

"resources" : {

"attachment" : [{

"attachmentName" : "Introduction.wav",

"attachmentDesc" : "voiceintro.wav",

"derefUri" : "..."

},{

"attachmentName" : "Body.wav",

"attachmentDesc" : "voicebody.wav",

"derefUri" : "..."

}]

}

}

}

{{codeEnd}}