API Reference

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

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 depend on the customer tier.

Notification icon

Please contact support in case you need higher limits.

HTTP methodRegular customersEnterprise customers
LimitBurstLimitBurst
GET500500500500
POST50250500500
PATCH50250500500
DELETE50250500500

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 send 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.

  • Send message
    • Intended to send a high number of messages
    • The HTTP response provides only the message ID and status
    • 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
    • It quickly accepts the HTTP request and does the same work as the following endpoint asynchronously
  • Start conversation
    • Important: always prefer to use the endpoint for sending messages (POST /v1/send), unless you need the conversation in the HTTP response
    • 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

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
ttlstringOnly supported by WhatsApp. You can set a time period for delivering the message. After this time, the message will be rejected. Formatted as a short-hand duration, for example: "30m" for 30 minutes, "3h" for 3 hours. Minimum value is 15s.No
replyToReplyToDeclare that the message is a reply to a previous messageNo
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
ttlstringOnly supported by WhatsApp. You can set a time period for delivering the message. After this time, the message will be rejected. Formatted as a short-hand duration, for example: "30m" for 30 minutes, "3h" for 3 hours. Minimum value is 15s.No
replyToReplyToDeclare that the message is a reply to a previous messageNo
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.
ttlstringOnly supported by WhatsApp. Time limit for delivering the message. Formatted as a short-hand duration, for example: "30m" for 30 minutes, "3h" for 3 hours. Minimum value is 15s.
{
"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
ttlstringOnly supported by WhatsApp. You can set a time period for delivering the message. After this time, the message will be rejected. Formatted as a short-hand duration, for example: "30m" for 30 minutes, "3h" for 3 hours. Minimum value is 15s.No
replyToReplyToDeclare that the message is a reply to a previous messageNo
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.

Notification icon

If your application fails to accept more than 90% of the HTTP requests in the last 12 hours, with a minimum of 200 HTTP requests, your webhook will be automatically disabled and must be re-enabled via the UPDATE method. You will automatically receive a notification when your webhook is disabled. It can be found in the [MessageBird Dashboard Notifications Center](https://dashboard.messagebird.com/notifications) and you can subscribe to the notification event through your desired emails and webhooks.

Conversation Created Event

AttributeTypeDescription
typeWebhookEventsEvent type (conversation.created)
contactContactContact of the new conversation
conversationConversationNew conversation
Conversation created event example
{
"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
},
"workspaceId": 3917675
}

Conversation Updated Event

AttributeTypeDescription
typeWebhookEventsEvent type (conversation.updated)
contactContactContact of the updated conversation
conversationConversationUpdated conversation
Conversation updated event example
{
"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"
},
"workspaceId": 3917675
}

Conversation Deleted Event

AttributeTypeDescription
typeWebhookEventsEvent type (conversation.deleted)
contactContactContact of the updated conversation
conversationConversationUpdated conversation
Conversation deleted event example
{
"type": "conversation.deleted",
"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": "deleted",
"createdDatetime": "2018-03-28T13:28:00Z",
"updatedDatetime": "2018-03-28T13:28:00Z",
"lastReceivedDatetime": "2018-03-28T13:28:00Z",
"lastUsedChannelId": "95e223e381364b00b1b21e52bbc6285e",
"lastUsedPlatformId": "sms"
},
"workspaceId": 3917675
}

Message Created Event

AttributeTypeDescription
typeWebhookEventsEvent type (message.created)
contactContactContact that received/sent the message
conversationConversationConversation which the message was added
messageMessageNew message
Message created event example
{
"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"
},
"workspaceId": 3917675
}

Message Updated Event

AttributeTypeDescription
typeWebhookEventsEvent type (message.updated)
contactContactContact object
conversationConversationConversation which the message was updated
messageMessageUpdated message
Message updated event example
{
"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."
},
"workspaceId": 3917675
}

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"
},
"workspaceId": 3917675
}

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

ValuePlatformDescription
activeAllThe channel is active and, therefore, can send and receive messages.
activatingWhatsAppThe channel is activating and it should become active soon.
activation_code_requiredWhatsAppThe activation code is necessary to activate the channel.
activation_requiredWhatsAppActivation process is necessary.
activation_failedWhatsAppActivation process has failed.
unavailableWhatsAppThe channel is temporarily unavailable.
not_verifiedWhatsAppThe business wasn't verified in Meta, so the channel can't send or receive messages.
inactiveAllThe channel is inactive and, therefore, can't send or receive messages.
pendingAllThe channel is pending and, therefore, can't send or receive messages.
action_requiredAllAn action is required to activate the channel.
deletedAllThe channel is deleted and, therefore, cannot be used anymore.

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.
conversation.deletedA conversation has been deleted.
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.
ttlstringOnly supported by WhatsApp. Time limit for delivering the message. Formatted as a short-hand duration, for example: "30m" for 30 minutes, "3h" for 3 hours. Minimum value is 15s.
referralMessageReferralOnly supported by WhatsApp. Contains information about from where the recipient came from.
replyToReplyToDeclare that the message is a reply to a previous message

MessageReferral object

The message referral object contains information about where the recipient came from.

Notification icon

Only supported by WhatsApp at the moment.

AttributeTypeDescription
whatsappWhatsAppReferralContains information about the advertisement or Facebook post which was clicked by the recipient.

WhatsAppReferral object

AttributeTypeDescription
headlinestringTitle of the advertisement or Facebook post that generated the message.
bodystringBody of the advertisement or Facebook post that generated the message.
sourceWhatsAppReferralSourceObject that contains information about the advertisement or Facebook post.
mediaWhatsAppReferralMediaObject that contains information about the media used in the advertisement or Facebook post.

WhatsAppReferralSource object

AttributeTypeDescription
typeWhatsAppReferralSourceTypeReferral source type
urlstringURL of the advertisement or Facebook post.
idstringFacebook ID of the advertisement or Facebook post.

WhatsAppReferralMedia object

AttributeTypeDescription
typeWhatsAppReferralMediaTypeReferral media type.
urlstringMedia URL.

WhatsAppReferralSourceType object

ValueDescription
adAdvertisement
postFacebook post

WhatsAppReferralMediaType object

Value
image
video

Platform object

Value
sms
whatsapp
facebook
telegram
line
wechat
email
email_freemium
events
whatsapp_sandbox
apple
twitter
viber
livechat
instagram
googlebm

MessageContent object

AttributeTypeDescriptionPlatforms
textstringRequired for type text. The plain-text content of the message.Multiple
imageMediaRequired for type image.Multiple
videoMediaRequired for type video.Multiple
audioMediaRequired for type audio.Multiple
fileMediaRequired for type file.Multiple
locationLocationRequired for type location.Multiple
buttonsButtonsRequired for type buttons.Multiple
hsmMessageHSMRequired for type hsm.WhatsApp
interactiveWhatsAppInteractiveRequired for type interactive.WhatsApp
emailEmailRequired for type email.Email
externalAttachmentsarray of MediaUsed for story mentions.Instagram
disableUrlPreviewboolOptional field for type text. When set to true, conversations will try to disable previews for urls in your text messages. Default value is false.WhatsApp
whatsappStickerWhatsAppStickerWhatsApp sticker message.WhatsApp
whatsappOrderWhatsAppOrderInbound WhatsApp order message.WhatsApp
whatsappTextWhatsAppTextInbound WhatsApp text message. Used for questions about products.WhatsApp
facebookQuickReplyFacebookMessageFacebook-specific message.Facebook
facebookMediaTemplateFacebookMessageFacebook-specific message.Facebook
facebookGenericTemplateFacebookMessageFacebook-specific message.Facebook
facebookReferralFacebookReferralFacebook-specific referral message.Facebook
lineStickerLineStickerLine-specific sticker message.Line

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
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.

Notification icon

For media on inbound messages, URLs that start with media.messagebird.com will not require an authorization key. For all other media hosted by MessageBird, see below.

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.

Buttons object

Messages with quick reply buttons. These can be sent over the following platforms; Line, Google Business Messaging, and OCW Livechat.

AttributeTypeDescription
textstringText to be sent with the quick replies. Can be a maximum of 300 characters
itemsArray of ButtonItemThe button items to be sent as part of the message.

Below are the platform limitations for the maximum amount of buttons that can be attached to a message.

PlatformMax buttons
Line13
Google Business Messaging13
OCW Livechat20

ButtonItem object

AttributesTypeDescriptionRequired
textstringText shown on the button. Can be a maximum 255 characters.Yes
actionButton actionAction that the button will perform.Yes
ButtonItemAction object

OCW Livechat and Google Business Messaging support only text ButtonItemActionType buttons, other types sent via these platforms will fallback to text buttons.

ValueTypeRequired
typeButtonItemActionTypeYes
uristringOptional. Required when type is set to uri.
ButtonItemActionType object
ValueDescription
textSends a text quick reply.
locationOpen the location screen.
cameraOpen the users camera.
camera_rollOpen the users camera roll.
uriOpen the uri specified.

Example json for a sending a buttons message via the /v1/send endpoint to a Line user

curl -X POST "https://conversations.messagebird.com/v1/send" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json" \
-d '{
"to":"U1234567890",
"from":"aa4c8e7cee664341a22ef9bfd9f52477",
"type":"buttons",
"content":{
"buttons": {
"text":"How can I help you?",
"items": [
{
"text":"I need fries",
"action":{
"type":"text"
}
},
{
"text":"Share location",
"action":{
"type":"location"
}
},
{
"text":"Take a picture",
"action":{
"type":"camera"
}
},
{
"text":"Open camera roll",
"action":{
"type":"camera_roll"
}
},
{
"text":"Click me",
"action":{
"type":"uri",
"uri":"https://messagebird.com/careers"
}
}
]
}
}
}'

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, body, button or carousel.
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.
cardsarray of WhatsAppCarouselCardRequired when type is carousel.

MessageParam object

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

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

  • Header: image, document or video
  • Body : text, currency or datetime
  • Button: text or 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.
documentMediaMessageParamRequired for type document
imageMediaMessageParamRequired for type image
videoMediaMessageParamRequired for type video

MediaMessageParam object

AttributeTypeDescription
urlstringThe URL of the remote media file.

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
videoVideo. 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/

ReplyTo object

ReplyTo object is part of a message and contains a reference of another message in the conversation, for which the original message is a reply.

AttributeTypeDescription
idstringThe id of the referenced message

The supported platforms are shown in the table below. Attempting to send a message with a replyTo object to an unsupported platform will result in 400 Bad Request.

PlatformReceive repliesSend replies
Whatsapp (on premise)YesNo
Whatsapp (cloud hosted)YesYes
TelegramYesYes

Clicks on buttons of WhatsAppInteractive and MessageHSM messages will include the replyTo.id property set with the original message ID. For more information about it, please refer to quickstarts about Send WhatsApp interactive message and Send WhatsApp template messages with buttons.

WhatsAppOrder object

It represents an order made through a Single or Multi-Product message.

Notification icon

WhatsApp order messages can't be sent, only received (inbound only).

AttributesTypeDescription
catalog_idstringID of the catalog that contains the products listed under product_items sections.
product_itemsarray of WhatsAppOrderProductProduct items
textstringText message sent along with the order.

WhatsAppOrderProduct object

AttributesTypeDescription
product_retailer_idstringUnique identifier (in the catalog) of the product.
quantityintNumber of items purchased.
item_pricestringUnitary price of the items.
currencystringCurrency of the price.

WhatsAppText object

It represents a question made by the user about a specific product.

Notification icon

WhatsApp text messages can't be sent, only received (inbound only).

AttributesTypeDescription
textWhatsAppTextBodyText message
contextWhatsAppContextMessage context

WhatsAppTextBody object

AttributesTypeDescription
bodystringMessage body

WhatsAppContext object

AttributesTypeDescription
fromstringWhatsApp ID of the sender of the original message.
idstringMessage ID of original message.
referred_productWhatsAppReferredProductUsed for enquiries coming from a Product Detail Page, Single Product Messages, and Multi-Product Message.

WhatsAppReferredProduct object

AttributesTypeDescription
catalog_idstringID for the catalog the item belongs to.
product_retailer_idstringUnique identifier (in the catalog) of the product.

WhatsAppInteractive object

AttributesTypeDescription
typeWhatsAppInteractiveTypeRequired. Interactive message type.
headerWhatsAppInteractiveHeaderRequired only for multi-product messages. Header content displayed on top of a message.
bodyWhatsAppInteractiveBodyRequired. The body of the message. Emojis and markdown are supported.
actionWhatsAppInteractiveActionRequired. Action you want the user to perform after reading the message.
footerWhatsAppInteractiveFooterOptional. The footer of the message. Emojis and markdown are supported.
replyWhatsAppInteractiveReplyAvailable only when message is inbound

WhatsAppInteractiveType object

ValueDescription
listList 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.
buttonReply buttons. Messages including up to 3 buttons. 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.
productSingle product messages
product_listMulti-product messages
button_replyInbound only. Replies of reply buttons

WhatsAppInteractiveHeader object

Header content displayed on top of a message.

AttributesTypeDescription
typeWhatsAppInteractiveHeaderTypeRequired. Define the header type
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.

WhatsAppInteractiveHeaderType object

ValueDescription
textUsed for List Messages, Reply Buttons and Multi-Product Messages
videoUsed for Reply Buttons and Multi-Product Messages
imageUsed for Reply Buttons and Multi-Product Messages
documentUsed for Reply Buttons and Multi-Product Messages

WhatsAppInteractiveBody 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.

WhatsAppInteractiveAction object

AttributesTypeDescription
catalog_idstringRequired for Single Product Messages and Multi-Product Messages. Unique identifier of the Facebook catalog linked to your WhatsApp Business Account. This ID can be retrieved via Commerce Manager.
product_retailer_idstringRequired for Single Product Messages and Multi-Product Messages. Unique identifier of the product in a catalog. This can be retrieved via Commerce Manager.
sectionsarray of WhatsAppInteractiveSectionRequired for List Messages and Multi-Product Messages. The minimum number of sections is 1 and maximum is 10.
buttonstringRequired for List Messages. Button content. It cannot be an empty string and must be unique within the message. Does not allow emojis or markdown. Maximum length: 20 characters.
buttonsWhatsAppInteractiveButtonRequired for Reply Button Messages.

WhatsAppInteractiveButton 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.
image_urlstringFor inbound/fetching messages only. Use this URL to retrieve the image button.

WhatsAppInteractiveSection object

AttributesTypeDescription
titlestringRequired if the message has more than one section. Title of the section. Maximum length: 24 characters.
rowsarray of WhatsAppInteractiveSectionRowRequired for List Messages.
product_itemsarray of WhatsAppInteractiveProductRequired for Multi-Product Messages. There is a minimum of 1 product per section and a maximum of 30 products across all sections.

WhatsAppInteractiveProduct object

AttributesTypeDescription
product_retailer_idstringRequired. Unique identifier of the product in a catalog. This can be retrieved via Commerce Manager.

WhatsAppInteractiveSectionRow object

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

WhatsAppInteractiveFooter 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.

WhatsAppInteractiveReply 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

WhatsAppSticker object

Represents a WhatsApp-specific sticker message, which have the following requirements/limitations:

  • The image format must be image/webp
  • The image size can't be bigger than 100 KB for static stickers and 500 KB for animated stickers
  • The image dimensions must be exactly 512 x 512
  • Animated stickers are supported only for On-Cloud channels
  • Native first party and third party WhatsApp stickers are not supported for outbound messages
AttributesTypeDescription
linkstringRequired. URL of the sticker image. The format must be image/webp and the maximum size is 100 KB.

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 the recipients of the message.
ccArray of EmailRecipientOptional. An array containing the recipients which a copy of the message should be sent to.
bccArray of EmailRecipientOptional. An array containing the recipients which a blind copy of the message should be sent to.
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
addressstringRequired. 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.
WhatsApptransmittedThe message was delivered to the WhatsApp Business Client.
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
Generic message types
ValueDescription
textText message.
imageImage.
videoVideo.
audioAudio message.
fileFile.
locationLocation.
eventConversation event, not a real message and won't visible by your contacts.
richRich content message.
menuMenu message.
buttonsMessage with buttons.
linkLink.
WhatsApp-specific message types

The following message types are supported only by WhatsApp channels.

ValueDescriptionDirection
hsmWhatsApp Template message (Highly Structured Message)Outbound
whatsappStickerWhatsApp sticker message.Inbound/outbound
interactiveWhatsApp interactive message.Outbound
whatsappOrderWhatsApp order message.Inbound
whatsappTextWhatsApp product question message.Inbound
Instagram-specific message types

The following message types are supported only by Instagram channels.

ValueDescription
externalAttachmentUsed for story mentions.
Email-specific message types

The following message types are supported only by Email channels.

ValueDescriptionDirection
emailEmail message.Inbound/outbound
MessageDirection object
ValueDescription
sentA message sent from you to your contacts (outbound message).
receivedA message received by you (inbound message).
FacebookMessage object

Facebook-specific message which provides quick replies, media templates and generic templates.

AttributesTypeDescriptionRequired
textstringText to be sent with the quick reply. Maximum 2000 characters.Required if attachment is not set
attachmentFacebookAttachmentMessage attachment.Required if text is not set
quick_repliesArray of FacebookQuickReplyQuick reply buttons. It supports up to 13 quick repliesNo
FacebookAttachment object

Facebook-specific message attachment.

AttributesTypeDescriptionRequired
typeFacebookAttachmentTypeAttachment type.Yes
payloadFacebookAttachmentPayloadAttachment payloadYes
FacebookAttachmentType object
ValueDescription
imageImage attachment type
audioAudio attachment type
videoVideo attachment type
fileFile attachment type
locationLocation attachment type
fallbackFallback attachment type. For example: a user shares a URL with a Facebook Page, then the attachment is created based on link sharing
templateTemplate attachment type
FacebookAttachmentPayload object

Facebook-specific message attachment payload.

AttributesTypeDescriptionRequired
urlstringAttachment URL.No
is_reusableboolIf true, then the attachment is may be sent to other recipients. The default value is false.No
attachment_idstringFacebook attachment ID.No
template_typeFacebookTemplateTypeTemplate type.Yes
elementsarray of FacebookElementParts of a generic message template. Maximum 10 elements for generic templates (template_type is generic) and it must be exactly 1 for media templates (template_type is media).Yes
image_aspect_ratioFacebookImageAspectRatioImage aspect ratio.For generic templates
FacebookTemplateType object
ValueDescription
mediaStructured template with image or video, and an optional button.
genericStructured template message with image, text and buttons.
FacebookElement object

A Facebook generic template message supports up to 10 elements. At least one additional field must be set along with title.

AttributesTypeDescriptionRequired
media_typeFacebookElementMediaTypeMedia type. It must be empty for generic templates (template_type is generic).For media templates
attachment_idstringAttachment ID of the image or video. Can't be used if media_url is set.No
media_urlstringAttachment URL of the image or video. Can't be used if attachment_id is set.For media templates
buttonsarray of FacebookButtonList of buttons. Maximum of 3 buttons for generic templates (template_type is generic) and maximum 1 button for media templates (template_type is media).No
titlestringTemplate title. Maximum 80 characters.For generic templates
subtitlestringTemplate subtitle. Maximum 80 characters.No
default_actionFacebookButtonThe default action to be executed when the template is clicked.No
image_urlstringThe image URL to display in the template.No
FacebookElementMediaType object
ValueDescription
videoVideo media template
imageImage media template
FacebookButton object
AttributesTypeDescriptionRequired
typeFacebookButtonTypeButton type.Yes
urlstringThe URL which the customer will see when clicking at the button.When type is web_url
titlestringThe text to be displayed in the button. Maximum of 20 characters.When type is postback
payloadstringWhen type is phone_number, it must contain a valid phone number to be called when the button is clicked. When type is postback, it must contain the payload to be sent through FacebookPostback. Maximum of 1000 characters.When type is phone_number or postback
FacebookButtonType object
ValueDescription
web_urlURL button
phone_numberCall button
postbackPostback button
FacebookImageAspectRatio object
ValueDescription
horizontalHorizontal aspect ratio (1.91:1). Default value.
squareSquare aspect ratio (1:1)
FacebookQuickReply object
AttributesTypeDescriptionRequired
content_typeFacebookQuickReplyContentTypeContent type.Yes
titlestringText to be displayed in the quick reply. Maximum 20 characters.When content_type is text
payloadstringPayload to be sent through an inbound message when the quick reply is clicked. Maximum 1000 characters.When content_type is text
image_urlstringImage URL to be displayed in the quick reply. The image must have a minimum of 24px x 24px. Larger images will be cropped and resized.When title is not set
FacebookQuickReplyContentType object
ValueDescription
textText quick reply.
user_phone_numberDisplays a button to allow the recipient to send the phone number associated with their account.
user_emailDisplays a button to allow the recipient to send the email associated with their account.
FacebookPostback object

Facebook-specific inbound-only message type that represents a recipient response to a button/quick reply.

AttributesTypeDescription
titlestringTitle of the button/option clicked.
payloadstringThe payload parameter defined in the button that was clicked.
FacebookReferral object

Facebook-specific inbound-only message type that provides information about how the recipient got into an existing thread via:

AttributesTypeDescription
refstringReference string. Limited to alphanumeric characters, -, _ and =.
sourceFacebookReferralSourceThe source of the referral
typestringReferral type. Currently supports only OPEN_THREAD
ad_idstringID of the advertisement
ads_context_dataFacebookAdsContextDataContextual information about the advertisement
FacebookReferralSource object
ValueDescription
ADSFacebook Messenger conversation advertisement referral source.
SHORTLINKm.me link referral source.
CUSTOMER_CHAT_PLUGINFacebook Chat Plugin referral source.
FacebookAdsContextData object
AttributesTypeDescription
ad_titlestringAdvertisement title.
photo_urlstringURL of the image from the advertisement
video_urlstringThumbnail URL of the video from the advertisement
post_idstringID of the post
product_idstringProduct ID from the advertisement
LineSticker object

The sticker object provides information about a sent or received sticker message through the Line platform.

Notification icon

Due to Line app limitations, we are unable to provide a URL link to the sticker nor display the sticker itself.

AttributesTypeRequired
typeLineStickerTypeYes
packageIdstringYes
stickerIdstringRequired for sticker type standard
keywordsstring(Inbound only) keywords that describe the sticker
textstring(Inbound only) text entered by the user
LineStickerType object
AttributesTypeDescription
standardstringSends a sticker to a user
missionstringSends a mission sticker to a user

Example json for a sending a sticker message via the /v1/send endpoint to a user

curl -X POST "https://conversations.messagebird.com/v1/send" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json" \
-d '{
"to":"U1234567890",
"from":"aa4c8e7cee664341a22ef9bfd9f52477",
"type":"lineSticker",
"content":{
"lineSticker":{
"stickerType":"standard",
"packageId":"446",
"stickerId":"1988"
}
}
}'
WhatsAppCarouselCard object
AttributesTypeDescriptionRequired
card_indexintegerCard index in the carouselYes
componentsarray of MessageComponentComponents of the carousel cardYes

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*For WhatApp Cloud API channels valid mime types listed below.
imageimage/jpeg, image/png5 MB-
stickerimage/webp100 KBThe sticker dimensions must be exactly 512x512 and animated stickers are not supported.
videovideo/mp416 MBOnly H.264 video codec and AAC audio codec is supported. Only videos with a single audio stream are supported.
Notification icon

Valid document MIME types for WhatApp Cloud API:

text/plain, application/pdf, application/vnd.ms-powerpoint, application/msword, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.

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.

SMS

NA.

Twitter

NA.

Google Business Messages

MediaTypesLimit
imagepng, jpg5 MB
Next upContactsv2

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