Voice Messaging API

MessageBird's Voice Messaging API enables you to transform text messages into voice messages to any country. Each voice message is identified by a unique random ID that can be used to check the status of the voice message. You can select from 26 languages and different attributes such as male or female voice, speaking rate, repeat, schedule, and more.

The Voice Messaging API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization framework. Request and response payloads are formatted as JSON—although we provide a GET alternative for requests—using UTF-8 encoding and URL encoded values.

URI

https://rest.messagebird.com/voicemessages

Available HTTPS Methods

POST /voicemessages
GET /voicemessages
GET /voicemessages/{voiceMessageId}
DELETE /voicemessages/{voiceMessageId}

The voice message object

This object represents a voice message at MessageBird.com

Attributes

AttributeTypeDescription
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
hrefstringThe URL of the created object.
referencestringA client reference
originatorstringThe sender of the message. A telephone number (including country code).
bodystringThe body of the SMS message. The maxlength is 1000 characters. Check the voice body for more options
languagestringThe language in which the message needs to be read to the recipient. Possible values are: cy-gb,da-dk,de-de,el-gr,en-au,en-gb,en-gb-wls,en-in,en-us,es-es,es-mx,es-us,fr-ca,fr-fr,id-id,is-is,it-it,ja-jp,ko-kr,ms-my,nb-no,nl-nl,pl-pl,pt-br,pt-pt,ro-ro,ru-ru,sv-se,ta-in,th-th,tr-tr,vi-vn,zh-cn,zh-hk.
voicestringThe voice in which the messages needs to be read to the recipient. Possible values are: male, female.
repeatintThe number of times the message needs to be repeated. Maximum is 10 times.
ifMachinestringWhat to do when a machine picks up the phone? Possible values are:
- continue do not check, just play the message
- delay if a machine answers, wait until the machine stops talking
- hangup hangup when a machine answers
Default is: delay.
machineTimeoutintegerThe time (in milliseconds) to analyze if a machine has picked up the phone. Used in combination with the delay and hangup values of the ifMachine attribute. Minimum: 400, maximum: 10000. Default is: 7000.
scheduledDatetimedatetimeThe scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP)
createdDatetimedatetimeThe date and time of the creation of the message in RFC3339 format (Y-m-d\TH:i:sP)
recipientshashThe hash with recipient information. Further explanation in the table below.

Object example

{
"id":"e8077d803532c0b5937c639b60216938",
"href":"https://rest.messagebird.com/voicemessages/e8077d803532c0b5937c639b60216938",
"originator":null,
"body":"The voice message to be sent",
"reference":"the-client-reference",
"language":"en-gb",
"voice":"female",
"repeat":1,
"ifMachine":"continue",
"machineTimeout":7000,
"scheduledDatetime":null,
"createdDatetime":"2016-05-03T14:26:57+00:00",
"recipients":{
"totalCount":1,
"totalSentCount":1,
"totalDeliveredCount":0,
"totalDeliveryFailedCount":0,
"items":[
{
"recipient":31612345678,
"status":"answered",
"statusDatetime":"2016-05-03T14:26:57+00:00"
}
]
}
}

The recipients array

AttributeTypeDescription
totalCountintegerThe total count of recipients.
totalSentCountintegerThe count of recipients that have the message pending (status calling).
totalDeliveredCountintegerThe count of recipients where the message is delivered (status answered).
totalDeliveryFailedCountintegerThe count of recipients where the delivery has failed (status failed, busy, machine).
itemsarrayAn array of recipient hashes
items[].recipientintegerThe msisdn of the recipient
items[].statusstringThe status of the message sent to the recipient. Possible values: calling, answered, failed. For future use the following status are reserved: busy and machine
items[].statusDatetimedatetimeThe datum time of the last status in RFC3339 format (Y-m-d\TH:i:sP)

The voice body

By tweaking the body you can alter the speed and delays in the spoken text.

You can add a small delay between words or digits by adding a comma (,). Another possibility is adding the "break" tag with an attribute "value" in seconds (s) or milliseconds (ms).

It is also possible to change the speaking rate, you can use the "prosody" tag with an attribute "value" in percentage.

Delay with a comma

Hello, your login token is 1, 8, 3, 4, 0

Delay with a break tag

Hello, your login token is<break time="1s"/>1<break time="500ms"/>8<break time="500ms"/>3<break time="500ms"/>4<break time="500ms"/>0

Speaking rate

Your login token is <prosody rate="-10%">1, 8, 3, 4, 0</prosody>

Send a voice message

This request creates a new voice message object. MessageBird returns the created voice message object with each request. Per request, a max of 50 recipients can be entered.

Example request

curl -X POST https://rest.messagebird.com/voicemessages \ -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \ -d "recipients=31612345678" \ -d "body=The voice message to be sent"

Required parameters

ParameterTypeDescription
bodystringThe body of the SMS message. Required
recipientsarrayThe array of recipients msisdns. Required

Optional parameters

ParameterTypeDescription
originatorstringThe sender of the message. A telephone number (including country code).
referencestringA client reference
languagestringThe language in which the message needs to be read to the recipient. Possible values are: cy-gb,da-dk,de-de,el-gr,en-au,en-gb,en-gb-wls,en-in,en-us,es-es,es-mx,es-us,fr-ca,fr-fr,id-id,is-is,it-it,ja-jp,ko-kr,ms-my,nb-no,nl-nl,pl-pl,pt-br,pt-pt,ro-ro,ru-ru,sv-se,ta-in,th-th,tr-tr,vi-vn,zh-cn,zh-hk. Default: en-gb
voicestringThe voice in which the messages needs to be read to the recipient. Possible values are: male, female. Default: female
repeatintThe number of times the message needs to be repeated. Default: 1
ifMachinestringWhat to do when a machine picks up the phone? Possible values are:
- continue do not check, just play the message
- delay if a machine answers, wait until the machine stops talking
- hangup hangup when a machine answers
Default is: delay.
machineTimeoutintegerThe time (in milliseconds) to analyze if a machine has picked up the phone. Used in combination with the delay and hangup values of the ifMachine attribute. Minimum: 400, maximum: 10000. Default: 7000
scheduledDatetimedatetimeThe scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP)

Returns

Returns a message object if the request was successful. If the request failed, an error object will be returned.

Example response

{
"id":"e8077d803532c0b5937c639b60216938",
"href":"https://rest.messagebird.com/voicemessages/e8077d803532c0b5937c639b60216938",
"originator":null,
"body":"The voice message to be sent",
"reference":"the-client-reference",
"language":"en-gb",
"voice":"female",
"repeat":1,
"ifMachine":"continue",
"machineTimeout":7000,
"scheduledDatetime":null,
"createdDatetime":"2016-05-03T14:26:57+00:00",
"recipients":{
"totalCount":1,
"totalSentCount":1,
"totalDeliveredCount":0,
"totalDeliveryFailedCount":0,
"items":[
{
"recipient":31612345678,
"status":"calling",
"statusDatetime":"2016-05-03T14:26:57+00:00"
}
]
}
}

View a voice message

This request retrieves the information of an existing voice message. You only need to supply the unique voice message id that was returned upon creation.

Required parameters

ParameterTypeDescription
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required

Definition

GET https://rest.messagebird.com/voicemessages/{voiceMessageId}

Example request

curl -X GET https://rest.messagebird.com/voicemessages/e8077d803532c0b5937c639b60216938 \ -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Returns

If successful, this request will return a voice message object. If the request failed, an error object will be returned.

Example response

{
"id":"e8077d803532c0b5937c639b60216938",
"href":"https://rest.messagebird.com/voicemessages/e8077d803532c0b5937c639b60216938",
"originator":null,
"body":"The voice message to be sent",
"reference":"the-client-reference",
"language":"en-gb",
"voice":"female",
"repeat":1,
"ifMachine":"continue",
"machineTimeout":7000,
"scheduledDatetime":null,
"createdDatetime":"2016-05-03T14:26:57+00:00",
"recipients":{
"totalCount":1,
"totalSentCount":1,
"totalDeliveredCount":0,
"totalDeliveryFailedCount":0,
"items":[
{
"recipient":31612345678,
"status":"calling",
"statusDatetime":"2016-05-03T14:26:57+00:00"
}
]
}
}

Handle a status report

Status reports are requests that are sent to your platform through a GET request. The requests hold information about the status of a voice message that you have sent through our API. Status reports are only provided for voice messages that have a reference and accounts that have configured their status report url.

Attributes

AttributeTypeDescription
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
referencestringA client reference
recipientstringThe recipient where this status report applies to.
statusstringThe status of the message sent to the recipient. Possible values: calling, answered, failed. For future use the following status are reserved: busy and machine
statusDatetimedatetimeThe datum time of this status in RFC3339 format (Y-m-d\TH:i:sP)

Example request

GET http://your-own.url/script?id=e8077d803532c0b5937c639b60216938&reference=YouReference123&recipient=31612345678&status=delivered&statusDatetime=2016-04-13T07:27:49+00:00

Response

Your platform should respond with a 200 OK HTTP header. When our platform doesn't receive a 200 OK header, we will try to deliver the receipt again (up to 10 times).

Example response

200 OK
cURL
PHP
Node
C#
Java
Ruby
Go
Python
Cookie Settings