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 are limited to 50 RPS with bursts of 250 RPS.

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	250	500
PATCH	50	250	250	500
DELETE	50	250	250	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 the messages, they are all processed asynchronously, which means, Conversations API will accept your message and process it later, and, because of that, it's important to have webhooks for receiving the status updates about the messages you send.

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

Start Conversation

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

POST /conversations/start

Request

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

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

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.

{
  "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

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 the request 200 times, or for more than 12 hours, your webhook will be automatically disabled and must be re-enabled via the Update method. Any successful response from your application will reset the counter.

Conversation Created Event

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

Conversation Updated Event

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

Message Created Event

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

Message Updated Event

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

Status update per message

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

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

Conversations

List Conversations

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

GET /v1/conversations

Request

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	Description
active	The channel is active and, therefore, can send and receive messages.
deleted	The channel is deleted and, therefore, cannot be used anymore.
unavailable	The channel is currently unavailable.

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

MessageContent object

Attribute	Type	Description
content.text	string	Required for type text. The plain-text content of the message.
content.image	Media	Required for type image.
content.video	Media	Required for type video.
content.audio	Media	Required for type audio.
content.file	Media	Required for type file.
content.location	Location	Required for type location.
content.hsm	MessageHSM	Required for type hsm. Available only for WhatsApp.
content.interactive	MessageInteractive	Required for type interactive. Available only for WhatsApp.
content.email	Email	Required for type email. Available only for Email channels.
content.externalAttachments	array of Media	Used for story mentions. Available only for Instagram channels.
content.disableUrlPreview	bool	Optional field for type text. When set to true, conversations will try to disable previews for urls in your text messages. Only supported by Whatsapp. Default value is false

MessageRecipient object

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

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

The following table displays the identifiers for every supported platform.

Platform	Identifier
SMS	Phone number
WhatsApp	Phone number
Facebook	Channel-specific
Telegram	Platform-specific
LINE	Channel-specific
WeChat	Platform-specific
Email	E-mail address
Apple Business Chat	Channel-specific
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.

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.

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 or body.
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 and dateTime.

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

Header: image or document
Body : text, currency, datetime
Button: text, payload (maximum 3 buttons are only possible)

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	Media	Required for type document
image	Media	Required for type image

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

MessageInteractive object

The following messages are considered interactive:

List Messages: Messages including a menu of up to 10 options. This type of message offers a simpler and more consistent way for users to make a selection when interacting with a business.
Reply Buttons: Messages including up to 3 options —each option is a button. This type of message offers a quicker way for users to make a selection from a menu when interacting with a business. Reply buttons have the same user experience as interactive templates with buttons.

Attributes	Type	Description
type	string	Required. Supported values: list, button and list_reply, button_reply when message is inbound
header	MessageInteractiveHeader	Optional. Header content displayed on top of a message.
body	MessageInteractiveBody	Required. The body of the message. Emojis and markdown are supported.
action	MessageInteractiveAction	Required. Action you want the user to perform after reading the message.
footer	MessageInteractiveFooter	Optional. The footer of the message. Emojis and markdown are supported.
reply	MessageInteractiveReply	Available only when message is inbound

MessageInteractiveHeader object

Header content displayed on top of a message.

Attributes	Type	Description
type	string	Required. The header type you would like to use. Supported values are: text: Used for List Messages and Reply Buttons., video: Used for Reply Buttons. , image: Used for Reply Buttons., document: Used for Reply Buttons.
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.

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

MessageInteractiveAction object

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

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

MessageInteractiveButton object

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.

MessageInteractiveSection object

Attributes	Type	Description
title	string	Required. if the message has more than one section. Maximum length: 24 characters.
rows	array of MessageInteractiveSectionRow	Required. contain list of rows for list messages.

MessageInteractiveSectionRow object

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

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

MessageInteractiveReply 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

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 of all the recipients of the message.
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
email	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.
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

Value	Description
text	Text message.
image	Image.
video	Video.
audio	Audio message.
file	File.
location	Location.
hsm	WhatsApp Template message (Highly Structured Message)
event	Conversation event, not a real message and won't visible by your contacts.
email	Email message.
rich	Rich content message.
menu	Menu message.
buttons	Message with buttons.
link	Link.
externalAttachment	Used for story mentions. Currently available only for Instagram.

MessageDirection object

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

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	-
image	image/jpeg, image/png	5 MB	-
sticker	image/webp	100 KB	-
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.

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.

Apple

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

SMS

NA.

Twitter

NA.

Google Business Messages

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