Conversations API beta
The MessageBird Conversations API is an omnichannel messaging solution to unify sent and received messages across all of your chat channels in one conversation thread. Conversations is the view of all messages between the provider and customer across any configured channels-—SMS, WhatsApp, WeChat, Messenger, Telegram, and LINE.
The Conversations API uses HTTP verbs and a RESTful endpoint 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.
Authorization
You'll need to set an access key to authenticate yourself. You can create, manage, and retrieve your API keys (both test and live) from the MessageBird Dashboard.
To provide the access key, set the Authorization header in the form of AccessKey {accessKey}.
Formats and Headers
All API responses are in JSON. You're required to send the Accept 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.
Errors
MessageBird uses standard HTTP status codes to indicate success or failure of an API request. Codes in the 2xx range indicate that a request was successfully processed and codes in the 4xx range indicate that there was an error that resulted from the information sent (e.g. authentication, no balance or a missing or wrong parameter).
In the case of an error, the body of the response includes a JSON-formatted response that tells you exactly what is wrong.
MessageBird uses standard HTTP status codes to indicate success or failure of an API request:
- Codes in the 2xx range indicate that a request was processed successfully
- The 4xx range indicates that there was an error - for example, due to authentication, no balance, or a missing or wrong parameter. Don't worry, the body of the response includes a JSON-formatted response that tells you exactly what is wrong. If you're stuck, feel free to contact support; we're happy to help you out.
- A 5xx status code indicates that something went wrong on our end.
Attributes
| Attribute | 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. |
Platforms
Conversations are supported for SMS, WhatsApp, Facebook Messenger, Telegram, LINE, and WeChat. Before using the Conversations API, head over to the MessageBird quickstarts for step-by-step guides on how to easily install and configure your channels via the MessageBird Dashboard.
Send message
The send endpoint allows you to send messages to users over any communication platform supported by Programmable Conversations - SMS, WhatsApp, WeChat, Messenger, Telegram, and LINE. You can send a message to a user with the ID of your MessageBird channel, and the identifier of the user on this channel. An identifier is platform-specific, for example, WhatsApp and SMS channels require the phone number of the recipient.
All sent messages are available in the message history via Conversations. You can also subscribe to Webhooks to receive notifications of events and status updates for sent messages.
The send definition sends a new message to a channel-specific user identifier (e.g. phone number). If an active conversation already exists for the recipient, this conversation will be resumed, if it doesn't exist, a new one will be created. All messages sent to a single contact will be added to the same conversation, regardless of the channel the message is sent over.
Parameters
| Parameter | Type | Description |
|---|---|---|
| to | string | Either a channel-specific identifier for the receiver (e.g. MSISDN for SMS or WhatsApp channels), or the ID of a MessageBird Contact. |
| from | string | The ID that identifies the channel over which the message should be sent. |
| type | string | The type of the message content being posted. |
| content | Content | Content of the message. The value of type defines the required fields. |
| reportUrl | string | The URL for delivery of status reports for the message. Must be HTTPS. |
| fallback | Fallback | Parameters required to send a Fallback message if the primary delivery fails. |
| source | object | The source of the response/action that sent the message. An example of the source form: {"agentId": "abc123", "userId": [1,2,3], "botId": 1234567890} |
Example request
curl -X "POST" "https://conversations.messagebird.com/v1/send" \-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \--data '{"to":"+31612345678","from":"619747f69cf940a98fb443140ce9aed2","type":"text","content":{"text":"Hello!"},"reportUrl":"https://example.com/reports","source": {"foo": "bar"}}'
Response
| Attribute | Type | Description |
|---|---|---|
| id | string | A unique ID generated by the MessageBird platform that identifies this message. |
| status | string | The status of the message. It will be initially set to accepted. |
| fallback | Object | An object of the form {"id": <uuid>}. Will be present only if a fallback was passed in your request. |
Status Reports
If the reportUrl parameter is provided in your request, status reports will be sent to your platform through a POST request to the supplied URL. The requests contain information about the status of the message that you've sent through the send endpoint, also in the event of a delivery failure, the payload will contain the reason for the error.
Fallback Messages
The Fallback parameter allows you to configure 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 so that if the customer is not a WhatsApp user or doesn't have a mobile data connection, the message is resent 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.
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. |
Example request
curl -X "POST" "https://conversations.messagebird.com/v1/send" \-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \--data '{"to":"+31612345678","from":"619747f69cf940a98fb443140ce9aed2","type":"text","content":{"text":"Hello!"},"reportUrl":"https://example.com/reports""fallback": {"from": "2ecea8ee6c564bb4ab15929c44527687""after": "5m"}}'
Example response
{"id": "2e15efafec384e1c82e9842075e87beb","status": "accepted""fallback": {"id": "a5a66361dc0b4e5d8d2da249753fa8b5",}}
Conversations
A Conversation is the view of all messages between you and a customer across any of your configured channels:
- Messages from multiple channels are collected and displayed in a single conversation.
- When the first message is sent or received from a user, a conversation is automatically created for them.
- A conversation status can be active or archived, but only one active conversation exists for each customer at a time.
- Archiving can be used to end a conversation so that the next time that the customer reaches out, a new conversation will be started. This is especially helpful for support use cases where conversations need to be opened and closed, rather than merely resumed.
The Conversation Object
| Attribute | Type | Description |
|---|---|---|
| id | string | A unique ID generated by the MessageBird platform that identifies this 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 | string | The status of the conversation. Either active or archived. |
| messages | MessagesCount | A link to the messages of this conversation. See below for definition. |
| createdDatetime | datetime | The date and time when this conversation was first created in RFC3339 format. |
| updatedDatetime | datetime | The date and time when this conversation was most recently updated in RFC3339 format. This applies only to changes of the Conversation object itself, not messages, i.e. currently just status changes. |
| lastReceivedDatetime | datetime | The date and time when the most recent message was added to this conversation in RFC3339 format. |
| lastUsedChannelId | string | A unique ID for the most recently used channel that sent or received a message in this conversation. |
The 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 endpoint.
| 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). |
The Channel Object
The Channels represent a platform from which messages can be sent and received; a conversation can take place over multiple channels simultaneously. You can configure your Channels via the Channels Overview in the MessageBird Dashboard; if you need some help, check out our step-by-step quickstarts for installing SMS, WhatsApp, Facebook, Email, and WeChat.
| 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 | string | A unique identifier for the platform that is used by this channel, for example: sms, Whatsapp or messenger. |
| status | string | The status of this channel. Only active channels can be used for messaging. Can be one of inactive, active, pending, activation_required, activation_code_required, activating, and deleted. |
| createdDatetime | datetime | The datetime when the message was created (in RFC3339 format). |
| updatedDatetime | datetime | The datetime when the message was updated (in RFC3339 format). |
MessagesCount
| Attribute | Type | Description |
|---|---|---|
| href | string | A link to the endpoint to retrieve messages of this conversation. |
| totalCount | integer | The total number of messages that can be retrieved through pagination for this conversation. |
| lastMessageId | string | The unique ID generated by the MessageBird platform that identifies latest message. This field is only sent for conversation start. |
Start a Conversation
The start method initiates a new conversation from a channel-specific user identifier, such as a phone number, and sends a first message. Whereas, if there is already an active conversation for the recipient, this conversation will be resumed.
Parameters
| Parameter | Type | Description |
|---|---|---|
| type | string | The type of the message content. |
| content | Content | Content of the message to send. The value of type defines the required fields. |
| to | string | An channel-specific identifier for the receiver. For example: a mobile phone number (MSISDN) is valid for SMS and Whatsapp channels. |
| channelId | string | The unique ID that identifies the channel through which the message should be sent. |
| source | object | The source of the response/action that sent the message. An example of the source form: {"agentId": "abc123", "userId": [1,2,3], "botId": 1234567890} |
| reportUrl | string | The URL for delivery of status reports for the message. Must be HTTPS. |
Definition
POST https://conversations.messagebird.com/v1/conversations/start
Example request
curl -X "POST" "https://conversations.messagebird.com/v1/conversations/start" \-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \--data '{"to":"+31612345678","channelId":"619747f69cf940a98fb443140ce9aed2","type":"text","content":{"text":"Hello!"},"source":{"foo": "bar"}}'
Example response
{"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","messages": {"totalCount": 24,"href": "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages","lastMessageId": "9d5d5921f5b34f8db415a2397eb762f9",}}
List all Conversations
Retrieves all conversations for this account. By default, conversations are sorted by the lastReceivedDatetime field so that all conversations with new messages appear first.
Parameters
No parameters are required; however, filters and pagination can be provided through the following optional query parameters:
| Parameter | Type | Description |
|---|---|---|
| limit | integer | The number of maximum objects to return on each request. |
| offset | integer | The number of objects to skip from the first. |
| ids | string | Comma seperated list of conversation ids to filter. The maximum number of ids allowed for each request is 20. Example: ids=idA,idB,idC |
| status | string | Filter based on status of the conversation. active or archived |
Response
| Attribute | Type | Description |
|---|---|---|
| count | integer | Number of conversations returned. |
| items | array | An array of Conversation objects. |
| limit | integer | The number of maximum objects returned on each request. Max: 200. |
| offset | integer | The number of objects skipped. |
| totalCount | integer | The number of total conversation objects that can be retrieved through pagination. |
Example request
{"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","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","messages": {"totalCount": 23,"href": "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages"}},]}
Example response
{"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","messages": {"totalCount": 23,"href": "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages"}}
Update Conversation Status
Sets the status of a conversation.
Parameters
| Parameter | Type | Description |
|---|---|---|
| status | string | The new status of the conversation. Either active or archived. |
Definition
PATCH https://conversations.messagebird.com/v1/conversations/{id}
Example request
curl -X "PATCH" "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb" \-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \--data '{"status": "archived"}'
Example response
{"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","messages": {"totalCount": 23,"href": "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages"}}
Reply to Conversation
Adds a new message to an existing conversation and sends it to the contact you're talking to.
Definition
POST https://conversations.messagebird.com/v1/conversations/{id}/messages
Example request
curl -X "POST" "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages" \-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \--data '{"type": "text","content":{"text": "Hello!"},"source":{"foo":"var"}}'
Parameters
In the path:
| Parameter | Type | Description |
|---|---|---|
| id | string | The unique ID that identifies the conversation. |
In the request body:
| Parameter | Type | Description |
|---|---|---|
| type | string | The type of the message content. |
| content | Content | Content of the message to send. The value of type defines the required fields. |
| channelId | string | Optional. 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. |
| fallback | Fallback | Optional. Parameters required to send a Fallback message. |
| source | object | The source of the response/action that sent the message. An example of the source form: {"agentId": "abc123", "userId": [1,2,3], "botId": 1234567890} |
| eventType | string | The type of event message being posted, to be able to send that field, the value of the parameter type must be a event |
| reportUrl | string | The URL for delivery of status reports for the message. Must be HTTPS. |
Example response
"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"}}
Fallback Messages
Fallback message are supported when replying to a Conversation, but it is important that the from channel specified with the fallback already exists in the Conversation so an identifier can be found.
Get Messages in Conversation
Retrieves all the messages from the conversation with the provided id.
Parameters
On the path:
| Parameter | Type | Description |
|---|---|---|
| id | string | The unique ID that identifies the conversation. |
Pagination can be provided through the following optional query parameters:
| Parameter | Type | Description |
|---|---|---|
| limit | integer | The number of maximum objects to return on each request. Max: 20. |
| offset | integer | The number of objects to skip from the first. |
Response
| Attribute | Type | Description |
|---|---|---|
| count | integer | Number of messages returned. |
| items | array | 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. |
Example response
{"count": 2,"items": [{"id": "eb34fb1fc73f47a58ad644de0e2de254","conversationId": "2e15efafec384e1c82e9842075e87beb","platform":"whatsapp","channelId": "619747f69cf940a98fb443140ce9aed2","status": "received","direction": "received","to":"+31687654321","from":"+31612345678","type": "text","content": {"text": "This is a test WhatsApp message"},"createdDatetime": "2018-08-29T08:07:15Z","updatedDatetime": "2018-08-29T08:07:33Z","source": {"foo", "bar"}},{"id": "5f3437fdb8444583aea093a047ac014b","conversationId": "2e15efafec384e1c82e9842075e87beb","platform":"events","channelId": "853eeb5348e541a595da93b48c61a1ae","type": "event","eventType": "note","content": {"text": "The conversation has been started"},"createdDatetime": "2018-08-29T10:52:41Z","updatedDatetime": "2018-08-29T10:52:58Z"},{"id": "5f3437fdb8444583aea093a047ac014b","conversationId": "2e15efafec384e1c82e9842075e87beb","platform":"whatsapp","channelId": "853eeb5348e541a595da93b48c61a1ae","status": "delivered","direction": "sent","to":"+31612345678","from":"+31687654321","type": "text","content": {"text": "This is a test SMS message"},"createdDatetime": "2018-08-28T15:52:41Z","updatedDatetime": "2018-08-28T15:52:58Z"},// ... remaining messages omitted],"limit": 20,"offset": 0,"totalCount": 24}
Messages
Messages that have been sent by, or received from, a customer are automatically threaded 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 endpoint. 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 are pre-approved message templates used by WhatsApp.
The Message Object
| 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 | string | A unique identifier for the platform that is used by this channel, for example: sms, whatsapp or messenger. |
| to | string | 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 | string | The direction of the message. Either sent for outbound messages sent through the API or received for inbound messages received from a customer. |
| status | string | The status of the message. Possible values: pending, received, sent, delivered, read, unsupported, failed, and deleted. |
| type | string | The type of message content. Possible values: text, image, audio, video, location, file, hsm (hsm is available only for WhatsApp), and email. |
| content | Content | 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 | The source of the response/action that sent the message. An example of the source form: {"agentId": "abc123", "userId": [1,2,3], "botId": 1234567890} |
Content
| 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 | HSMContent | Required for type hsm. Available only for WhatsApp. |
| content.email | Required for type email. Available only for Email channels. |
Media
| Attribute | Type | Description |
|---|---|---|
| url | string | The url of the remote media file |
| caption | string | The caption associated with the media file |
Location
| Attribute | Type | Description |
|---|---|---|
| latitude | float | The latitude coordinates of the location. |
| longitude | float | The longitude coordinates of the location. |
HSMContent
HSM stands for "Highly Structured Message" and can only be sent over a WhatsApp channel, see HSM Messages for Whatsapp
| Attribute | Type | Description |
|---|---|---|
| hsm.namespace | string | Required. WhatsApp namespace for your account. You will receive this value when setting up your WhatsApp account. |
| hsm.templateName | string | Required. The name of the template. |
| hsm.language | HSMLanguage | Required. |
| hsm.params | array of HSMLocalizableParameters | Required. |
HSMLanguage
| Attribute | Type | Description |
|---|---|---|
| hsm.language.policy | string | Required. Possible values: fallback or deterministic. Deterministic will deliver the message template in exactly the language and locale asked for while fallback will deliver the message template in user's device language, if the settings can't be found on users device the fallback language is used. |
| hsm.language.code | string | Required. The code of the language or locale to use, accepts both language and language_locale formats (e.g., en or en_US). |
HSMLocalizableParameters
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 |
|---|---|---|
| hsm.params.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. |
| hsm.params.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"} |
| hsm.params.dateTime | string | Can be present only if currency object is not present. RFC3339 representation of the date and time. |
Email object
The email object is the same as used by the Email API. The required fields are to, from, subject and content
| Attributes | Type | Description |
|---|---|---|
| id | string | A unique random ID for this message on the MessageBird platform, returned upon acceptance of the message. |
| to | Array of Recipient | Required. An array containing of all the recipients of the message. |
| from | Recipient | 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 | Content | 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. |
| attachments | Array of Attachment | List of the attachments of the message. |
| tracking | Tracking | Optional. Allows you to set tracking options. |
| reportUrl | string | The URL for delivery of status reports for the message. Must use https. |
Content
The 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. |
Recipient
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 |
|---|---|---|---|
| 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 |
Attachments
Attachments for a message are given in-line in the attachments array where each can contain the following properties:
| Attributes | Type | Description |
|---|---|---|
| name | string | The filename of the attachment. This is inserted into the filename parameter of the Content-Disposition header. Maximum length is 255 characters. |
| type | string | The MIME type of the attachment. The value will apply as-is to the Content-Type header of the generated MIME part for the attachment. Include the charset parameter, if needed (e.g. text/html; charset="UTF-8") |
| data | string | The content of the attachment as a Base64 encoded string. The string should not contain \r\n line breaks. |
Tracking
| 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) |
Email Request example
{"subject": "Hello from MessageBird","to": [{"name": "Jane Doe","address": "jane@messagebird.com","variables": {"firstname": "Jane","lastname": "Doe","orderNo": "ABC-321","link": "mailto:unsubscribe@messagebird.com?subject="}}],"from": {"name": "MessageBird.com","address": "noreply@messagebird.com"},"replyTo": "support@messagebird.com","content": {"html": "<b>Hello {{firstname}} {{lastname}}!</b><br><br>Your order <b>{{orderNo}}</b> has been accepted.<br>You'll receive a new email once your order has been shipped.<br><br>Your friends at <a href="https://www.messagebird.com">MessageBird.com</a><br><a href="{{{link}}}{{orderNo}}">Unsubscribe</a>"}}
Example Response
{"id": "5f3437fdb8444583aea093a047ac014b","conversationId": "2e15efafec384e1c82e9842075e87beb","channelId": "853eeb5348e541a595da93b48c61a1ae","platform":"sms","status": "delivered","direction": "sent","to":"+31612345678","from":"+31687654321","type": "text","content": {"text": "This is a test SMS message"},"createdDatetime": "2018-08-28T15:52:41Z","updatedDatetime": "2018-08-28T15:52:58Z","source": {"foo":"bar"}}
Message errors
When a message cannot be sent, the status will change to “rejected” or “failed”, and any additional details available will be provided via an error object attached to the message that indicates the code and a description of the error. Platform-specific error codes for common delivery errors are listed below.
Message Errors
{"id": "5f3437fdb8444583aea093a047ac014b","conversationId": "2e15efafec384e1c82e9842075e87beb","channelId": "853eeb5348e541a595da93b48c61a1ae","type": "text","content": {"text": "This is a test WhatsApp message"},"direction": "sent","status": "failed","error": {"code": 302,"description": "The contact is not registered on WhatsApp."}"createdDatetime": "2018-08-28T15:52:41Z","updatedDatetime": "2018-08-28T15:52:58Z"}
WhatsApp errors
| Code | Message |
|---|---|
| 301 | The message failed to send. Please check your message is valid, including any media, and/or try again later. |
| 302 | The contact is not registered on WhatsApp. |
| 470 | Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid message template. |
Webhooks
Webhooks enable real-time notifications of conversation events to be delivered to endpoints on your own server. A webhook can be configured with a URL and a list of events that should be subscribed to for notifications. It's possible to create multiple webhooks with different URLs to listen to one or more events each.
The Webhook Object
| Attribute | Type | Description |
|---|---|---|
| id | string | The unique ID generated by the MessageBird platform that identifies this webhook. |
| events | array | A list of event name strings from the list of available events that trigger this webhook. |
| channelId | string | The unique identifier for a MessageBird channel that this webhook will subcribe to events for. |
| url | string | The endpoint URL on your server that requests are sent to. |
| status | string | The status of the webhook. Either "enabled" or "disabled". |
| createdDatetime | datetime | The date and time when this webhook was first created. |
| updatedDatetime | datetime | The date and time when this webhook was updated (in RFC3339 format). |
The following events are available:
| Name | 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. |
Create Webhook
Creates a new webhook.
Parameters
| Parameter | Type | Description |
|---|---|---|
| events | array | A list of event name strings from the list of available events that should trigger this webhook. |
| channelId | string | The unique identifier for a MessageBird channel that this webhook will subcribe to events for. |
| url | string | The endpoint URL that requests should be sent to. |
Definition
POST https://conversations.messagebird.com/v1/webhooks
Example request
curl -X "POST" "https://conversations.messagebird.com/v1/webhooks/" \-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \--data '{"events":["message.created", "message.updated"],"channelId": "853eeb5348e541a595da93b48c61a1ae","url":"https://example.com/webhook"}'
Response
| Attribute | Type | Description |
|---|---|---|
| count | integer | Number of webhooks returned. |
| items | array | An 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. |
Example response
{"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},// ... remaining webhooks omitted]}
Update Webhook
Updates a webhook with the supplied parameters. Only parameters that will change need to be provided in the request.
Parameters
| Parameter | Type | Description |
|---|---|---|
| events | array | A list of event name strings from the list of available events that should trigger this webhook. |
| url | string | The endpoint URL that requests should be sent to. |
| status | string | Status of the webhook. Can be set to "enabled" or "disabled" |
Definition
PATCH https://conversations.messagebird.com/v1/webhooks/{id}
Example request
curl -X "PATCH" "https://conversations.messagebird.com/v1/webhooks/985ae50937a94c64b392531ea87a0263" \-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \--data '{"status": "disabled"}'
Example response
{"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"}
Handle Webhooks
HTTP requests will be made to your platform to the URL provided with your webhook whenever one of the events you have subscribed to is triggered within the Conversations API. Each event has a specific payload which is delivered to you as a POST request.
Example JSON bodies are provided below:.
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"}}
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": "95e223e381364b00b1b21e52bbc6285e"},"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"},"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."}}
Response
Your platform should reply with a 200 OK response if it has handled the webhook. If any other response is sent by your platform, MessageBird will attempt to redeliver each specific webhook up to 10 times over a 24-hour period.
If your webhook returns a non-200 response a total of 200 times or more within a 12 hour period, it will be automatically disabled and must be re-enabled manually via the Update method. Any successful response from your webhook will reset this count.
Template Messages for WhatsApp
To initiate a conversation with a client, WhatsApp requires you to use a pre-approved message template called a Message Template (previously called a Highly Structured Message or HSM).
Message Templates are message formats for common reusable messages a business may want to send. This allows a firm to send just the template identifier along with the appropriate parameters instead of the full message content. It also allows for localization of the message and decreases the possibility of being blocked on the first contact as the message is pre-approved by WhatsApp.
How to Send a Message Template (HSM)
A Message Template (HSM message) content can be provided anywhere where other message content is allowed, via POST /conversations/start or POST /conversations/{id}/messages
The id in the URL refers to the conversation ID.
Check out the steps on how to submit your Message Template (HSM messages) for pre-approval by WhatsApp and our step-by-step quickstart on how to write and send a WhatsApp Templates.
Example request
Hi {{1}}, your order has been shipped and should arrive {{2}}
curl -X "POST" "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages" \-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \--data '{"type": "hsm","content":{"hsm": {"namespace": "5ba2d0b7_f2c6_433b_a66e_57b009ceb6ff","templateName": "order_update","language": {"policy": "deterministic","code": "en"},"params": [{"default": "Bob"},{"default": "tomorrow!"}]}}'
Example response
{"id": "2ec3d1e8725f41b1933906426738e6a5","conversationId": "2e15efafec384e1c82e9842075e87beb","channelId": "aa4c8e7cee664341a22ef9bfd9f52477","platform": "whatsapp","status": "pending","type": "hsm","direction": "sent","content": {"hsm": {"namespace": "5ba2d0b7_f2c6_433b_a66e_57b009ceb6ff","templateName": "order_update","language": {"policy": "deterministic","code": "en"},"params": [{ "default": "Bob" },{ "default": "tomorrow!" }]}},"createdDatetime": "2018-08-29T13:53:44.642664784Z","updatedDatetime": "2018-08-29T13:53:44.673850825Z"}
MessageBird WhatsApp Sandbox
The MessageBird WhatsApp Sandbox allows you to try and prototype WhatsApp Business in a developer environment without going through the approval process.
Check out our quickstart for Getting Started with MessageBird's WhatsApp Sandbox in 6 easy steps.
A Message Template (HSM message) content can be provided anywhere where other message content is allowed, via POST /conversations/start or POST /conversations/{id}/messages
The id in the URL refers to the conversation ID.
Unlike sending a Message Template in production, when it's done via the MessageBird WhatsApp Sandbox, the URL https://conversations.messagebird.com is replaced by https://whatsapp-sandbox.messagebird.com.
Keep in mind that the id in the URL refers to the conversation ID.
/start
Hi {{1}}, your order has been shipped and should arrive {{2}}
curl -X "POST" "https://whatsapp-sandbox.messagebird.com/v1/conversations/start" \-H "Authorization: AccessKey YOUR-API-KEY" \-H "Content-Type: application/json" \--data '{"type": "hsm","content":{"hsm": {"namespace": "5ba2d0b7_f2c6_433b_a66e_57b009ceb6ff","templateName": "support","language": {"policy": "deterministic","code": "en"},"params": [{"default": "Bob"},{"default": "tomorrow!"}]}}'
/messages
This is a reply from the sandbox!
curl -X "POST" "https://whatsapp-sandbox.messagebird.com/v1/conversations/{id}/messages" -H "Authorization: AccessKey YOUR-API-KEY" -H "Content-Type: application/json" --data '{"type": "text","content":{"text": "This is a reply from the sandbox!"}}'
Webhooks with the MessageBird WhatsApp Sandbox
You can now use Conversations Webhooks endpoint with the WhatsApp Sandbox to enable the delivery of real-time notifications to any endpoint on your own server.
The WhatsApp Sandbox currently supports the following webhook events:
| Name | Description |
|---|---|
| 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. |
Head over to /Webhooks for more details.