API Reference

OverviewSMSSMS batch APIVoice CallingVoice MessagingConversations APIContacts API (v2)Integrations APIFile Storage APIOmnichannel WidgetNumbersPartner AccountsVerifyMMSHLRBalanceLookupContactsGroupsIntentFAQNamed Entity RecognitionLanguage Detection

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.


API Endpoint

All URLs referenced in MessageBird's Voice Messaging API documentation have the base URL in the code snippet on the right side:

API Endpoint

https://rest.messagebird.com/voicemessages

Available HTTP methods

The MessageBird API uses HTTP verbs to understand if you want to read (GET), delete (DELETE) or create (POST) an object. When your web application cannot do a POST or DELETE, we provide the ability to set the method through the query parameter _method.

Available HTTP 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)
items[].recipientCountrystringThe name of the recipient’s original country, based on MSISDN.
items[].recipientCountryPrefixintegerThe prefix code for the recipient’s original country, based on MSISDN.
items[].recipientOperatorstringThe name of the operator of the recipient. Identified by MCCMNC of the message.
items[].messageLengthintegerThe length of the message in characters. Depends on the message datacoding.
items[].statusReasonstringThe details about the message status. Possible values: successfully delivered, pending DLR, DLR not received, incorrect number, unknown subscriber, expired, timeout, and generic delivery failure.
items[].pricehashmapA hashmap with extra information about how much the message costs.
Note: see this article for more details about our pricing policy.
items[].price.amountfloat | nullThe price the message was billed with. It could have a null value if the message isn’t billed yet.
items[].price.currencystring | nullThe alphabetic code of the price currency, in ISO 4217 format. It could have null value if the message isn’t billed yet.
items[].mccmncstring | nullThe code of the operator of the message sender. It could have null value if the message isn’t delivered yet.
items[].mccstring | nullThe MCC (Mobile Country Code) part of MCCMNC.
items[].mncstring | nullThe MNC (Mobile Network Code) part of MCCMNC.

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":"answered",
"statusDatetime":"2016-05-03T14:26:57+00:00",
"recipientCountry":"Netherlands",
"recipientCountryPrefix":31,
"recipientOperator":"",
"messageLength":28,
"statusReason":"successfully delivered",
"price":{
"amount":0.055,
"currency":"EUR"
},
"mccmnc":"20408",
"mcc":"204",
"mnc":"08"
}
]
}
}

List voice messages

To list all inbound and outbound voice messages, you can do a GET request on the /messages endpoint.

Messages are identified by a unique random ID. You can use this ID to check the status of the SMS message through the provided endpoint.

API Endpoint

curl -X GET https://rest.messagebird.com/voicemessages/?offset=100&limit=30 \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Filters

Besides listing all voice messages, the MessageBird Voice API also provides some filters that can be used as query parameters:

FilterTypeDescription
originatorstringDisplay messages by the specified originator.
recipientstringDisplay messages for the specified recipient.
limitintLimit the amount of messages listed.
offsetintSkip first n results.
contact_idintDisplay messages by contact_id. See
Contacts API
for more info.
statusstringDisplay messages with status scheduled, sent, buffered, delivered, expired, or delivery_failed.
fromdatetimeDisplay messages starting from the specified date in RFC3339 format (Y-m-d\TH:i:sP).
untildatetimeDisplay messages until the specified date in RFC3339 format (Y-m-d\TH:i:sP).

Returns

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

Example response

{
"offset": 0,
"limit": 30,
"count": 2,
"totalCount": 2,
"links": {
"first": "https://rest.messagebird.com/voicemessages/?offset=0&limit=30&contact_id=65",
"previous": null,
"next": null,
"last": "https://rest.messagebird.com/voicemessages/?offset=0&limit=30&contact_id=65"
},
"items": [
{
"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

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings