API Reference

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.

Please contact support in case you need higher limits.

HTTP method	Regular customers		Enterprise customers
	Limit	Burst	Limit	Burst
GET	500	500	500	500
POST	50	250	500	500
PATCH	50	250	500	500
DELETE	50	250	500	500

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

Parameter	Type	Description
errors[].code	integer	An integer that represents the error type.
errors[].description	string	A human-readable description of the error. You can use this to let the user know what they can do about the error.
errors[].parameter	string	The 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

Parameter	Type	Description	Required
type	MessageType	The type of the message content. Defines which field is required inside content.	Yes
content	MessageContent	Content of the message to send. The value of type defines the required fields.	Yes
to	MessageRecipient	A platform-specific identifier of the recipient.	Yes
channelId	string	The unique ID that identifies the channel through which the message should be sent.	Yes
source	object	A JSON-formatted object that can be used to identify the source of the message.	No
reportUrl	string	The URL to deliver status updates for the message. Must use HTTPS.	No
tag	MessageTag	Mark the message with a particular MessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.	No
trackId	string	Useful for grouping messages across conversations. The limit is 36 characters.	No
eventType	string	The type of event being sent. The value of the parameter type must be a event	No
ttl	string	Only 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
replyTo	ReplyTo	Declare that the message is a reply to a previous message	No

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

Code	Description
201	Message accepted and it will be processed asynchronously.
400	Invalid HTTP request. The HTTP response should include details about the error.
401	Unauthorized.
422	The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected 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

Parameter	Type	Description	Required
type	MessageType	The type of the message content. Defines which field is required inside content.	Yes
content	MessageContent	Content of the message to send. The value of type defines the required fields.	Yes
channelId	string	The 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
fallback	Fallback	Required to send a fallback message.	No
source	object	A JSON-formatted object that can be used to identify the source of the message.	No
eventType	string	The type of event being sent. The value of the parameter type must be a event	No
reportUrl	string	The URL for delivering status updates for the message. Must be HTTPS.	No
tag	MessageTag	Mark the message with a particular MessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.	No
trackId	string	Useful for grouping messages across conversations. The limit is 36 characters.	No
ttl	string	Only 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
replyTo	ReplyTo	Declare that the message is a reply to a previous message	No

curl -X POST "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "text",
  "content": {
    "text": "Hello!"},
    "source": {"foo":"var"}
  }'

Response

Parameter	Type	Description
id	string	The unique ID generated by MessageBird that identifies the message.
conversationId	string	The unique ID that identifies the conversation which the message is a part of.
channelId	string	The unique ID that identifies the channel which the message was sent.
platform	Platform	The platform name of the channel which the message was sent.
to	MessageRecipient	The identifier of the recipient in the platform. The value depends on the platform.
from	string	The identifier of the sender in the platform. The value depends on the platform.
direction	MessageDirection	The direction of the message.
status	MessageStatus	The status of the message.
type	MessageType	The type of message content.
content	MessageContent	Content of the message. The type field indicates the field which is populated in this object.
createdDatetime	Datetime	The datetime when the message was created in RFC3339 format.
updatedDatetime	Datetime	The datetime when the message was updated in RFC3339 format.
source	object	A JSON-formatted object that can be used to identify the source of the message.
tag	MessageTag	Mark the message with a particular MessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.
fallback	Fallback	The fallback message, if provided.
ttl	string	Only 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

Code	Description
201	Message accepted and it will be processed asynchronously.
400	Invalid HTTP request. The HTTP response should include details about the error.
404	Conversation not found.
401	Unauthorized.
422	The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected 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

Parameter	Type	Description	Required
to	string	Either a MessageRecipient or the MessageBird contact ID.	Yes
from	string	The channel ID from which the message should be sent.	Yes
type	MessageType	The type of the message content. Defines which field is required inside content.	Yes
content	MessageContent	Content of the message to send. The value of type defines the required fields.	Yes
reportUrl	string	The URL for delivering status updates for the message. Must be HTTPS.	No
fallback	Fallback	Required to send a fallback message.	No
source	object	A JSON-formatted object that can be used to identify the source of the message.
tag	MessageTag	Mark the message with a particular MessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.	No
trackId	string	Useful for grouping messages across conversations. The limit is 36 characters.	No
ttl	string	Only 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
replyTo	ReplyTo	Declare that the message is a reply to a previous message	No

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

Response

Parameter	Type	Description
id	string	An unique ID generated by MessageBird that identifies the message.
status	MessageStatus	The status of the message.
fallback	Fallback	The fallback message, if provided.

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

Response codes

Code	Description
202	Message accepted and it will be processed asynchronously.
400	Invalid HTTP request. The HTTP response should include details about the error.
401	Unauthorized.
422	The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected 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.

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.

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

Create Webhook

Creates a webhook.

POST /v1/webhooks

Request

Parameter	Type	Description	Required
events	Array of WebhookEvents	A list of event names that should trigger this webhook.	Yes
channelId	string	The unique identifier for a MessageBird channel that this webhook is subscribed.	No
url	string	The endpoint URL that requests should be sent to.	Yes
settings	WebhookSettings	The 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

Code	Description
201	Webhook created.
400	Invalid HTTP request. The HTTP response should include details about the error.
401	Unauthorized.
422	The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected 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

Parameter	Type	Description
count	integer	Number of webhooks.
items	array of Webhook	Array of webhook objects.
limit	integer	The number of maximum objects returned on each request.
offset	integer	The number of objects skipped.
totalCount	integer	The 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

Code	Description
200	Ok.
400	Invalid HTTP request. The HTTP response should include details about the error.
401	Unauthorized.
422	The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected 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

Code	Description
200	Ok.
404	Webhook not found.
401	Unauthorized.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected 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

Parameter	Type	Description
events	Array of WebhookEvents	A list of event names that should trigger this webhook.
url	string	The endpoint URL that requests should be sent to.
status	WebhookStatus	The webhook status.
settings	WebhookSettings	The 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

Code	Description
200	Ok.
404	Webhook not found.
401	Unauthorized.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected 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

Code	Description
204	Webhook deleted.
404	Webhook not found.
401	Unauthorized.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected internal server error. Please retry the request with standard exponential backoff.

Handling Webhook Requests

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

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

If your application fails to accept 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.

Conversation Created Event

Attribute	Type	Description
type	WebhookEvents	Event type (conversation.created)
contact	Contact	Contact of the new conversation
conversation	Conversation	New 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

Attribute	Type	Description
type	WebhookEvents	Event type (conversation.updated)
contact	Contact	Contact of the updated conversation
conversation	Conversation	Updated 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

Attribute	Type	Description
type	WebhookEvents	Event type (conversation.deleted)
contact	Contact	Contact of the updated conversation
conversation	Conversation	Updated 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

Attribute	Type	Description
type	WebhookEvents	Event type (message.created)
contact	Contact	Contact that received/sent the message
conversation	Conversation	Conversation which the message was added
message	Message	New 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

Attribute	Type	Description
type	WebhookEvents	Event type (message.updated)
contact	Contact	Contact object
conversation	Conversation	Conversation which the message was updated
message	Message	Updated 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

Parameter	Type	Description	Required
limit	integer	The number of maximum objects to return on each request. The default value is 10 and the maximum is 20.	No
offset	integer	The number of objects to skip from the first. The default value is 10.	No
ids	string	Comma seperated list of conversation IDs to filter. The maximum number of IDs allowed for each request is 20.	No
status	ConversationStatus	Filter 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

Attribute	Type	Description
count	integer	Number of conversations returned.
items	array of Conversation	Array of Conversation objects.
limit	integer	The number of maximum objects returned on each request.
offset	integer	The number of objects skipped.
totalCount	integer	The 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

Code	Description
200	Ok.
400	Invalid HTTP request. The HTTP response should include details about the error.
401	Unauthorized.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected internal server error. Please retry the request with standard exponential backoff.

Get Conversation

Retrieves a specific conversation.

Parameter	Type	Description	Required
id	string	The 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

Code	Description
200	Ok.
401	Unauthorized.
404	Conversation not found.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected internal server error. Please retry the request with standard exponential backoff.

Update Conversation

Updates a specific conversation.

PATCH /v1/conversations/{id}

Request

Parameter	Type	Description	Required
status	ConversationStatus	The 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

Code	Description
200	Ok.
400	Invalid HTTP request. The HTTP response should include details about the error.
401	Unauthorized.
404	Conversation not found.
422	An active conversation already exist.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected 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

Parameter	Type	Description	Required
id	string	The MessageBird contact ID.	Yes
limit	integer	The number of maximum objects to return on each request. The default value is 10 and the maximum is 20.	No
offset	integer	The number of objects to skip from the first. The default value is 10.	No
status	ConversationStatus	Filter the results by a specific conversation status. The default value is all	No

curl -X GET "https://conversations.messagebird.com/v1/conversations/contact/ebf6aceed7ae4375b726e247318d3377"
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Response

Attribute	Type	Description
count	integer	Number of conversations returned.
items	array of string	Array of conversation IDs.
limit	integer	The number of maximum objects returned on each request.
offset	integer	The number of objects skipped.
totalCount	integer	The number of total conversation objects that can be retrieved through pagination.

{
  "offset": 0,
  "limit": 20,
  "count": 2,
  "totalCount": 2,
  "items": [
    "0b7c237df609487c9c41437dab502889",
    "9eaceec9cd244e7a9b374df81aad4349"
  ]
}

Response codes

Code	Description
200	Ok.
400	Invalid HTTP request. The HTTP response should include details about the error.
401	Unauthorized.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected 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

Parameter	Type	Description	Required
id	string	The unique ID that identifies the conversation.	Yes
limit	integer	The number of maximum objects to return on each request. The default value is 10 and maximum is 20.	No
offset	integer	The number of objects skipped.	No
excludePlatforms	List of Platform	Ignore 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

Attribute	Type	Description
count	integer	Number of messages returned.
items	array of Message	An array of message objects.
limit	integer	The number of maximum objects returned on each request.
offset	integer	The number of objects skipped.
totalCount	integer	The 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

Code	Description
200	Ok.
400	Invalid HTTP request. The HTTP response should include details about the error.
401	Unauthorized.
404	Conversation not found.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected 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

Parameter	Type	Description	Required
id	string	The 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

Code	Description
200	Ok.
400	Invalid HTTP request. The HTTP response should include details about the error.
401	Unauthorized.
404	Message not found.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected 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

Parameter	Type	Description	Required
ids	string	Comma separated message IDs. Maximum of 20 messages.	No, if from is provided
from	Datetime	A 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

Attribute	Type	Description
items	array of Message	An 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

Code	Description
200	Ok.
400	Invalid HTTP request. The HTTP response should include details about the error.
401	Unauthorized.
429	Too many concurrent requests. Please retry the request with standard exponential backoff.
499	The client closed the connection.
500	Unexpected internal server error. Please retry the request with standard exponential backoff.

Objects Reference

Conversation object

Attribute	Type	Description
id	string	An unique ID generated by MessageBird that identifies the conversation.
contactId	string	The MessageBird contact ID for the conversation.
contact	Contact	The MessageBird Contact for this conversation.
channels	array of Channel	A 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.
status	ConversationStatus	The status of the conversation.
createdDatetime	Datetime	The date and time when the conversation was created in RFC3339 format.
updatedDatetime	Datetime	The 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.
lastReceivedDatetime	Datetime	The date and time when the most recent message was added to the conversation in RFC3339 format.
lastUsedChannelId	string	An unique ID for the most recently used channel that sent or received a message to the conversation.
lastUsedPlatformId	Platform	The platform name of the channel which most recently sent or received a message in the conversation.
messages	Messages	A 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.

Attribute	Type	Description
id	string	The unique ID generated by the MessageBird platform that identifies this contact.
href	string	The URL of this contact object.
msisdn	string	The phone number of this contact.
firstName	string	The first name of this contact. Where the first name is not known, msisdn will be used as the firstName instead.
lastName	string	The last name of this contact.
customDetails	object	Additional platform specific details about this contact.
createdDatetime	datetime	The datetime when the message was created (in RFC3339 format).
updatedDatetime	datetime	The 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.

Attribute	Type	Description
id	string	The unique ID generated by the MessageBird platform that identifies this channel.
name	string	The name of this channel (configured through the MessageBird Dashboard).
platformId	Platform	The platform name. For example: sms, whatsapp, email, etc..
status	ChannelStatus	The status of the channel.
createdDatetime	datetime	The datetime when the message was created (in RFC3339 format).
updatedDatetime	datetime	The datetime when the message was updated (in RFC3339 format).

ChannelStatus object

Value	Platform	Description
active	All	The channel is active and, therefore, can send and receive messages.
activating	WhatsApp	The channel is activating and it should become active soon.
activation_code_required	WhatsApp	The activation code is necessary to activate the channel.
activation_required	WhatsApp	Activation process is necessary.
activation_failed	WhatsApp	Activation process has failed.
unavailable	WhatsApp	The channel is temporarily unavailable.
not_verified	WhatsApp	The business wasn't verified in Meta, so the channel can't send or receive messages.
inactive	All	The channel is inactive and, therefore, can't send or receive messages.
pending	All	The channel is pending and, therefore, can't send or receive messages.
action_required	All	An action is required to activate the channel.
deleted	All	The channel is deleted and, therefore, cannot be used anymore.

Messages object

Attribute	Type	Description
href	string	A link to the endpoint to retrieve messages of the conversation.
totalCount	integer	The total number of messages that can be retrieved through pagination for the conversation.
lastMessageId	string	The unique ID generated by MessageBird that identifies the latest message.

Webhook object

Attribute	Type	Description
id	string	The unique ID generated by MessageBird that identifies the webhook.
events	Array of WebhookEvents	A list of event names that should trigger this webhook.
channelId	string	The unique identifier for a MessageBird channel that this webhook is subscribed.
messageId	string	The unique message identifier for a message associated to the webhook.
url	string	The endpoint URL that requests should be sent to.
status	WebhookStatus	The webhook status: enabled.
createdDatetime	Datetime	The date and time when the webhook was created (in RFC3339 format).
updatedDatetime	Datetime	The date and time when the webhook was updated (in RFC3339 format).
settings	WebhookSettings	The webhook extra settings.

WebhookEvents object

Value	Description
conversation.created	A new conversation has been created.
conversation.updated	A conversation has been updated with a new status.
conversation.deleted	A conversation has been deleted.
message.created	A new message has been created. Triggered for both sent and received messages.
message.updated	A message has been updated with a new status.

WebhookStatus object

Value	Description
enabled	The webhook is enabled, therefore events will be delivered.
disabled	The webhook is disabled, therefore events won't be delivered.

WebhookSettings object

Attribute	Type	Description
settings.expected_http_code	string	The expected HTTP status code mask (like: 2xx, 200 and 201).
settings.headers	hash	Custom HTTP headers for the outgoing request (max length: 1024).
settings.username	string	Basic auth username (max length: 255).
settings.password	string	Basic auth password (max length: 255).
settings.query_params	string	The query parameters (max length: 2048).
settings.retry	integer	The number of maximum retries (between 0-10).
settings.timeout	integer	The 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.

Attribute	Type	Description
id	string	The unique ID generated by the MessageBird platform that identifies this message.
conversationId	string	The unique ID that identifies the conversation that this message is a part of.
channelId	string	The unique ID that identifies the channel that the message was sent or received on.
platform	Platform	The platform name of the channel which the message was sent or received.
to	MessageRecipient	The unique ID that identifies the message recepient. The value depends on platform.
from	string	The unique ID that identifies the message sender. The value depends on platform.
direction	MessageDirection	The direction of the message.
status	MessageStatus	The status of the message.
type	MessageType	The type of the message content.
content	MessageContent	Content of the message. The type field indicates the fields that will be populated in this object.
createdDatetime	datetime	The datetime when the message was created (in RFC3339 format).
updatedDatetime	datetime	The datetime when the message was updated (in RFC3339 format).
source	object	A JSON-formatted object that can be used to identify the source of the message.
tag	MessageTag	MessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.
ttl	string	Only 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.
referral	MessageReferral	Only supported by WhatsApp. Contains information about from where the recipient came from.
replyTo	ReplyTo	Declare that the message is a reply to a previous message

MessageReferral object

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

Only supported by WhatsApp at the moment.

Attribute	Type	Description
whatsapp	WhatsAppReferral	Contains information about the advertisement or Facebook post which was clicked by the recipient.

WhatsAppReferral object

Attribute	Type	Description
headline	string	Title of the advertisement or Facebook post that generated the message.
body	string	Body of the advertisement or Facebook post that generated the message.
source	WhatsAppReferralSource	Object that contains information about the advertisement or Facebook post.
media	WhatsAppReferralMedia	Object that contains information about the media used in the advertisement or Facebook post.

WhatsAppReferralSource object

Attribute	Type	Description
type	WhatsAppReferralSourceType	Referral source type
url	string	URL of the advertisement or Facebook post.
id	string	Facebook ID of the advertisement or Facebook post.

WhatsAppReferralMedia object

Attribute	Type	Description
type	WhatsAppReferralMediaType	Referral media type.
url	string	Media URL.

WhatsAppReferralSourceType object

Value	Description
ad	Advertisement
post	Facebook 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

Attribute	Type	Description	Platforms
text	string	Required for type text. The plain-text content of the message.	Multiple
image	Media	Required for type image.	Multiple
video	Media	Required for type video.	Multiple
audio	Media	Required for type audio.	Multiple
file	Media	Required for type file.	Multiple
location	Location	Required for type location.	Multiple
buttons	Buttons	Required for type buttons.	Multiple
hsm	MessageHSM	Required for type hsm.	WhatsApp
interactive	WhatsAppInteractive	Required for type interactive.	WhatsApp
email	Email	Required for type email.	Email
externalAttachments	array of Media	Used for story mentions.	Instagram
disableUrlPreview	bool	Optional 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
whatsappSticker	WhatsAppSticker	WhatsApp sticker message.	WhatsApp
whatsappOrder	WhatsAppOrder	Inbound WhatsApp order message.	WhatsApp
whatsappText	WhatsAppText	Inbound WhatsApp text message. Used for questions about products.	WhatsApp
facebookQuickReply	FacebookMessage	Facebook-specific message.	Facebook
facebookMediaTemplate	FacebookMessage	Facebook-specific message.	Facebook
facebookGenericTemplate	FacebookMessage	Facebook-specific message.	Facebook
facebookReferral	FacebookReferral	Facebook-specific referral message.	Facebook
lineSticker	LineSticker	Line-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.

Platform	Identifier
SMS	Phone number
WhatsApp	Phone number
Facebook	Channel-specific
Telegram	Platform-specific
LINE	Channel-specific
WeChat	Platform-specific
Email	E-mail address
Twitter	Platform-specific
Viber	Phone number
Livechat	Channel-specific
Google Business Messages	Channel-specific
Instagram	Channel-specific

Fallback object

Attribute	Type	Description
from	string	The ID that identifies the channel over which the message should be sent.
after	string	This 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.

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.

Attribute	Type	Description
url	string	The 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.
caption	string	The caption associated with the media file

Location object

Attribute	Type	Description
latitude	float	The latitude coordinates of the location.
longitude	float	The 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.

Attribute	Type	Description
text	string	Text to be sent with the quick replies. Can be a maximum of 300 characters
items	Array of ButtonItem	The 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.

Platform	Max buttons
Line	13
Google Business Messaging	13
OCW Livechat	20

ButtonItem object

Attributes	Type	Description	Required
text	string	Text shown on the button. Can be a maximum 255 characters.	Yes
action	Button action	Action 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.

Value	Type	Required
type	ButtonItemActionType	Yes
uri	string	Optional. Required when type is set to uri.

ButtonItemActionType object

Value	Description
text	Sends a text quick reply.
location	Open the location screen.
camera	Open the users camera.
camera_roll	Open the users camera roll.
uri	Open 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.

Attribute	Type	Description
namespace	string	Required. WhatsApp namespace for your account. You will receive this value when setting up your WhatsApp account.
templateName	string	Required. Template name.
language	HSMLanguage	The message language.
params	array of HSMLocalizableParameters	Parameters for regular templates.
components	array of MessageComponent	Parameters 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.

Attribute	Type	Description
policy	string	Default value: deterministic. The fallback value was deprecated in January 2020.
code	string	Required. 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.

Attribute	Type	Description
default	string	Required. Default value of the parameter, it is used when localization fails. The only field needed when specifying parameter value that doesn't require localization.
currency	object	Can 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"}
dateTime	string	Can 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.

Attribute	Type	Description
type	string	Required. Value could be set to header, body or button.
sub_type	string	Optional. Required when type is set to button. Supported values are: quick_reply and url
index	integer	Optional. Required when type is set to button. You can have up to 3 buttons using index values of 0-2.
parameters	array of MessageParam	Required. Parameters to be used in the template message.

MessageParam object

Component parameters are the values that are replaced in the template message. The possible types are text, payload, image, document, currency, 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)

Attribute	Type	Description
type	TemplateMediaType	Required. Defines the parameter type.
text	string	Required for type text
payload	string	Required for type payload
currency	HSMCurrency	Required for type currency. Defines the currency details.
dateTime	string	Required for type date_time Can be present only if currency object is not present. RFC3339 representation of the date and time.
document	MediaMessageParam	Required for type document
image	MediaMessageParam	Required for type image
video	MediaMessageParam	Required for type video

MediaMessageParam object

Attribute	Type	Description
url	string	The URL of the remote media file.

TemplateMediaType object

Value	Description
image	Image. It can be used when the component type (hsm.components.type) is header
document	Document. It can be used when the component type (hsm.components.type) is header
video	Video. It can be used when the component type (hsm.components.type) is header
text	Text. It can be used when the component type (hsm.components.type) is button
currency	Currency
date_time	Date/time
payload	Payload. It can be used when the component type (hsm.components.type) is button

HSMCurrency object

Attribute	Type	Description
currencyCode	string	Currency code as defined in ISO 4217
amount	int	Amount 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 Tag	Facebook Message Tag	Platform-specific Description
event.update	CONFIRMED_EVENT_UPDATE	Send the user reminders or updates for an event they have registered for (e.g., RSVP'ed, purchased tickets).
purchase.update	POST_PURCHASE_UPDATE	Notify the user of an update on a recent purchase.
account.update	ACCOUNT_UPDATE	Notify the user of a non-recurring change to their application or account.
human_agent	HUMAN_AGENT (Closed BETA) Apply for access	Allows 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.

Attribute	Type	Description
id	string	The 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.

Platform	Receive replies	Send replies
Whatsapp (on premise)	Yes	No
Whatsapp (cloud hosted)	Yes	Yes
Telegram	Yes	Yes

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.

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

Attributes	Type	Description
catalog_id	string	ID of the catalog that contains the products listed under product_items sections.
product_items	array of WhatsAppOrderProduct	Product items
text	string	Text message sent along with the order.

WhatsAppOrderProduct object

Attributes	Type	Description
product_retailer_id	string	Unique identifier (in the catalog) of the product.
quantity	int	Number of items purchased.
item_price	string	Unitary price of the items.
currency	string	Currency of the price.

WhatsAppText object

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

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

Attributes	Type	Description
text	WhatsAppTextBody	Text message
context	WhatsAppContext	Message context

WhatsAppTextBody object

Attributes	Type	Description
body	string	Message body

WhatsAppContext object

Attributes	Type	Description
from	string	WhatsApp ID of the sender of the original message.
id	string	Message ID of original message.
referred_product	WhatsAppReferredProduct	Used for enquiries coming from a Product Detail Page, Single Product Messages, and Multi-Product Message.

WhatsAppReferredProduct object

Attributes	Type	Description
catalog_id	string	ID for the catalog the item belongs to.
product_retailer_id	string	Unique identifier (in the catalog) of the product.

WhatsAppInteractive object

Attributes	Type	Description
type	WhatsAppInteractiveType	Required. Interactive message type.
header	WhatsAppInteractiveHeader	Required only for multi-product messages. Header content displayed on top of a message.
body	WhatsAppInteractiveBody	Required. The body of the message. Emojis and markdown are supported.
action	WhatsAppInteractiveAction	Required. Action you want the user to perform after reading the message.
footer	WhatsAppInteractiveFooter	Optional. The footer of the message. Emojis and markdown are supported.
reply	WhatsAppInteractiveReply	Available only when message is inbound

WhatsAppInteractiveType object

Value	Description
list	List messages. Messages including a menu of up to 10 options. This type of message offers a simpler and more consistent way for users to make a selection when interacting with a business.
button	Reply 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.
product	Single product messages
product_list	Multi-product messages
button_reply	Inbound only. Replies of reply buttons

WhatsAppInteractiveHeader object

Header content displayed on top of a message.

Attributes	Type	Description
type	WhatsAppInteractiveHeaderType	Required. Define the header type
text	string	Required if type is set to text. Text for the header. Formatting allows emojis, but not markdown. Maximum length: 60 characters.
video	Media	Required if type is set to video.
image	Media	Required if type is set to image.
document	Media	Required if type is set to document.

WhatsAppInteractiveHeaderType object

Value	Description
text	Used for List Messages, Reply Buttons and Multi-Product Messages
video	Used for Reply Buttons and Multi-Product Messages
image	Used for Reply Buttons and Multi-Product Messages
document	Used for Reply Buttons and Multi-Product Messages

WhatsAppInteractiveBody object

The body of the message.

Attributes	Type	Description
text	string	Required. The body content of the message. Emojis and markdown are supported. Links are supported. Maximum length: 1024 characters.

WhatsAppInteractiveAction object

Attributes	Type	Description
catalog_id	string	Required 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_id	string	Required for Single Product Messages and Multi-Product Messages. Unique identifier of the product in a catalog. This can be retrieved via Commerce Manager.
sections	array of WhatsAppInteractiveSection	Required for List Messages and Multi-Product Messages. The minimum number of sections is 1 and maximum is 10.
button	string	Required 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.
buttons	WhatsAppInteractiveButton	Required for Reply Button Messages.

WhatsAppInteractiveButton object

Attributes	Type	Description
id	string	Required. Must be unique within buttons. Maximum length: 256 characters.
type	string	Required. Only supported type reply for Reply Button Messages. Maximum length: 20 characters.
title	string	Required. Must be unique within buttons. Maximum length: 20 characters.
image_url	string	For inbound/fetching messages only. Use this URL to retrieve the image button.

WhatsAppInteractiveSection object

Attributes	Type	Description
title	string	Required if the message has more than one section. Title of the section. Maximum length: 24 characters.
rows	array of WhatsAppInteractiveSectionRow	Required for List Messages.
product_items	array of WhatsAppInteractiveProduct	Required for Multi-Product Messages. There is a minimum of 1 product per section and a maximum of 30 products across all sections.

WhatsAppInteractiveProduct object

Attributes	Type	Description
product_retailer_id	string	Required. Unique identifier of the product in a catalog. This can be retrieved via Commerce Manager.

WhatsAppInteractiveSectionRow object

Attributes	Type	Description
id	string	Required. It must be unique within rows. Maximum length: 200 characters.
title	string	Required. Row title text. Maximum length: 24 characters.
description	string	Optional. Maximum length: 72 characters.

WhatsAppInteractiveFooter object

The footer of the message.

Attributes	Type	Description
text	string	Required. 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.

Attributes	Type	Description
id	string	Required. The unique id of button reply or list message reply
text	string	Required. The text content of reply or list message reply
description	string	Optional. 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
The image dimensions must be exactly 512 x 512
Animated stickers are not supported at the moment
Native first party and third party WhatsApp stickers are not supported for outbound messages

Attributes	Type	Description
link	string	Required. 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.

Attributes	Type	Description
id	string	An unique random ID for this message on the MessageBird platform, returned upon acceptance of the message.
to	Array of EmailRecipient	Required. An array containing the recipients of the message.
cc	Array of EmailRecipient	Optional. An array containing the recipients which a copy of the message should be sent to.
bcc	Array of EmailRecipient	Optional. An array containing the recipients which a blind copy of the message should be sent to.
from	EmailRecipient	Required. 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.
subject	string	Required. This will be displayed as the subject in the message, expected in the UTF-8 charset without RFC2047 encoding.
content	EmailContent	Required. HTML or text content for the email. At least one type of content is required.
replyTo	string	Email address used to compose the email's "Reply-To" header.
returnPath	string	Email address used to compose the email's "Return-Path" header. Must match your sending domain.
headers	object	Object containing custom headers other than Subject, From, To, and Reply-To. These will be sent along with your message.
tracking	EmailTracking	Optional. Allows you to set tracking options.
reportUrl	string	The URL for delivery of status reports for the message. Must use https.
performSubstitutions	bool	Perform substitutions of variables inside the content or headers of your email (Default: true).
attachments	array of EmailAttachment	Optional. List of files attached to a message.
inlineImages	array of EmailInlineImage	Optional. 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.

Attributes	Type	Description
html	string	HTML content of the message, expected in UTF-8.
text	string	Plain 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.

Attributes	Type	Description	Example
address	string	Required. Valid email address	demo@messagebird.com
name	string	Name attached to the email address, this appears in the To field in a users email client	Jane Doe
variables	object	List of variables used for placeholders inside the content or headers of your email	{"firstname": "John", "lastname": "Doe"}

EmailTracking object

Attributes	Type	Description
open	bool	Adds a tracking pixel to handle message.opened events. (Default: true)
click	bool	Adds 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.

Attributes	Type	Description
id	string	Attachment ID.
name	string	File name.
type	string	File type.
URL	string	URL of the file to be attached to the message.
length	integer	File 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>">

Attributes	Type	Description
id	string	Inline image ID.
name	string	File name.
type	string	File type.
URL	string	URL of the file.
length	integer	File size in bytes.
contentId	string	ID used in the content of the message.

ConversationStatus object

Value	Description
active	New inbound or outbound messages will be added to the conversation.
archived	The conversation is archived, therefore, it won't receive any new messages.
all	Can be used when listing conversations for fetching active and archived conversations.

MessageStatus object

Platform	Value	Description
All	accepted	The message is accepted and it will be processed asynchronously.
All	pending	The message is pending to be delivered.
All	sent	The message is sent.
All	rejected	The message is rejected. The reason should be available in the message details.
All	failed	The message failed to be delivered.
All	read	The message was read by the recipient.
All	received	Inbound message.
All	deleted	The message is deleted.
All	unknown	The message status is temporarily unknown.
WhatsApp	transmitted	The message was delivered to the WhatsApp Business Client.
SMS	delivery_failed	The message failed to be delivered.
SMS	buffered	The message is enqueued to be delivered.
SMS	expired	The message was not delivered in time.
Email	clicked	The recipient clicked in a tracked link in the message.
Email	opened	The recipient opened the message.
Email	bounce	The message was permanently rejected by the recipient's email server.
Email	spam_complaint	The message was marked as spam by the recipient.
Email	out_of_bounded	The recipient's email server accepted the message, however, later it reported the message was not delivered.
Email	delayed	The recipient's email server temporarily rejected the message (it will be retried).
Email	list_unsubscribe	The recipient clicked the 'Unsubscribe' button in their email client.
Email	dispatched	The message, which was addressed to multiple recipients, was delivered to Sparkpost (email provider).

MessageType object

Generic message types

Value	Description
text	Text message.
image	Image.
video	Video.
audio	Audio message.
file	File.
location	Location.
event	Conversation event, not a real message and won't visible by your contacts.
rich	Rich content message.
menu	Menu message.
buttons	Message with buttons.
link	Link.

WhatsApp-specific message types

The following message types are supported only by WhatsApp channels.

Value	Description	Direction
hsm	WhatsApp Template message (Highly Structured Message)	Outbound
whatsappSticker	WhatsApp sticker message.	Inbound/outbound
interactive	WhatsApp interactive message.	Outbound
whatsappOrder	WhatsApp order message.	Inbound
whatsappText	WhatsApp product question message.	Inbound

Instagram-specific message types

The following message types are supported only by Instagram channels.

Value	Description
externalAttachment	Used for story mentions.

Email-specific message types

The following message types are supported only by Email channels.

Value	Description	Direction
email	Email message.	Inbound/outbound

MessageDirection object

Value	Description
sent	A message sent from you to your contacts (outbound message).
received	A message received by you (inbound message).

FacebookMessage object

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

Attributes	Type	Description	Required
text	string	Text to be sent with the quick reply. Maximum 2000 characters.	Required if attachment is not set
attachment	FacebookAttachment	Message attachment.	Required if text is not set
quick_replies	Array of FacebookQuickReply	Quick reply buttons. It supports up to 13 quick replies	No

FacebookAttachment object

Facebook-specific message attachment.

Attributes	Type	Description	Required
type	FacebookAttachmentType	Attachment type.	Yes
payload	FacebookAttachmentPayload	Attachment payload	Yes

FacebookAttachmentType object

Value	Description
image	Image attachment type
audio	Audio attachment type
video	Video attachment type
file	File attachment type
location	Location attachment type
fallback	Fallback attachment type. For example: a user shares a URL with a Facebook Page, then the attachment is created based on link sharing
template	Template attachment type

FacebookAttachmentPayload object

Facebook-specific message attachment payload.

Attributes	Type	Description	Required
url	string	Attachment URL.	No
is_reusable	bool	If true, then the attachment is may be sent to other recipients. The default value is false.	No
attachment_id	string	Facebook attachment ID.	No
template_type	FacebookTemplateType	Template type.	Yes
elements	array of FacebookElement	Parts 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_ratio	FacebookImageAspectRatio	Image aspect ratio.	For generic templates

FacebookTemplateType object

Value	Description
media	Structured template with image or video, and an optional button.
generic	Structured 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.

Attributes	Type	Description	Required
media_type	FacebookElementMediaType	Media type. It must be empty for generic templates (template_type is generic).	For media templates
attachment_id	string	Attachment ID of the image or video. Can't be used if media_url is set.	No
media_url	string	Attachment URL of the image or video. Can't be used if attachment_id is set.	For media templates
buttons	array of FacebookButton	List 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
title	string	Template title. Maximum 80 characters.	For generic templates
subtitle	string	Template subtitle. Maximum 80 characters.	No
default_action	FacebookButton	The default action to be executed when the template is clicked.	No
image_url	string	The image URL to display in the template.	No

FacebookElementMediaType object

Value	Description
video	Video media template
image	Image media template

FacebookButton object

Attributes	Type	Description	Required
type	FacebookButtonType	Button type.	Yes
url	string	The URL which the customer will see when clicking at the button.	When type is web_url
title	string	The text to be displayed in the button. Maximum of 20 characters.	When type is postback
payload	string	When 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

Value	Description
web_url	URL button
phone_number	Call button
postback	Postback button

FacebookImageAspectRatio object

Value	Description
horizontal	Horizontal aspect ratio (1.91:1). Default value.
square	Square aspect ratio (1:1)

FacebookQuickReply object

Attributes	Type	Description	Required
content_type	FacebookQuickReplyContentType	Content type.	Yes
title	string	Text to be displayed in the quick reply. Maximum 20 characters.	When content_type is text
payload	string	Payload to be sent through an inbound message when the quick reply is clicked. Maximum 1000 characters.	When content_type is text
image_url	string	Image 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

Value	Description
text	Text quick reply.
user_phone_number	Displays a button to allow the recipient to send the phone number associated with their account.
user_email	Displays 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.

Attributes	Type	Description
title	string	Title of the button/option clicked.
payload	string	The 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:

An m.me link with a referral parameter
Clicking on a Facebook Messenger conversation advertisement
Starting or resuming a conversation thread from the Facebook Chat Plugin

Attributes	Type	Description
ref	string	Reference string. Limited to alphanumeric characters, -, _ and =.
source	FacebookReferralSource	The source of the referral
type	string	Referral type. Currently supports only OPEN_THREAD
ad_id	string	ID of the advertisement
ads_context_data	FacebookAdsContextData	Contextual information about the advertisement

FacebookReferralSource object

Value	Description
ADS	Facebook Messenger conversation advertisement referral source.
SHORTLINK	m.me link referral source.
CUSTOMER_CHAT_PLUGIN	Facebook Chat Plugin referral source.

FacebookAdsContextData object

Attributes	Type	Description
ad_title	string	Advertisement title.
photo_url	string	URL of the image from the advertisement
video_url	string	Thumbnail URL of the video from the advertisement
post_id	string	ID of the post
product_id	string	Product ID from the advertisement

LineSticker object

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

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

Attributes	Type	Required
type	LineStickerType	Yes
packageId	string	Yes
stickerId	string	Required for sticker type standard
keywords	string	(Inbound only) keywords that describe the sticker
text	string	(Inbound only) text entered by the user

LineStickerType object

Attributes	Type	Description
standard	string	Sends a sticker to a user
mission	string	Sends 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"
      }
    }
  }'

Platforms

Supported media types per platform

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

Media	Types	Limit	Notes
audio	audio/aac, audio/mp4, audio/mpeg, audio/amr, audio/ogg	16 MB	Only opus codecs, base audio/ogg is not supported
document	Any valid MIME-type.*	100 MB	*For WhatApp Cloud API channels valid mime types listed below.
image	image/jpeg, image/png	5 MB	-
sticker	image/webp	100 KB	The sticker dimensions must be exactly 512x512 and animated stickers are not supported.
video	video/mp4	16 MB	Only H.264 video codec and AAC audio codec is supported. Only videos with a single audio stream are supported.

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

Media	Types	Limit
image	jpg, gif, png, ico, bmp	8 MB

Facebook

Media	Types	Limit	Notes
image	png, jpeg	25 MB	The maximum resolution for images is 85 Megapixel.
video	mp4	25 MB	-
audio	mp3, wav, ogg	25 MB	-
file	csv, pdf, ...	25 MB	-

Media	Types	Limit
image	png, jpg	max 10 MB for multipart form upload or 5 MB if posted as URL
video	mp4	max 50 MB for multipart form upload or 5 MB if posted as URL
audio	mp3, ogg	max 50 MB for multipart form upload or 5 MB if posted as URL
file	pdf	max 50 MB for multipart form upload or 5 MB if posted as URL

LINE

Media	Types	Limit
audio	m4a	200 MB
video	mp4	200 MB
image	jpeg, png	10 MB

WeChat

Media	Types	Limit
audio	mp3, amr	2 MB
video	mp4	10 MB
image	gif, png and jpg	1 MB

Viber

Media	Types	Limit
image	png, jpg	50 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

Media	Types	Limit
image	png, jpg	5 MB

Is this page useful?

Next upIntegrations

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