API Reference

OverviewSMSVoice CallingVoice MessagingConversations APIIntegrations APIOmnichannel WidgetNumbersPartner AccountsVerifyMMSHLRBalanceLookupContactsGroups

Conversations API

The MessageBird Conversations API is an omnichannel messaging solution to unify sending and receiving messages across all platforms in one conversation thread. A conversation is the view of all messages between you and a customer across any of your configured channels.

  • Messages from multiple channels and same contact are displayed in a single conversation
  • When the first message is sent to or received from a contact, a conversation is automatically created
  • A conversation status can be active or archived, but only one active conversation exists for each contact at any given time
  • Archiving can be used to end a conversation so that the next time the customer reaches out, a new conversation is started. This is especially helpful for support use cases where conversations need to be opened and closed, rather than merely resumed.

The Conversations API uses HTTP verbs and RESTful endpoints structure with an access key that is used as the API Authorization. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values.

Base URL

All paths referenced in this page uses the following base URL:

https://conversations.messagebird.com/v1/

Authorization

You need to set an access key to authenticate your HTTP requests. You can create, manage, and retrieve your access keys using the MessageBird Dashboard.

To provide the access key, set the Authorization HTTP header in the form of AccessKey {accessKey}.

Formats and Headers

All HTTP responses are in JSON. It's advised to send the Accept HTTP header with the value application/json with each request. Both POST and PUT requests to the API must contain a JSON-formatted payload in the request body.

Rate limits

Conversations API will reject HTTP requests with status code 429 Too Many Requests in case the number of requests per second (RPS) is higher than the following limits. The burst is the maximum RPS in a short period of time, and the limit is the maximum RPS a long term. In short, read requests are limited to 500 RPS, and write/update requests are limited to 50 RPS with bursts of 250 RPS.

Notification icon

Please contact support in case you need higher limits.

HTTP methodRegular customersEnterprise customers
LimitBurstLimitBurst
GET500500500500
POST50250250500
PATCH50250250500
DELETE50250250500

Errors

MessageBird uses standard HTTP status codes to indicate success or failure of API requests.

  • HTTP response codes in the 2xx range indicate the request was successfully processed
  • HTTP response codes in the 4xx range indicate that there was a client error - for example: authentication error, not enough balance or wrong/missing parameters. Don't worry, the HTTP response body includes a JSON-formatted response that tells you exactly what went wrong. If you're stuck, feel free to contact support, we're happy to help you out
  • HTTP response codes in the 5xx range indicate a server error. It's considered safe to retry the same request, preferably with a delay

Error object

{
"errors": [
{
"code": 1001,
"description": "You are requesting with an invalid credential.",
"parameter": null
}
]
}

Attributes

ParameterTypeDescription
errors[].codeintegerAn integer that represents the error type.
errors[].descriptionstringA human-readable description of the error. You can use this to let the user know what they can do about the error.
errors[].parameterstringThe parameter in your request related to the error if the error is parameter specific.

Sending Messages

The Conversations API provides three ways of sending messages: start conversation, send a message to a specific conversation and send message. Regardless the way you the messages, they are all processed asynchronously, which means, Conversations API will accept your message and process it later, and, because of that, it's important to have webhooks for receiving the status updates about the messages you send.

  • Start conversation
    • Intended to be used to start new conversations
    • If there's an existing active conversation with the contact, the message will add the message to the active conversation
    • If there are no conversation with the contact or all conversations are archived, it will create a new active conversation
    • The HTTP response provides the conversation ID and the contact details
  • Reply to conversation
    • Intended to be used to send a message to a specific conversation
    • If the conversation is archived, the endpoint will respond 400 Bad Request
    • If the conversation doesn't exist, the endpoint will respond 404 Not Found
    • The HTTP response provides the message details, including the message ID and status
  • Send message
    • Intended to send a high number of messages
    • It quickly accepts the HTTP request and does the same work as the previous endpoint asynchronously
    • The HTTP response provides only the message ID and status

Start Conversation

Starts a conversation with a specific contact. In case there's already an active conversation with the contact, the message will be added to the existing active conversation. In case there's no active conversation with the contact, a new conversation will be created.

POST /conversations/start

Request

ParameterTypeDescriptionRequired
typeMessageTypeThe type of the message content. Defines which field is required inside content.Yes
contentMessageContentContent of the message to send. The value of type defines the required fields.Yes
toMessageRecipientA platform-specific identifier of the recipient.Yes
channelIdstringThe unique ID that identifies the channel through which the message should be sent.Yes
sourceobjectA JSON-formatted object that can be used to identify the source of the message.No
reportUrlstringThe URL to deliver status updates for the message. Must use HTTPS.No
tagMessageTagMark the message with a particular MessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.No
trackIdstringUseful for grouping messages across conversations. The limit is 36 characters.No
eventTypestringThe type of event being sent. The value of the parameter type must be a eventNo
curl -X POST "https://conversations.messagebird.com/v1/conversations/start" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json" \
-d '{
"to": "+31612345678",
"channelId": "619747f69cf940a98fb443140ce9aed2",
"type": "text",
"content": {
"text": "Hello!"
},
"source": {
"foo": "bar"
}
}'

Response

The HTTP response contains a Conversation object.

{
"id": "2e15efafec384e1c82e9842075e87beb",
"contactId": "a621095fa44947a28b441cfdf85cb802",
"contact": {
"id": "a621095fa44947a28b441cfdf85cb802",
"href": "https://rest.messagebird.com/1/contacts/a621095fa44947a28b441cfdf85cb802",
"msisdn": 316123456789,
"firstName": "Jen",
"lastName": "Smith",
"customDetails": {
"custom1": null,
"custom2": null,
"custom3": null,
"custom4": null
},
"createdDatetime": "2018-06-03T20:06:03Z",
"updatedDatetime": null
},
"channels": [
{
"id": "853eeb5348e541a595da93b48c61a1ae",
"name": "SMS",
"platformId": "sms",
"status": "active",
"createdDatetime": "2018-08-28T11:56:57Z",
"updatedDatetime": "2018-08-29T08:16:33Z"
},
{
"id": "619747f69cf940a98fb443140ce9aed2",
"name": "My WhatsApp",
"platformId": "whatsapp",
"status": "active",
"createdDatetime": "2018-08-28T11:56:57Z",
"updatedDatetime": "2018-08-29T08:16:33Z"
},
],
"status": "active",
"createdDatetime": "2018-08-13T09:17:22Z",
"updatedDatetime": "2018-08-29T07:35:48Z",
"lastReceivedDatetime": "2018-08-29T07:35:48Z",
"lastUsedChannelId": "619747f69cf940a98fb443140ce9aed2",
"lastUsedPlatformId": "whatsapp",
"messages": {
"totalCount": 24,
"href": "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages",
"lastMessageId": "9d5d5921f5b34f8db415a2397eb762f9",
}
}
Response codes
CodeDescription
201Message accepted and it will be processed asynchronously.
400Invalid HTTP request. The HTTP response should include details about the error.
401Unauthorized.
422The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

Reply Conversation

Send a new message to an existing conversation. In case the conversation is archived, a new conversation is created.

POST /v1/conversations/{conversation_id}/messages

Request

ParameterTypeDescriptionRequired
typeMessageTypeThe type of the message content. Defines which field is required inside content.Yes
contentMessageContentContent of the message to send. The value of type defines the required fields.Yes
channelIdstringThe unique ID that identifies the channel over which the message should be sent. If not provided, the most-recently used active channel for the conversation is used.No
fallbackFallbackRequired to send a fallback message.No
sourceobjectA JSON-formatted object that can be used to identify the source of the message.No
eventTypestringThe type of event being sent. The value of the parameter type must be a eventNo
reportUrlstringThe URL for delivering status updates for the message. Must be HTTPS.No
tagMessageTagMark the message with a particular MessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.No
trackIdstringUseful for grouping messages across conversations. The limit is 36 characters.No
curl -X POST "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json" \
-d '{
"type": "text",
"content": {
"text": "Hello!"},
"source": {"foo":"var"}
}'

Response

ParameterTypeDescription
idstringThe unique ID generated by MessageBird that identifies the message.
conversationIdstringThe unique ID that identifies the conversation which the message is a part of.
channelIdstringThe unique ID that identifies the channel which the message was sent.
platformPlatformThe platform name of the channel which the message was sent.
toMessageRecipientThe identifier of the recipient in the platform. The value depends on the platform.
fromstringThe identifier of the sender in the platform. The value depends on the platform.
directionMessageDirectionThe direction of the message.
statusMessageStatusThe status of the message.
typeMessageTypeThe type of message content.
contentMessageContentContent of the message. The type field indicates the field which is populated in this object.
createdDatetimeDatetimeThe datetime when the message was created in RFC3339 format.
updatedDatetimeDatetimeThe datetime when the message was updated in RFC3339 format.
sourceobjectA JSON-formatted object that can be used to identify the source of the message.
tagMessageTagMark the message with a particular MessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.
fallbackFallbackThe fallback message, if provided.
{
"id": "13a97a5023944648b8e5e61248c40da8",
"conversationId": "2e15efafec384e1c82e9842075e87beb",
"channelId": "a621095fa44947a28b441cfdf85cb802",
"status": "pending",
"to":"+31612345678",
"from":"+31687654321",
"type": "text",
"direction": "sent",
"content": {
"text": "This is a test message"
},
"createdDatetime": "2018-08-29T13:53:44.642664784Z",
"updatedDatetime": "2018-08-29T13:53:44.673850825Z",
"source": {
"foo": "bar"
}
}
Response codes
CodeDescription
201Message accepted and it will be processed asynchronously.
400Invalid HTTP request. The HTTP response should include details about the error.
404Conversation not found.
401Unauthorized.
422The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

Send Message

Send a message to a specific recipient in a specific platform. If an active conversation already exists for the recipient, the conversation will be resumed. In case there's no active conversation a new one is created.

POST /v1/send

Request

ParameterTypeDescriptionRequired
tostringEither a MessageRecipient or the MessageBird contact ID.Yes
fromstringThe channel ID from which the message should be sent.Yes
typeMessageTypeThe type of the message content. Defines which field is required inside content.Yes
contentMessageContentContent of the message to send. The value of type defines the required fields.Yes
reportUrlstringThe URL for delivering status updates for the message. Must be HTTPS.No
fallbackFallbackRequired to send a fallback message.No
sourceobjectA JSON-formatted object that can be used to identify the source of the message.
tagMessageTagMark the message with a particular MessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.No
trackIdstringUseful for grouping messages across conversations. The limit is 36 characters.No
curl -X POST "https://conversations.messagebird.com/v1/send" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json" \
-d '{
"to": "+31612345678",
"from": "619747f69cf940a98fb443140ce9aed2",
"type": "text",
"content": {
"text": "Hello!"
},
"reportUrl": "https://example.com/reports",
"source": {
"foo": "bar"
}
}'

Response

ParameterTypeDescription
idstringAn unique ID generated by MessageBird that identifies the message.
statusMessageStatusThe status of the message.
fallbackFallbackThe fallback message, if provided.
{
"id": "2e15efafec384e1c82e9842075e87beb",
"status": "accepted"
}
Response codes
CodeDescription
202Message accepted and it will be processed asynchronously.
400Invalid HTTP request. The HTTP response should include details about the error.
401Unauthorized.
422The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

Fallback Messages

A fallback message is a message to be sent over a secondary channel if the original message failed or could not be sent within a defined time window.

For example, when sending a WhatsApp message to a customer, you can configure a fallback message so that if the customer is not a WhatsApp user or doesn't have a mobile data connection, the message is then sent over SMS. You can define the time at which the fallback message should be sent if it wasn't successful over the primary channel; if you don't set a time, the fallback will automatically trigger after 1 minute.

Currently, our Conversations API only supports fallbacks between SMS and WhatsApp. You can set a fallback for a WhatsApp session message with SMS as the secondary channel, or the other way around. Please note that the fallback configuration using WhatsApp media templates and location are not supported yet.

Notification icon

It's important to understand that, when sending a fallback message to a secondary channel, the contact must have an identifier in the secondary platform, otherwise it won't be possible to send the message.

Here is an example of sending a text message using a primary channel, and falling back to a secondary channel after 5 minutes.

curl -X POST "https://conversations.messagebird.com/v1/send" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json" \
-d '{
"to":"+31612345678",
"from":"619747f69cf940a98fb443140ce9aed2",
"type":"text",
"content":{
"text":"Hello!"
},
"reportUrl":"https://example.com/reports"
"fallback": {
"from": "2ecea8ee6c564bb4ab15929c44527687"
"after": "5m"
}
}'

Here is the response for the request above.

{
"id": "2e15efafec384e1c82e9842075e87beb",
"status": "accepted"
"fallback": {
"id": "a5a66361dc0b4e5d8d2da249753fa8b5",
}
}

Fallback Status Updates

In case the reportUrl is provided in the request, and the fallback message was triggered, you'll also receive the status update message.fallbackTriggered in your report URL. The status update will include the original and fallback message IDs.

{
"type": "message.fallbackTriggered",
"message": {
"id": "5d76d378e5eb4af2b9e98ac659781dfd",
},
"fallback": {
"id": "2fcb9be1131f4f409fae0ead9ed54e81",
}
}

Receiving Messages and Status Updates

In order to receive messages, you must set up webhooks in Conversations API. For receiving status updates of sent messages, there are two ways of doing that: by using webhooks or per message. More details about these two approaches are in the following sections.

Webhooks

Webhooks allow your application to receive conversation events, inbound messages and status updates of outbound messages. A webhook can be configured with a URL and a list of events that should be subscribed for notifications. It's possible to create multiple webhooks with different URLs to listen to one or more events.

There are two types of webhooks: channel-specific, which subscribes to events of a particular channel; and generic webhooks, which subscribes to events of all your channels.

Notification icon

The current webhook limits are 10 channel-specific webhooks and 5 generic webhooks.

Create Webhook

Creates a webhook.

POST /v1/webhooks
Request
ParameterTypeDescriptionRequired
eventsArray of WebhookEventsA list of event names that should trigger this webhook.Yes
channelIdstringThe unique identifier for a MessageBird channel that this webhook is subscribed.No
urlstringThe endpoint URL that requests should be sent to.Yes
settingsWebhookSettingsThe webhook extra settings.No
curl -X POST "https://conversations.messagebird.com/v1/webhooks/" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json" \
-d '{
"events": ["message.created", "message.updated"],
"channelId": "853eeb5348e541a595da93b48c61a1ae",
"url": "https://example.com/webhook",
"settings": {
"expected_http_code" : "2xx",
"headers": {
"from" : "messagebird"
},
"query_params" : "transactionID=1312435365",
"username" : "user20121",
"password" : "mypass1213",
"retry": 2,
"timeout": 14
}
}'
Response

The HTTP response contains a Webhook object.

{
"id": "985ae50937a94c64b392531ea87a0263",
"url": "https://example.com/webhook",
"channelId": "853eeb5348e541a595da93b48c61a1ae",
"events": [
"message.created",
"message.updated",
],
"status": "enabled",
"createdDatetime": "2018-08-29T10:04:23Z",
"updatedDatetime": null,
"settings": {
"expected_http_code" : "2xx",
"headers": {
"from" : "messagebird"
},
"query_params" : "transactionID=1312435365",
"username" : "user20121",
"password" : "mypass1213",
"retry": 2,
"timeout": 14
}
}
Response codes
CodeDescription
201Webhook created.
400Invalid HTTP request. The HTTP response should include details about the error.
401Unauthorized.
422The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

List Webhooks

Retrieves a list of webhooks.

GET /v1/webhooks
Request
curl -X GET "https://conversations.messagebird.com/v1/webhooks/" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Response
ParameterTypeDescription
countintegerNumber of webhooks.
itemsarray of WebhookArray of webhook objects.
limitintegerThe number of maximum objects returned on each request.
offsetintegerThe number of objects skipped.
totalCountintegerThe number of total webhook objects that can be retrieved through pagination.
{
"offset": 0,
"limit": 100,
"count": 10,
"totalCount": 10,
"items": [
{
"id": "985ae50937a94c64b392531ea87a0263",
"url": "https://example.com/webhook",
"channelId": "853eeb5348e541a595da93b48c61a1ae",
"events": [
"message.created",
"message.updated",
],
"status": "enabled",
"createdDatetime": "2018-08-29T10:04:23Z",
"updatedDatetime": null,
"settings": {
}
},
// ... remaining webhooks omitted
]
}
Response codes
CodeDescription
200Ok.
400Invalid HTTP request. The HTTP response should include details about the error.
401Unauthorized.
422The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

Get Webhook

Retrieves a specific webhook.

GET /v1/webhooks/{id}
Request
curl -X GET "https://conversations.messagebird.com/v1/webhooks/985ae50937a94c64b392531ea87a0263" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Response

The HTTP response contains a Webhook object.

{
"id": "985ae50937a94c64b392531ea87a0263",
"url": "https://example.com/webhook",
"channelId": "853eeb5348e541a595da93b48c61a1ae",
"events": [
"message.created",
"message.updated",
],
"status": "enabled",
"createdDatetime": "2018-08-29T10:04:23Z",
"updatedDatetime": null,
"settings": {
"expected_http_code" : "2xx",
"headers": {
"from" : "messagebird"
},
"query_params" : "transactionID=1312435365",
"username" : "user20121",
"password" : "mypass1213",
"retry": 2,
"timeout": 14
}
}
Response codes
CodeDescription
200Ok.
404Webhook not found.
401Unauthorized.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

Update Webhook

Updates a webhook with the parameters provided. Only parameters that will change need to be provided in the request.

PATCH /v1/webhooks/{id}
Request
ParameterTypeDescription
eventsArray of WebhookEventsA list of event names that should trigger this webhook.
urlstringThe endpoint URL that requests should be sent to.
statusWebhookStatusThe webhook status.
settingsWebhookSettingsThe webhook extra settings.
curl -X PATCH "https://conversations.messagebird.com/v1/webhooks/985ae50937a94c64b392531ea87a0263" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json" \
-d '{
"status": "disabled",
"settings": {
"retry": 6,
"timeout": 26
}
}'
Response

The HTTP response contains a Webhook object.

{
"id": "985ae50937a94c64b392531ea87a0263",
"url": "https://example.com/webhook",
"channelId": "853eeb5348e541a595da93b48c61a1ae",
"events": [
"message.created",
"message.updated",
],
"status": "disabled",
"createdDatetime": "2018-08-29T10:04:23Z",
"updatedDatetime": "2018-08-29T10:10:23Z",
"settings": {
"expected_http_code" : "2xx",
"headers": {
"from" : "messagebird"
},
"query_params" : "transactionID=1312435365",
"username" : "user20121",
"password" : "mypass1213",
"retry": 6,
"timeout": 26
}
}
Response codes
CodeDescription
200Ok.
404Webhook not found.
401Unauthorized.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

Delete Webhook

Disables and removes an existing webhook.

DELETE https://conversations.messagebird.com/v1/webhooks/{id}
Request
curl -X DELETE "https://conversations.messagebird.com/v1/webhooks/985ae50937a94c64b392531ea87a0263" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Response
204 No Content
Response codes
CodeDescription
204Webhook deleted.
404Webhook not found.
401Unauthorized.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

Handling Webhook Requests

HTTP requests will be delivered to your application whenever one of the events you have subscribed is triggered. Each event has a specific payload which is delivered as a POST request.

A HTTP request is considered successfully accepted when your application responds with any successful response (2xx). Any other HTTP response code will be treated as not accepted. Not-accepted HTTP requests will be retried up to 10 times over the next 24-hours period.

If your application fails to accept the request 200 times, or for more than 12 hours, your webhook will be automatically disabled and must be re-enabled via the Update method. Any successful response from your application will reset the counter.

Conversation Created Event

{
"type": "conversation.created",
"contact": {
"id": "9354647c5b144a2b4c99f2n42497249",
"href": "https://rest.messagebird.com/1/contacts/9354647c5b144a2b4c99f2n42497249",
"msisdn": 316123456789,
"firstName": "Jen",
"lastName": "Smith",
"customDetails": {
"custom1": null,
"custom2": null,
"custom3": null,
"custom4": null
},
"createdDatetime": "2018-06-03T20:06:03Z",
"updatedDatetime": null
},
"conversation": {
"id": "2f719ebc5b144a18b75f44n12188288",
"contactId": "9354647c5b144a2b4c99f2n42497249",
"status": "active",
"createdDatetime": "2018-03-28T13:28:00Z",
"updatedDatetime": null,
"lastReceivedDatetime": null
}
}

Conversation Updated Event

{
"type": "conversation.updated",
"contact": {
"id": "9354647c5b144a2b4c99f2n42497249",
"href": "https://rest.messagebird.com/1/contacts/9354647c5b144a2b4c99f2n42497249",
"msisdn": 316123456789,
"firstName": "Jen",
"lastName": "Smith",
"customDetails": {
"custom1": null,
"custom2": null,
"custom3": null,
"custom4": null
},
"createdDatetime": "2018-06-03T20:06:03Z",
"updatedDatetime": null
},
"conversation": {
"id": "2f719ebc5b144a18b75f44n12188288",
"contactId": "9354647c5b144a2b4c99f2n42497249",
"status": "archived",
"createdDatetime": "2018-03-28T13:28:00Z",
"updatedDatetime": "2018-03-28T13:28:00Z",
"lastReceivedDatetime": "2018-03-28T13:28:00Z",
"lastUsedChannelId": "95e223e381364b00b1b21e52bbc6285e",
"lastUsedPlatformId": "sms"
}
}

Message Created Event

{
"type": "message.created",
"contact": {
"id": "9354647c5b144a2b4c99f2n42497249",
"href": "https://rest.messagebird.com/1/contacts/9354647c5b144a2b4c99f2n42497249",
"msisdn": 316123456789,
"firstName": "Jen",
"lastName": "Smith",
"customDetails": {
"custom1": null,
"custom2": null,
"custom3": null,
"custom4": null
},
"createdDatetime": "2018-06-03T20:06:03Z",
"updatedDatetime": null
},
"conversation": {
"id": "2f719ebc5b144a18b75f44n12188288",
"contactId": "9354647c5b144a2b4c99f2n42497249",
"status": "active",
"createdDatetime": "2018-03-28T13:28:00Z",
"updatedDatetime": "2018-03-28T13:28:00Z",
"lastReceivedDatetime": "2018-03-28T13:28:00Z",
"lastUsedChannelId": "2f719ebc5b144a18b75f44n12188288",
"lastUsedPlatformId": "sms"
},
"message": {
"id": "8909570c5b71a40bb957f1n63383684",
"conversationId": "2f719ebc5b144a18b75f44n12188288",
"channelId": "2f719ebc5b144a18b75f44n12188288",
"status": "delivered",
"type": "text",
"direction": "sent",
"content": {
"text": "hello"
},
"createdDatetime": "2018-08-13T15:30:19Z",
"updatedDatetime": "2018-08-13T15:30:20Z"
}
}

Message Updated Event

{
"type": "message.updated",
"contact": {
"id": "9354647c5b144a2b4c99f2n42497249",
"href": "https://rest.messagebird.com/1/contacts/9354647c5b144a2b4c99f2n42497249",
"msisdn": 316123456789,
"firstName": "Jen",
"lastName": "Smith",
"customDetails": {
"custom1": null,
"custom2": null,
"custom3": null,
"custom4": null
},
"createdDatetime": "2018-06-03T20:06:03Z",
"updatedDatetime": null
},
"conversation": {
"id": "2f719ebc5b144a18b75f44n12188288",
"contactId": "9354647c5b144a2b4c99f2n42497249",
"status": "active",
"createdDatetime": "2018-03-28T13:28:00Z",
"updatedDatetime": "2018-03-28T13:28:00Z",
"lastReceivedDatetime": "2018-03-28T13:28:00Z",
"lastUsedChannelId": "95e223e381364b00b1b21e52bbc6285e",
"lastUsedPlatformId": "sms"
},
"message": {
"id": "8909570c5b71a40bb957f1n63383684",
"conversationId": "2f719ebc5b144a18b75f44n12188288",
"channelId": "2f719ebc5b144a18b75f44n12188288",
"status": "failed",
"type": "text",
"direction": "sent",
"content": {
"text": "hello"
},
"createdDatetime": "2018-08-13T15:30:19Z",
"updatedDatetime": "2018-08-13T15:31:20Z"
},
"error": {
"code": 470,
"description": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid message template."
}
}

Status update per message

When sending a message, it's possible to set a different webhook URL per message basis using the reportUrl parameter. The requests contain information about the status of the message, and, in the event of a delivery failure, the payload will contain the failure details.

{
"type": "message.status",
"message": {
"id": "2e15efafec384e1c82e9842075e87beb",
"status": "failed"
},
"error": {
"code": 302,
"description": "The contact is not registered on WhatsApp"
}
}

Conversations

List Conversations

Retrieves all conversations sorted by the lastReceivedDatetime field so that all conversations with new messages appear first.

GET /v1/conversations

Request

ParameterTypeDescriptionRequired
limitintegerThe number of maximum objects to return on each request. The default value is 10 and the maximum is 20.No
offsetintegerThe number of objects to skip from the first. The default value is 10.No
idsstringComma seperated list of conversation IDs to filter. The maximum number of IDs allowed for each request is 20.No
statusConversationStatusFilter based on status of the conversation. The default value is active.No
curl -X GET "https://conversations.messagebird.com/v1/conversations" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"

Response

AttributeTypeDescription
countintegerNumber of conversations returned.
itemsarray of ConversationArray of Conversation objects.
limitintegerThe number of maximum objects returned on each request.
offsetintegerThe number of objects skipped.
totalCountintegerThe number of total conversation objects that can be retrieved through pagination.
{
"offset": 0,
"limit": 20,
"count": 2,
"totalCount": 2,
"items": [
{
"id": "fbbdde79129f45e3a179458a91e2ead6",
"contactId": "03dfc27855c3475b953d6200a1b7eaf7",
"contact": {
"id": "03dfc27855c3475b953d6200a1b7eaf7",
"href": "https://rest.messagebird.com/contacts/03dfc27855c3475b953d6200a1b7eaf7",
"msisdn": 31612345678,
"firstName": "John",
"lastName": "Doe",
"customDetails": {
"custom1": null,
"custom2": null,
"custom3": null,
"custom4": null
},
"createdDatetime": "2018-08-01T09:45:52Z",
"updatedDatetime": "2018-08-28T12:37:35Z"
},
"channels": [
{
"id": "619747f69cf940a98fb443140ce9aed2",
"name": "My WhatsApp",
"platformId": "whatsapp",
"status": "active",
"createdDatetime": "2018-08-28T11:56:57Z",
"updatedDatetime": "2018-08-29T08:16:33Z"
},
],
"status": "active",
"createdDatetime": "2018-08-29T08:52:54Z",
"updatedDatetime": "2018-08-29T08:52:54Z",
"lastReceivedDatetime": "2018-08-29T08:52:54Z",
"lastUsedChannelId": "619747f69cf940a98fb443140ce9aed2",
"lastUsedPlatformId": "whatsapp",
"messages": {
"totalCount": 10,
"href": "https://conversations.messagebird.com/v1/conversations/fbbdde79129f45e3a179458a91e2ead6/messages"
}
},
{
"id": "2e15efafec384e1c82e9842075e87beb",
"contactId": "a621095fa44947a28b441cfdf85cb802",
"contact": {
"id": "a621095fa44947a28b441cfdf85cb802",
"href": "https://rest.messagebird.com/1/contacts/a621095fa44947a28b441cfdf85cb802",
"msisdn": 316123456789,
"firstName": "Jen",
"lastName": "Smith",
"customDetails": {
"custom1": null,
"custom2": null,
"custom3": null,
"custom4": null
},
"createdDatetime": "2018-06-03T20:06:03Z",
"updatedDatetime": null
},
"channels": [
{
"id": "853eeb5348e541a595da93b48c61a1ae",
"name": "SMS",
"platformId": "sms",
"status": "active",
"createdDatetime": "2018-08-28T11:56:57Z",
"updatedDatetime": "2018-08-29T08:16:33Z"
},
{
"id": "619747f69cf940a98fb443140ce9aed2",
"name": "My WhatsApp",
"platformId": "whatsapp",
"status": "active",
"createdDatetime": "2018-08-28T11:56:57Z",
"updatedDatetime": "2018-08-29T08:16:33Z"
}
],
"status": "active",
"createdDatetime": "2018-08-13T09:17:22Z",
"updatedDatetime": "2018-08-29T07:35:48Z",
"lastReceivedDatetime": "2018-08-29T07:35:48Z",
"lastUsedChannelId": "853eeb5348e541a595da93b48c61a1ae",
"lastUsedPlatformId": "sms",
"messages": {
"totalCount": 23,
"href": "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages"
}
},
]
}
Response codes
CodeDescription
200Ok.
400Invalid HTTP request. The HTTP response should include details about the error.
401Unauthorized.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

Get Conversation

Retrieves a specific conversation.

ParameterTypeDescriptionRequired
idstringThe unique ID that identifies the conversation.Yes
GET /v1/conversations/{id}

Request

curl -X GET "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"

Response

The HTTP response contains a Conversation object.

{
"id": "2e15efafec384e1c82e9842075e87beb",
"contactId": "a621095fa44947a28b441cfdf85cb802",
"contact": {
"id": "a621095fa44947a28b441cfdf85cb802",
"href": "https://rest.messagebird.com/1/contacts/a621095fa44947a28b441cfdf85cb802",
"msisdn": 316123456789,
"firstName": "Jen",
"lastName": "Smith",
"customDetails": {
"custom1": null,
"custom2": null,
"custom3": null,
"custom4": null
},
"createdDatetime": "2018-06-03T20:06:03Z",
"updatedDatetime": null
},
"channels": [
{
"id": "853eeb5348e541a595da93b48c61a1ae",
"name": "SMS",
"platformId": "sms",
"status": "active",
"createdDatetime": "2018-08-28T11:56:57Z",
"updatedDatetime": "2018-08-29T08:16:33Z"
},
{
"id": "619747f69cf940a98fb443140ce9aed2",
"name": "My WhatsApp",
"platformId": "whatsapp",
"status": "active",
"createdDatetime": "2018-08-28T11:56:57Z",
"updatedDatetime": "2018-08-29T08:16:33Z"
}
],
"status": "active",
"createdDatetime": "2018-08-13T09:17:22Z",
"updatedDatetime": "2018-08-29T07:35:48Z",
"lastReceivedDatetime": "2018-08-29T07:35:48Z",
"lastUsedChannelId": "853eeb5348e541a595da93b48c61a1ae",
"lastUsedPlatformId": "sms",
"messages": {
"totalCount": 23,
"href": "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages"
}
}
Response codes
CodeDescription
200Ok.
401Unauthorized.
404Conversation not found.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

Update Conversation

Updates a specific conversation.

PATCH /v1/conversations/{id}

Request

ParameterTypeDescriptionRequired
statusConversationStatusThe new status of the conversation.Yes
curl -X PATCH "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json" \
-d '{
"status": "archived"
}'

Response

The HTTP response contains a Conversation object.

{
"id": "2e15efafec384e1c82e9842075e87beb",
"contactId": "a621095fa44947a28b441cfdf85cb802",
"contact": {
"id": "a621095fa44947a28b441cfdf85cb802",
"href": "https://rest.messagebird.com/1/contacts/a621095fa44947a28b441cfdf85cb802",
"msisdn": 316123456789,
"firstName": "Jen",
"lastName": "Smith",
"customDetails": {
"custom1": null,
"custom2": null,
"custom3": null,
"custom4": null
},
"createdDatetime": "2018-06-03T20:06:03Z",
"updatedDatetime": null
},
"channels": [
{
"id": "853eeb5348e541a595da93b48c61a1ae",
"name": "SMS",
"platformId": "sms",
"status": "active",
"createdDatetime": "2018-08-28T11:56:57Z",
"updatedDatetime": "2018-08-29T08:16:33Z"
},
{
"id": "619747f69cf940a98fb443140ce9aed2",
"name": "My WhatsApp",
"platformId": "whatsapp",
"status": "active",
"createdDatetime": "2018-08-28T11:56:57Z",
"updatedDatetime": "2018-08-29T08:16:33Z"
}
],
"status": "archived",
"createdDatetime": "2018-08-13T09:17:22Z",
"updatedDatetime": "2018-08-29T07:35:48Z",
"lastReceivedDatetime": "2018-08-29T07:35:48Z",
"lastUsedChannelId": "853eeb5348e541a595da93b48c61a1ae",
"lastUsedPlatformId": "sms",
"messages": {
"totalCount": 23,
"href": "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages"
}
}
Response codes
CodeDescription
200Ok.
400Invalid HTTP request. The HTTP response should include details about the error.
401Unauthorized.
404Conversation not found.
422An active conversation already exist.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

Get Conversations by Contact

Retrieves the list of conversation IDs of a specific contact ID.

GET /v1/conversations/contact/{id}

Request

ParameterTypeDescriptionRequired
idstringThe MessageBird contact ID.Yes
limitintegerThe number of maximum objects to return on each request. The default value is 10 and the maximum is 20.No
offsetintegerThe number of objects to skip from the first. The default value is 10.No
statusConversationStatusFilter the results by a specific conversation status. The default value is allNo
curl -X GET "https://conversations.messagebird.com/v1/conversations/contact/ebf6aceed7ae4375b726e247318d3377"
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Response

AttributeTypeDescription
countintegerNumber of conversations returned.
itemsarray of stringArray of conversation IDs.
limitintegerThe number of maximum objects returned on each request.
offsetintegerThe number of objects skipped.
totalCountintegerThe number of total conversation objects that can be retrieved through pagination.
{
"offset": 0,
"limit": 20,
"count": 2,
"totalCount": 2,
"items": [
"0b7c237df609487c9c41437dab502889",
"9eaceec9cd244e7a9b374df81aad4349"
]
}
Response codes
CodeDescription
200Ok.
400Invalid HTTP request. The HTTP response should include details about the error.
401Unauthorized.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

Messages

Get Messages in Conversation

Retrieves the messages of a specific conversation.

GET /v1/conversations/{id}/messages

Request

ParameterTypeDescriptionRequired
idstringThe unique ID that identifies the conversation.Yes
limitintegerThe number of maximum objects to return on each request. The default value is 10 and maximum is 20.No
offsetintegerThe number of objects skipped.No
excludePlatformsList of PlatformIgnore messages from the specific platforms (separated by comma). Limited to 10 platforms.No
curl -X GET "https://conversations.messagebird.com/v1/conversations/5f3437fdb8444583aea093a047ac014b/messages" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"

Response

AttributeTypeDescription
countintegerNumber of messages returned.
itemsarray of MessageAn array of message objects.
limitintegerThe number of maximum objects returned on each request.
offsetintegerThe number of objects skipped.
totalCountintegerThe number of total message objects that can be retrieved through pagination.
{
"count": 2,
"items": [
{
"id": "a25c8e4dbd0347198c6c404a6db2aadc",
"conversationId": "5f3437fdb8444583aea093a047ac014b",
"platform": "telegram",
"to": "517420321",
"from": "MessageBird",
"channelId": "c92c0babdc764d8674bcea14a55d867d",
"type": "text",
"content": {
"text": "Hello!"
},
"direction": "sent",
"status": "sent",
"createdDatetime": "2020-03-06T12:35:59.957903187Z",
"updatedDatetime": "2020-03-06T12:36:01.405545547Z"
},
{
"id": "195d2ac7ea364564a54ed5f9b05c4c17",
"conversationId": "5f3437fdb8444583aea093a047ac014b",
"platform": "telegram",
"to": "121830327",
"from": "MessageBird",
"channelId": "c92c0babdc764d8674bcea14a55d867d",
"type": "text",
"content": {
"text": "Hello!"
},
"direction": "sent",
"status": "sent",
"createdDatetime": "2020-03-05T15:31:23.200954713Z",
"updatedDatetime": "2020-03-05T15:31:23.207428669Z"
}
],
"limit": 10,
"offset": 0,
"totalCount": 2
}
Response codes
CodeDescription
200Ok.
400Invalid HTTP request. The HTTP response should include details about the error.
401Unauthorized.
404Conversation not found.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

Get Message

Retrieves a message given a specific ID.

GET /v1/messages/{id}

Request

ParameterTypeDescriptionRequired
idstringThe unique ID that identifies the message.Yes
curl -X GET "https://conversations.messagebird.com/v1/messages/5f3437fdb8444583aea093a047ac014b" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"

Response

The HTTP response contains a Message object.

{
"id": "5f3437fdb8444583aea093a047ac014b",
"conversationId": "ef39fbf69170b58787ce4e574db9d842",
"platform": "telegram",
"to": "927241320",
"from": "messagebird",
"channelId": "3ab1faad513e753501264a716622ba06",
"type": "text",
"content": {
"text": "Hello!"
},
"direction": "sent",
"status": "sent",
"createdDatetime": "2020-03-05T15:05:59.412358103Z",
"updatedDatetime": "2020-03-05T15:05:59.418598938Z"
}
Response codes
CodeDescription
200Ok.
400Invalid HTTP request. The HTTP response should include details about the error.
401Unauthorized.
404Message not found.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

List Messages

Retrieves a list of messages given a list of message IDs or a timestamp (not both).

GET /v1/messages?ids={ids}&from={datetime}

Request

ParameterTypeDescriptionRequired
idsstringComma separated message IDs. Maximum of 20 messages.No, if from is provided
fromDatetimeA datetime in the RFC3339 format which specifies since when messages should be retrieved. Must be maximum 5 minutes.No, if ids is provided
curl -X GET "https://conversations.messagebird.com/v1/messages?ids=5f3437fdb8444583aea093a047ac014b,4abc37fdb8444583aea093a047ac014c" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"

Response

AttributeTypeDescription
itemsarray of MessageAn array of message objects.
{
"items": [{
"id": "5f3437fdb8444583aea093a047ac014b",
"conversationId": "ef39fbf69170b58787ce4e574db9d842",
"platform": "telegram",
"to": "927241320",
"from": "messagebird",
"channelId": "3ab1faad513e753501264a716622ba06",
"type": "text",
"content": {
"text": "Hello!"
},
"direction": "sent",
"status": "sent",
"createdDatetime": "2020-03-05T15:05:59.412358103Z",
"updatedDatetime": "2020-03-05T15:05:59.418598938Z"
}, {
"id": "4abc37fdb8444583aea093a047ac014c",
"conversationId": "ef39fbf69170b58787ce4e574db9d842",
"platform": "telegram",
"to": "927241320",
"from": "messagebird",
"channelId": "3ab1faad513e753501264a716622ba06",
"type": "text",
"content": {
"text": "Hello 2!"
},
"direction": "sent",
"status": "sent",
"createdDatetime": "2020-03-05T15:05:59.412358103Z",
"updatedDatetime": "2020-03-05T15:05:59.418598938Z"
}]
}
Response codes
CodeDescription
200Ok.
400Invalid HTTP request. The HTTP response should include details about the error.
401Unauthorized.
429Too many concurrent requests. Please retry the request with standard exponential backoff.
499The client closed the connection.
500Unexpected internal server error. Please retry the request with standard exponential backoff.

Objects Reference

Conversation object

AttributeTypeDescription
idstringAn unique ID generated by MessageBird that identifies the conversation.
contactIdstringThe MessageBird contact ID for the conversation.
contactContactThe MessageBird Contact for this conversation.
channelsarray of ChannelA series of Channels through which the contact of the conversation can be reached. This attribute can be empty if the conversation doesn't have any channels yet.
statusConversationStatusThe status of the conversation.
createdDatetimeDatetimeThe date and time when the conversation was created in RFC3339 format.
updatedDatetimeDatetimeThe date and time when the conversation was most recently updated in RFC3339 format. It only applies to changes in the conversation object itself, not its messages.
lastReceivedDatetimeDatetimeThe date and time when the most recent message was added to the conversation in RFC3339 format.
lastUsedChannelIdstringAn unique ID for the most recently used channel that sent or received a message to the conversation.
lastUsedPlatformIdPlatformThe platform name of the channel which most recently sent or received a message in the conversation.
messagesMessagesA link to the messages of this conversation

Contact object

Contacts are a representation of an end-user you are communicating with; contacts are also available through the REST API via the Contacts API.

AttributeTypeDescription
idstringThe unique ID generated by the MessageBird platform that identifies this contact.
hrefstringThe URL of this contact object.
msisdnstringThe phone number of this contact.
firstNamestringThe first name of this contact. Where the first name is not known, msisdn will be used as the firstName instead.
lastNamestringThe last name of this contact.
customDetailsobjectAdditional platform specific details about this contact.
createdDatetimedatetimeThe datetime when the message was created (in RFC3339 format).
updatedDatetimedatetimeThe datetime when the message was updated (in RFC3339 format).

Channel object

A channel enables you to send and receive messages through a platform (WhatsApp, Telegram, Email, etc.). A conversation may contain messages of multiple channels simultaneously. You can configure your channels using the Channels Overview.

AttributeTypeDescription
idstringThe unique ID generated by the MessageBird platform that identifies this channel.
namestringThe name of this channel (configured through the MessageBird Dashboard).
platformIdPlatformThe platform name. For example: sms, whatsapp, email, etc..
statusChannelStatusThe status of the channel.
createdDatetimedatetimeThe datetime when the message was created (in RFC3339 format).
updatedDatetimedatetimeThe datetime when the message was updated (in RFC3339 format).

ChannelStatus object

ValueDescription
activeThe channel is active and, therefore, can send and receive messages.
deletedThe channel is deleted and, therefore, cannot be used anymore.
unavailableThe channel is currently unavailable.

Messages object

AttributeTypeDescription
hrefstringA link to the endpoint to retrieve messages of the conversation.
totalCountintegerThe total number of messages that can be retrieved through pagination for the conversation.
lastMessageIdstringThe unique ID generated by MessageBird that identifies the latest message.

Webhook object

AttributeTypeDescription
idstringThe unique ID generated by MessageBird that identifies the webhook.
eventsArray of WebhookEventsA list of event names that should trigger this webhook.
channelIdstringThe unique identifier for a MessageBird channel that this webhook is subscribed.
messageIdstringThe unique message identifier for a message associated to the webhook.
urlstringThe endpoint URL that requests should be sent to.
statusWebhookStatusThe webhook status: enabled.
createdDatetimeDatetimeThe date and time when the webhook was created (in RFC3339 format).
updatedDatetimeDatetimeThe date and time when the webhook was updated (in RFC3339 format).
settingsWebhookSettingsThe webhook extra settings.

WebhookEvents object

ValueDescription
conversation.createdA new conversation has been created.
conversation.updatedA conversation has been updated with a new status.
message.createdA new message has been created. Triggered for both sent and received messages.
message.updatedA message has been updated with a new status.

WebhookStatus object

ValueDescription
enabledThe webhook is enabled, therefore events will be delivered.
disabledThe webhook is disabled, therefore events won't be delivered.

WebhookSettings object

AttributeTypeDescription
settings.expected_http_codestringThe expected HTTP status code mask (like: 2xx, 200 and 201).
settings.headershashCustom HTTP headers for the outgoing request (max length: 1024).
settings.usernamestringBasic auth username (max length: 255).
settings.passwordstringBasic auth password (max length: 255).
settings.query_paramsstringThe query parameters (max length: 2048).
settings.retryintegerThe number of maximum retries (between 0-10).
settings.timeoutintegerThe request timeout in seconds (between 1-30).

Message object

Messages that have been sent by, or received from, a customer are automatically grouped in a conversation. Any messages sent through the API or received from your customer across any of your configured channels can be retrieved via the messages endpoints. Messages are returned from the API in the order they were created, with newest messages returned first. Certain message types are channel specific such as a Highly Structured Message (HSM), which must be pre-approved by Facebook.

AttributeTypeDescription
idstringThe unique ID generated by the MessageBird platform that identifies this message.
conversationIdstringThe unique ID that identifies the conversation that this message is a part of.
channelIdstringThe unique ID that identifies the channel that the message was sent or received on.
platformPlatformThe platform name of the channel which the message was sent or received.
toMessageRecipientThe unique ID that identifies the message recepient. The value depends on platform.
fromstringThe unique ID that identifies the message sender. The value depends on platform.
directionMessageDirectionThe direction of the message.
statusMessageStatusThe status of the message.
typeMessageTypeThe type of the message content.
contentMessageContentContent of the message. The type field indicates the fields that will be populated in this object.
createdDatetimedatetimeThe datetime when the message was created (in RFC3339 format).
updatedDatetimedatetimeThe datetime when the message was updated (in RFC3339 format).
sourceobjectA JSON-formatted object that can be used to identify the source of the message.
tagMessageTagMessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.

MessageContent object

AttributeTypeDescription
content.textstringRequired for type text. The plain-text content of the message.
content.imageMediaRequired for type image.
content.videoMediaRequired for type video.
content.audioMediaRequired for type audio.
content.fileMediaRequired for type file.
content.locationLocationRequired for type location.
content.hsmMessageHSMRequired for type hsm. Available only for WhatsApp.
content.interactiveMessageInteractiveRequired for type interactive. Available only for WhatsApp.
content.emailEmailRequired for type email. Available only for Email channels.
content.externalAttachmentsarray of MediaUsed for story mentions. Available only for Instagram channels.
content.disableUrlPreviewboolOptional field for type text. When set to true, conversations will try to disable previews for urls in your text messages. Only supported by Whatsapp. Default value is false

MessageRecipient object

It represents the identification of a specific recipient in a platform. For example, in SMS platform, identifiers are the phone numbers (MSISDN). There are a few types of identifiers:

  • Phone number
  • Email address
  • Platform-specific: the platform assigns a universal identifier to every recipient
  • Channel-specific: the identifier of the recipients varies from channel to channel

The following table displays the identifiers for every supported platform.

PlatformIdentifier
SMSPhone number
WhatsAppPhone number
FacebookChannel-specific
TelegramPlatform-specific
LINEChannel-specific
WeChatPlatform-specific
EmailE-mail address
Apple Business ChatChannel-specific
TwitterPlatform-specific
ViberPhone number
LivechatChannel-specific
Google Business MessagesChannel-specific
InstagramChannel-specific

Fallback object

AttributeTypeDescription
fromstringThe ID that identifies the channel over which the message should be sent.
afterstringThis is optional. You can set a time period before attempting to send the fallback. After this time, if the original message isn't in a successfully delivered state, the fallback will be triggered. Formatted as a short-hand duration, for example: "30m" for 30 minutes, "3h" for 3 hours. If the fallback time period isn't specified, 1 minute will be used as the default value.

Media object

For more information about the media types supported per platform, please check the section Supported media types per platform.

AttributeTypeDescription
urlstringThe url of the remote media file. If the media is hosted inside MessageBird, you will need to set the Authorization header with your MessageBird AccessKey.
captionstringThe caption associated with the media file

Location object

AttributeTypeDescription
latitudefloatThe latitude coordinates of the location.
longitudefloatThe longitude coordinates of the location.

MessageHSM object

HSM stands for "Highly Structured Message" and can only be sent over a WhatsApp channel.

AttributeTypeDescription
namespacestringRequired. WhatsApp namespace for your account. You will receive this value when setting up your WhatsApp account.
templateNamestringRequired. Template name.
languageHSMLanguageThe message language.
paramsarray of HSMLocalizableParametersParameters for regular templates.
componentsarray of MessageComponentParameters for media templates.

HSMLanguage object

Until January 2020, WhatsApp supported two possible values for hsm.language.policy: deterministic and fallback (deprecated). Deterministic will deliver the message template using the language and locale asked for, and fallback was used to deliver the message template using the user's device language, if the language couldn't be determined, then the fallback language is used. More details are available in the Language section of Whatsapp documentation page.

AttributeTypeDescription
policystringDefault value: deterministic. The fallback value was deprecated in January 2020.
codestringRequired. The code of the language or locale to use. It must correspond to one of the languages approved in the WhatsApp template you're using to send a message.

HSMLocalizableParameters object

Some of the template parameters related to date/time and currency are localizable and can be displayed based on a customer's device language and local preferences. Default values are used when localization fails.

AttributeTypeDescription
defaultstringRequired. Default value of the parameter, it is used when localization fails. The only field needed when specifying parameter value that doesn't require localization.
currencyobjectCan be present only if dateTime object is not present. An object of the form {"currencyCode": "required string of ISO 4217 currency code", "amount": "required integer of total amount together with cents as a float, multiplied by 1000"}
dateTimestringCan be present only if currency object is not present. RFC3339 representation of the date and time.

MessageComponent object

In a media template, there is a layout which is consists of header, body and footer. Header and body are configurable by a user input in component property.

AttributeTypeDescription
typestringRequired. Value could be set to header or body.
sub_typestringOptional. Required when type is set to button. Supported values are: quick_reply and url
indexintegerOptional. Required when type is set to button. You can have up to 3 buttons using index values of 0-2.
parametersarray of MessageParamRequired. Parameters to be used in the template message.

MessageParam object

Component parameters are the values that are replaced in the template message. The possible types are text, payload, image, document, currency and dateTime.

The parameter types are dependent on the component types. The possible values for each component type is as follows

  • Header: image or document
  • Body : text, currency, datetime
  • Button: text, payload (maximum 3 buttons are only possible)
AttributeTypeDescription
typeTemplateMediaTypeRequired. Defines the parameter type.
textstringRequired for type text
payloadstringRequired for type payload
currencyHSMCurrencyRequired for type currency. Defines the currency details.
dateTimestringRequired for type date_time Can be present only if currency object is not present. RFC3339 representation of the date and time.
documentMediaRequired for type document
imageMediaRequired for type image

TemplateMediaType object

ValueDescription
imageImage. It can be used when the component type (hsm.components.type) is header
documentDocument. It can be used when the component type (hsm.components.type) is header
textText. It can be used when the component type (hsm.components.type) is button
currencyCurrency
date_timeDate/time
payloadPayload. It can be used when the component type (hsm.components.type) is button

HSMCurrency object

AttributeTypeDescription
currencyCodestringCurrency code as defined in ISO 4217
amountintAmount with cents multiplied by 1000. So $100.99 would be 100990

MessageTag object

Message tags allow messages to be marked with a particular tag. The meaning and effect of each tag depend on each specific platform. Using Conversations API, it's possible to set a MessageBird Message Tag, which will be converted to a platform-specific message tag. The table below displays the correspondence between MessageBird Message Tags and platform-specific message tags.

MessageBird Message TagFacebook Message TagPlatform-specific Description
event.updateCONFIRMED_EVENT_UPDATESend the user reminders or updates for an event they have registered for (e.g., RSVP'ed, purchased tickets).
purchase.updatePOST_PURCHASE_UPDATENotify the user of an update on a recent purchase.
account.updateACCOUNT_UPDATENotify the user of a non-recurring change to their application or account.
human_agentHUMAN_AGENT (Closed BETA) Apply for accessAllows human agents to respond to user inquiries. Messages can be sent within 7 days after a user message.

More details about Facebook Message Tags are available here: https://developers.facebook.com/docs/messenger-platform/send-messages/message-tags/

MessageInteractive object

The following messages are considered interactive:

  • List Messages: Messages including a menu of up to 10 options. This type of message offers a simpler and more consistent way for users to make a selection when interacting with a business.
  • Reply Buttons: Messages including up to 3 options —each option is a button. This type of message offers a quicker way for users to make a selection from a menu when interacting with a business. Reply buttons have the same user experience as interactive templates with buttons.
AttributesTypeDescription
typestringRequired. Supported values: list, button and list_reply, button_reply when message is inbound
headerMessageInteractiveHeaderOptional. Header content displayed on top of a message.
bodyMessageInteractiveBodyRequired. The body of the message. Emojis and markdown are supported.
actionMessageInteractiveActionRequired. Action you want the user to perform after reading the message.
footerMessageInteractiveFooterOptional. The footer of the message. Emojis and markdown are supported.
replyMessageInteractiveReplyAvailable only when message is inbound

MessageInteractiveHeader object

Header content displayed on top of a message.

AttributesTypeDescription
typestringRequired. The header type you would like to use. Supported values are: text: Used for List Messages and Reply Buttons., video: Used for Reply Buttons. , image: Used for Reply Buttons., document: Used for Reply Buttons.
textstringRequired if type is set to text. Text for the header. Formatting allows emojis, but not markdown. Maximum length: 60 characters.
videoMediaRequired if type is set to video.
imageMediaRequired if type is set to image.
documentMediaRequired if type is set to document.

MessageInteractiveBody object

The body of the message.

AttributesTypeDescription
textstringRequired. The body content of the message. Emojis and markdown are supported. Links are supported. Maximum length: 1024 characters.

MessageInteractiveAction object

Action you want the user to perform after reading the message.

  • List Messages: | Attributes | Type | Description | | ---------- | ---- | ----------- | | button | string | Required for List Messages. Button content. must be unique within the message, Does not allow emojis or markdown. Maximum length: 20 characters. | | sections | array of MessageInteractiveSection | Required for List Messages. |

  • Reply Buttons: | Attributes | Type | Description | | ---------- | ---- | ----------- | | buttons | array of MessageInteractiveButton | Required for Reply Button Messages. |

MessageInteractiveButton object

AttributesTypeDescription
idstringRequired. Must be unique within buttons. Maximum length: 256 characters.
typestringRequired. Only supported type reply for Reply Button Messages. Maximum length: 20 characters.
titlestringRequired. Must be unique within buttons. Maximum length: 20 characters.

MessageInteractiveSection object

AttributesTypeDescription
titlestringRequired. if the message has more than one section. Maximum length: 24 characters.
rowsarray of MessageInteractiveSectionRowRequired. contain list of rows for list messages.

MessageInteractiveSectionRow object

AttributesTypeDescription
titlestringRequired. row title text. Maximum length: 24 characters.
idstringRequired. must be unique within rows. Maximum length: 200 characters.
descriptionstringOptional. Maximum length: 72 characters.

MessageInteractiveFooter object

The footer of the message.

AttributesTypeDescription
textstringRequired. The footer content of the message. Emojis and markdown are supported. Links are supported. Maximum length: 60 characters.

MessageInteractiveReply object

Represents an interactive reply when message is inbound.

AttributesTypeDescription
idstringRequired. The unique id of button reply or list message reply
textstringRequired. The text content of reply or list message reply
descriptionstringOptional. The description content of button reply or list message reply

Email object

Email represents an email message and it's one of the content types available in Conversations API. The required fields are to, from, subject and content. Before sending a message with attachments or inline images, you need to upload them to the Messaging API and then use its IDs in the payload. For more information about how to upload attachments and inline images, refer to the Upload attachments and inline images.

AttributesTypeDescription
idstringAn unique random ID for this message on the MessageBird platform, returned upon acceptance of the message.
toArray of EmailRecipientRequired. An array containing of all the recipients of the message.
fromEmailRecipientRequired. Name / address that will be displayed in the from field of the sent messages, the domain in the address email must be registered to one of your channels.
subjectstringRequired. This will be displayed as the subject in the message, expected in the UTF-8 charset without RFC2047 encoding.
contentEmailContentRequired. HTML or text content for the email. At least one type of content is required.
replyTostringEmail address used to compose the email's "Reply-To" header.
returnPathstringEmail address used to compose the email's "Return-Path" header. Must match your sending domain.
headersobjectObject containing custom headers other than Subject, From, To, and Reply-To. These will be sent along with your message.
trackingEmailTrackingOptional. Allows you to set tracking options.
reportUrlstringThe URL for delivery of status reports for the message. Must use https.
performSubstitutionsboolPerform substitutions of variables inside the content or headers of your email (Default: true).
attachmentsarray of EmailAttachmentOptional. List of files attached to a message.
inlineImagesarray of EmailInlineImageOptional. List of inline images added to the message content.
EmailContent object

The email content object represents the content to be included as the body of your message, it can contain either HTML or plain text.

AttributesTypeDescription
htmlstringHTML content of the message, expected in UTF-8.
textstringPlain text of the message, expected in UTF-8.
EmailRecipient object

You can specify the recipients of your email as an array of objects with the properties listed below. Variables added for each recipient are used to customise the content sent to a user if a template with matching dynamic placeholders is used in the body or custom headers. Additional variables not present in the content or headers are ignored.

AttributesTypeDescriptionExample
emailstringRequired. Valid email addressdemo@messagebird.com
namestringName attached to the email address, this appears in the To field in a users email clientJane Doe
variablesobjectList of variables used for placeholders inside the content or headers of your email{"firstname": "John", "lastname": "Doe"}
EmailTracking object
AttributesTypeDescription
openboolAdds a tracking pixel to handle message.opened events. (Default: true)
clickboolAdds link-wrapping to handle link.clicked events. (Default: true)
EmailAttachment object

The Attachment object represents a file attached to a particular message. The maximum attachment size is 20 MB.

AttributesTypeDescription
idstringAttachment ID.
namestringFile name.
typestringFile type.
URLstringURL of the file to be attached to the message.
lengthintegerFile size in bytes.
EmailInlineImage object

The Inline Image object represents an image added to the message content. The maximum image size is 20 MB.

In order to use the inline image in the content of the message, you must refer the contentId using the img tag. For example: <img src="cid:<contentId>">

AttributesTypeDescription
idstringInline image ID.
namestringFile name.
typestringFile type.
URLstringURL of the file.
lengthintegerFile size in bytes.
contentIdstringID used in the content of the message.
ConversationStatus object
ValueDescription
activeNew inbound or outbound messages will be added to the conversation.
archivedThe conversation is archived, therefore, it won't receive any new messages.
allCan be used when listing conversations for fetching active and archived conversations.
MessageStatus object
PlatformValueDescription
AllacceptedThe message is accepted and it will be processed asynchronously.
AllpendingThe message is pending to be delivered.
AllsentThe message is sent.
AllrejectedThe message is rejected. The reason should be available in the message details.
AllfailedThe message failed to be delivered.
AllreadThe message was read by the recipient.
AllreceivedInbound message.
AlldeletedThe message is deleted.
AllunknownThe message status is temporarily unknown.
SMSdelivery_failedThe message failed to be delivered.
SMSbufferedThe message is enqueued to be delivered.
SMSexpiredThe message was not delivered in time.
EmailclickedThe recipient clicked in a tracked link in the message.
EmailopenedThe recipient opened the message.
EmailbounceThe message was permanently rejected by the recipient's email server.
Emailspam_complaintThe message was marked as spam by the recipient.
Emailout_of_boundedThe recipient's email server accepted the message, however, later it reported the message was not delivered.
EmaildelayedThe recipient's email server temporarily rejected the message (it will be retried).
Emaillist_unsubscribeThe recipient clicked the 'Unsubscribe' button in their email client.
EmaildispatchedThe message, which was addressed to multiple recipients, was delivered to Sparkpost (email provider).
MessageType object
ValueDescription
textText message.
imageImage.
videoVideo.
audioAudio message.
fileFile.
locationLocation.
hsmWhatsApp Template message (Highly Structured Message)
eventConversation event, not a real message and won't visible by your contacts.
emailEmail message.
richRich content message.
menuMenu message.
buttonsMessage with buttons.
linkLink.
externalAttachmentUsed for story mentions. Currently available only for Instagram.
MessageDirection object
ValueDescription
sentA message sent from you to your contacts (outbound message).
receivedA message received by you (inbound message).

Platforms

Supported media types per platform

This section describes the media types supported by platforms and their restrictions.

WhatsApp

MediaTypesLimitNotes
audioaudio/aac, audio/mp4, audio/mpeg, audio/amr, audio/ogg16 MBOnly opus codecs, base audio/ogg is not supported
documentAny valid MIME-type.100 MB-
imageimage/jpeg, image/png5 MB-
stickerimage/webp100 KB-
videovideo/mp416 MBOnly H.264 video codec and AAC audio codec is supported. Only videos with a single audio stream are supported.

Instagram

MediaTypesLimit
imagejpg, gif, png, ico, bmp8 MB

Facebook

MediaTypesLimitNotes
imagepng, jpeg25 MBThe maximum resolution for images is 85 Megapixel.
videomp425 MB-
audiomp3, wav, ogg25 MB-
filecsv, pdf, ...25 MB-

Telegram

MediaTypesLimit
imagepng, jpgmax 10 MB for multipart form upload or 5 MB if posted as URL
videomp4max 50 MB for multipart form upload or 5 MB if posted as URL
audiomp3, oggmax 50 MB for multipart form upload or 5 MB if posted as URL
filepdfmax 50 MB for multipart form upload or 5 MB if posted as URL

LINE

MediaTypesLimit
audiom4a200 MB
videomp4200 MB
imagejpeg, png10 MB

WeChat

MediaTypesLimit
audiomp3, amr2 MB
videomp410 MB
imagegif, png and jpg1 MB

Viber

MediaTypesLimit
imagepng, jpg50 MB

Email

The entire payload (text + html + attachments + inline images) is limited to 20 MBs. It supports all types of file.

Apple

An attachment can be an image, PDF, or other file type, and it must be smaller than 100 MB.

SMS

NA.

Twitter

NA.

Google Business Messages

MediaTypesLimit
imagepng, jpg5 MB

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