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, both via text-to-speech and custom WAV files to be played over the phone

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

Each voice call is made up of three parts:

  • Message introduction: Either TTS or a WAV file
  • Message acceptance: Asks the recipient to press a button or insert a PIN to hear the message
  • Message content: The concatenation of the message subject and message body. The latter can be either TTS or a WAV file. At the end the recipient will be given the possibility to acknowledge the message

In order to use this functionality your account must be enabled to use the Voice module. If you're unsure whether you can use Voice, please contact the Whispir Support Team

  • JSON
  • XML

Sending voice messages via Text-To-Speech [TTS]

{{codeStart}}

# To call from a User-defined workspace

POST https://api.<region>.whispir.com/workspaces/:workspace_id/messages 

# To call from the default workspace

POST https://api.<region>.whispir.com/messages

 

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

 

{

"to" : "61400400400",

"subject" : "Test Voice Call",

"voice" : {

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

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

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

}

}

{{codeEnd}}

Request Body Details

to

(required)

  • Mobile phone: e.g. 61400400400
  • Landline phone: e.g. 61386000000

header

The introduction for the Voice call*. If specified, this is the first element that is going to be reproduced. If a "Pin" has been specified in the "type" field then the user will be asked to insert it after this part is over, otherwise dialling "1" as requested will be enough to hear the rest of the message

subject

(required)

A description of the Voice call. This is the first part to be reproduced after the user entered "1" in the previous step

body

(required)

The body of the Voice message*. The recipient will be able to replay the message dialling "1" or to acknowledge it dialling "2" 

type

(required)

The Type field is mandatory even when no conference call is being used. The minimum string to be used as a value for JSON and XML is specified in the examples above. More details about them will be given in the following section


* 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

WAV files requirements

Before a WAV file can be used for the Voice module, it needs to conform to certain criteria:

  • All the WAV files combined must not exceed 10 MB in total file size
  • All the WAV files must be a maximum of 8 bit, 8000 Hz, 1ch, 64 kbps
  • If a WAV file is outside these criteria please use TTS instead
  • JSON
  • XML

Sending Voice messages via WAV files

{{codeStart}}

# To call from a User-defined workspace

POST https://api.<region>.whispir.com/workspaces/:workspace_id/messages 

# To call from the default workspace

POST https://api.<region>.whispir.com/messages

 

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

{

"to" : "61400400400",

"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}}

Request Body Details

In addition to the parameters already specified for the TTS Voice calls for each attached WAV file there are the following ones to be set up

IMPORTANT: please notice that in the JSON case "attachment" is an array including all the files and thus requires square brackets, while in XML each attachment has its own "attachment" field

attachmentName

(required)

String

The name of the file being attached, including the file extension [e.g. "MessageBody.wav"]

attachmentDesc

(required)

String

In order to play a WAV file as introduction for the Voice call the value of this field MUST be equal to "voiceintro.wav" to play the file for the "header" field and to "voicebody.wav" to play the file for the "body" field in the "Voice" object [see example above]

derefUri

(required)

String

The Base64 encoded value for each attached WAV file

  • JSON
  • XML

Inviting to Teleconferences with Voice messages

{{codeStart}}

# To call from a User-defined workspace

POST https://api.<region>.whispir.com/workspaces/:workspace_id/messages 

# To call from the default workspace

POST https://api.<region>.whispir.com/messages

 

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

 

{

"to" : "61400400400",

"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" : "Pin:,ConfCall:1800500536,ConfAccountNo:12345678,ConfPinNo:1234,ConfModPinNo:1234"

}

}

{{codeEnd}}

 

Inviting to Teleconferences with Voice messages leaving an SMS to join later

{{codeStart}}

POST https://api.<region>.whispir.com/messages

 

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

 

{

"to" : "61400400400",

"subject" : "Test Voice Call",

"body" : "To join the Teleconference later - Dial-in number: @@teleconf_number@@, Access code: @@teleconf_pin@@, Moderator PIN: @@teleconf_mod_pin@@",

"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" : "Pin:,ConfCall:1800500536,ConfAccountNo:12345678,ConfPinNo:1234,ConfModPinNo:1234"

}

}

{{codeEnd}}

Request Body Details

In addition to the parameters already specified above, users can easily integrate with the existing teleconference services providing the following information in the "type" field. Please notice once again that - depending on the chosen teleconference service - some parameters values can be omitted but the parameters keys must all be included in the same field. The minimum string was already shown in the first example of this page

NOTE - Whispir’s Voice module doesn’t include a conference call service but users can easily integrate with the existing ones using the following parameters

Pin

The access code required to be inserted from the recipient to hear the Voice message after the "header" is over. It can be left blank and then the user will be asked to proceed dialling "1"

For example, 7171

If the right code is inserted then "subject" and "body" of the Voice Message will be reproduced. The user will be able to dial "1" to replay the message, "2" to join the conference call or "3" to receive the details to dial in later

In this last case the details - a Dial-In number and a PIN - will be repeated 3 times

ConfCall

The teleconference line that will be used in the voice call

For example, 1800123123

It is possible to reference this value in other channels using the @@teleconf_number@@ custom variable

ConfAccountNo

The teleconference account or room number that is used in the voice call

For example, 098711234

It is possible to reference this value in other channels using the @@teleconf_account@@ custom variable

ConfPinNo

The teleconference room PIN that is used in the voice call

For example, 8181

It is possible to reference this value in other channels using the @@teleconf_pin@@ custom variable

ConfModPinNo

The teleconference moderator PIN that is used in the voice call

For example, 4242

It is possible to reference this value in other channels using the @@teleconf_mod_pin@@ custom variable

Sample Response

202- Accepted

In this case the Location header in the Response Headers will show the direct link to the message. Depending on the endpoint of choice we will respectively have:

https://api.<region>.whispir.com/workspaces/:workspace_id/messages/:message_id

https://api.<region>.whispir.com/messages/:message_id

NOTE: if the Location Header containing the message_id wasn't collected at the time of sending please refer to Retrieve a previously sent message. This process is same for SMS, email, voice and push notifications