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.
The voice message object
This object represents a voice message at MessageBird.com
Attributes
| Attribute | Type | Description |
|---|---|---|
| id | string | A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. |
| href | string | The URL of the created object. |
| reference | string | A client reference |
| originator | string | The sender of the message. A telephone number (including country code). |
| body | string | The body of the SMS message. The maxlength is 1000 characters. Check the voice body for more options |
| language | string | The 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. |
| voice | string | The voice in which the messages needs to be read to the recipient. Possible values are: male, female. |
| repeat | int | The number of times the message needs to be repeated. Maximum is 10 times. |
| ifMachine | string | What 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. |
| machineTimeout | integer | The 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. |
| scheduledDatetime | datetime | The scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP) |
| createdDatetime | datetime | The date and time of the creation of the message in RFC3339 format (Y-m-d\TH:i:sP) |
| recipients | hash | The 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
| Attribute | Type | Description |
|---|---|---|
| totalCount | integer | The total count of recipients. |
| totalSentCount | integer | The count of recipients that have the message pending (status calling). |
| totalDeliveredCount | integer | The count of recipients where the message is delivered (status answered). |
| totalDeliveryFailedCount | integer | The count of recipients where the delivery has failed (status failed, busy, machine). |
| items | array | An array of recipient hashes |
| items[].recipient | integer | The msisdn of the recipient |
| items[].status | string | The 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[].statusDatetime | datetime | The datum time of the last status in RFC3339 format (Y-m-d\TH:i:sP) |
| items[].recipientCountry | string | The name of the recipient’s original country, based on MSISDN. |
| items[].recipientCountryPrefix | integer | The prefix code for the recipient’s original country, based on MSISDN. |
| items[].recipientOperator | string | The name of the operator of the recipient. Identified by MCCMNC of the message. |
| items[].messageLength | integer | The length of the message in characters. Depends on the message datacoding. |
| items[].statusReason | string | The 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[].price | hashmap | A hashmap with extra information about how much the message costs. Note: see this article for more details about our pricing policy. |
| items[].price.amount | float | null | The price the message was billed with. It could have a null value if the message isn’t billed yet. |
| items[].price.currency | string | null | The alphabetic code of the price currency, in ISO 4217 format. It could have null value if the message isn’t billed yet. |
| items[].mccmnc | string | null | The code of the operator of the message sender. It could have null value if the message isn’t delivered yet. |
| items[].mcc | string | null | The MCC (Mobile Country Code) part of MCCMNC. |
| items[].mnc | string | null | The 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.
Required parameters
| Parameter | Type | Description |
|---|---|---|
| body | string | The body of the SMS message. Required |
| recipients | array | The array of recipients msisdns. Required |
Optional parameters
| Parameter | Type | Description |
|---|---|---|
| originator | string | The sender of the message. A telephone number (including country code). |
| reference | string | A client reference |
| language | string | The 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 |
| voice | string | The voice in which the messages needs to be read to the recipient. Possible values are: male, female. Default: female |
| repeat | int | The number of times the message needs to be repeated. Default: 1 |
| ifMachine | string | What 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. |
| machineTimeout | integer | The 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 |
| scheduledDatetime | datetime | The 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
| Parameter | Type | Description |
|---|---|---|
| id | string | A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required |
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"}]}}
Filters
Besides listing all voice messages, the MessageBird Voice API also provides some filters that can be used as query parameters:
| Filter | Type | Description |
|---|---|---|
| originator | string | Display messages by the specified originator. |
| recipient | string | Display messages for the specified recipient. |
| limit | int | Limit the amount of messages listed. |
| offset | int | Skip first n results. |
| contact_id | int | Display messages by contact_id. See Contacts API for more info. |
| status | string | Display messages with status scheduled, sent, buffered, delivered, expired, or delivery_failed. |
| from | datetime | Display messages starting from the specified date in RFC3339 format (Y-m-d\TH:i:sP). |
| until | datetime | Display 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
| Attribute | Type | Description |
|---|---|---|
| id | string | A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. |
| reference | string | A client reference |
| recipient | string | The recipient where this status report applies to. |
| status | string | The status of the message sent to the recipient. Possible values: calling, answered, failed. For future use the following status are reserved: busy and machine |
| statusDatetime | datetime | The datum time of this status in RFC3339 format (Y-m-d\TH:i:sP) |
Is this page useful?
Next upConversations