Programmable Conversations beta

The Programmable Conversations API is a complete omni-channel messaging solution. It empowers you to unify sent and received messages across all of your chat channels in one seamless conversation thread. Conversations can be initiated from the API for channels that allow it, making customer reach simple.

API Endpoint

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

Endpoint Summary

/conversations
/conversations/{id}
/conversations/{id}/messages
/messages/{id}
/send
/webhooks
/webhooks/{webhookId}

Authorization

With each API call you'll need to set an access key to authenticate yourself. API keys can be created or retrieved through 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.

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.

Error Object Example

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

Attributes

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

Platforms

Conversations are support for SMS, WhatsApp, Facebook Messenger, Telegram, LINE, and WeChat. You must install your own configured channel for a platform via the MessageBird Dashboard before using the Conversations API.

Send a Message

The Send endpoint allows you to send a message to a user over any platform supported by Programmable Conversations. 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 messages sent to a single contact will be added to the same conversation, regardless of the channel the message is sent over.

Any 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 an active conversation does not exist, a new one will be created.

URI

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

Available HTTP Methods

POST /send

Definition

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

Parameters

ParameterTypeDescription
tostringEither a channel-specific identifier for the receiver (e.g. MSISDN for SMS or WhatsApp channels), or the ID of a MessageBird Contact.
fromstringThe ID that identifies the channel over which the message should be sent.
typestringThe type of the message content.
contentContentContent of the message. The value of type defines the required fields.
reportUrlstringThe URL for delivery of status reports for the message. Must be HTTPS.
fallbackFallbackParameters required to send a Fallback message if the primary delivery fails.

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"
}'

Response

AttributeTypeDescription
idstringA unique ID generated by the MessageBird platform that identifies this message.
statusstringThe status of the message. It will be initially set to accepted.
fallbackObjectAn object of the form {"id": <uuid>}. Will be present only if a fallback was passed in your request.

Example response

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

Status Reports

If the reportUrl parameter is provided in your request, status reports will be delivered to your platform through a POST request to the supplied URL. The requests hold information about the status of a message that you have sent through the send endpoint. In the event of a delivery failure, the payload will contain a reason for the error.

Example request

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

Fallback Messages

Notification icon

Currently, Fallback Messages are only available in cURL.

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 does not have a mobile data connection, the message will be resent over SMS. You can define the time at which the fallback message should be sent if it was not successful over the primary channel. If you set no time, the fallback will trigger after 1 minute.

Fallback Object

AttributeTypeDescription
fromstringThe ID that identifies the channel over which the message should be sent.
afterstringOptional. A time period to wait before attempting to send the fallback. After this time, if the original message is not in a successfully delivered state, the fallback will be triggered. Formatted as a short-hand duration, e.g.: "30m" for 30 minutes, "3h" for 3 hours. If fallback time is not specified, a default value of 1 minute will be used.

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",
}
}

Fallback Reports

If the reportUrl was provided in your request and the fallback message was triggered, you will also receive a message.fallbackTriggered webhook delivered to your report URL. The webhook body will include the original and fallback message IDs.

Example request

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

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. A conversation status can be active or archived, but only one active conversation exists for each customer at a time. Archive can be used to end a conversation so that the next time that customer reaches out, a new conversation will be started. This is a useful feature for support use cases where you require conversations to be opened and closed, rather than merely resumed. If a message is received from a customer with no active conversations, a new one will be created automatically.

URI

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

Available HTTP Methods

POST /conversations/start
GET /conversations
GET /conversations/{id}
PATCH /conversations/{id}
GET /conversations/{id}/messages
POST /conversations/{id}/messages

The Conversation Object

AttributeTypeDescription
idstringA unique ID generated by the MessageBird platform that identifies this conversation.
contactContactThe MessageBird Contact for this conversation.
channelsarray of ChannelAn array of Channels that the contact of this conversation can be reached on. Can be empty if the conversation doesn't yet have any channels.
statusstringThe status of the conversation. Either active or archived.
messagesMessagesCountA link to the messages of this conversation. See below for definition.
createdDatetimedatetimeThe date and time when this conversation was first created in RFC3339 format.
updatedDatetimedatetimeThe 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.
lastReceivedDatetimedatetimeThe date and time when the most recent message was added to this conversation in RFC3339 format.
lastUsedChannelIdstringA 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.

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

The Channel Object

Channels represent a platform that messages can be sent and received on. You can configure your channels via the MessageBird dashboard. A conversation can take place over multiple channels simultaneously.

AttributeTypeDescription
idstringThe unique ID generated by the MessageBird platform that identifies this channel.
namestringThe name of this channel (configured through the MessageBird dashboard).
platformIdstringA unique identifier for the platform that is used by this channel, for example: sms, whatsapp or messenger.
statusstringThe 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.
createdDatetimedatetimeThe datetime when the message was created (in RFC3339 format).
updatedDatetimedatetimeThe datetime when the message was updated (in RFC3339 format).

MessagesCount

AttributeTypeDescription
hrefstringA link to the endpoint to retrieve messages of this conversation.
totalCountintegerThe total number of messages that can be retrieved for this conversation through pagination.

Start a Conversation

The start method starts a new conversation from a channel-specific user identifier, such as a phone number, and sends a first message. If an active conversation already exists for the recipient, this conversation will be resumed.

Parameters

ParameterTypeDescription
typestringThe type of the message content.
contentContentContent of the message to send. The value of type defines the required fields.
tostringAn channel-specific identifier for the receiver. For example: a mobile phone number (MSISDN) is valid for SMS or Whatsapp channels.
channelIdstringThe unique ID that identifies the channel over which the message should be sent.

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!"}}'

Response

A Conversation object as described above.

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

List all Conversations

Retrieves all conversations for this account. By default, conversations are sorted by their lastReceivedDatetime field so that conversations with new messages appear first.

Parameters

None required. Pagination can be provided through the following optional query parameters:

ParameterTypeDescription
limitintegerThe number of maximum objects to return on each request.
offsetintegerThe number of objects to skip from the first.

Definition

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

Example request

$ curl -X "GET" "https://conversations.messagebird.com/v1/conversations" \
-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM"

Response

AttributeTypeDescription
countintegerNumber of conversations returned.
itemsarrayAn array of Conversation objects.
limitintegerThe number of maximum objects returned on each request. Max: 200.
offsetintegerThe number of objects skipped.
totalCountintegerThe 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"
}
},
]
}

Get Conversation

Retrieves a single conversation.

Definition

GET https://conversations.messagebird.com/v1/conversations/{id}

Example request

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

Response

A Conversation object as described above.

Example response

{
"count": 2,
"items": [
{
"id": "eb34fb1fc73f47a58ad644de0e2de254",
"conversationId": "2e15efafec384e1c82e9842075e87beb",
"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"
},
{
"id": "5f3437fdb8444583aea093a047ac014b",
"conversationId": "2e15efafec384e1c82e9842075e87beb",
"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
}

Update Conversation Status

Sets the status of a conversation.

Parameters

ParameterTypeDescription
statusstringThe 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"}'

Response

A Conversation object without expanded contact or channel information.

Reply to Conversation

Adds a new message to an existing conversation and sends it to the contact that you're in conversation with.

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!"}}'

Parameters

On the path:

ParameterTypeDescription
idstringThe unique ID that identifies the conversation.

In the request body:

ParameterTypeDescription
typestringThe type of the message content.
contentContentContent of the message to send. The value of type defines the required fields.
channelIdstringOptional. 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.
fallbackFallbackOptional. Parameters required to send a Fallback message.

Response

A Message object as described below.

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

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:

ParameterTypeDescription
idstringThe unique ID that identifies the conversation.

Pagination can be provided through the following optional query parameters:

ParameterTypeDescription
limitintegerThe number of maximum objects to return on each request. Max: 20.
offsetintegerThe number of objects to skip from the first.

Definition

GET https://conversations.messagebird.com/v1/conversations/{id}

Example request

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

Response

AttributeTypeDescription
countintegerNumber of messages returned.
itemsarrayAn array of message objects.
limitintegerThe number of maximum objects returned on each request.
offsetintegerThe number of objects skipped.
totalCountintegerThe number of total message objects that can be retrieved through pagination.

Example response

{
"count": 2,
"items": [
{
"id": "eb34fb1fc73f47a58ad644de0e2de254",
"conversationId": "2e15efafec384e1c82e9842075e87beb",
"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"
},
{
"id": "5f3437fdb8444583aea093a047ac014b",
"conversationId": "2e15efafec384e1c82e9842075e87beb",
"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.

URI

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

Available HTTP Methods

GET /messages/{id}

The Message Object

AttributeTypeDescription
idstringThe unique ID generated by the MessageBird platform that identifies this message.
conversationIdstringThe unique ID that identifies the conversation that this message is a part of.
channelIdstringThe unique ID that identifies the channel that the message was sent or received on.
tostringThe unique ID that identifies the message recepient. The value depends on platform.
fromstringThe unique ID that identifies the message sender. The value depends on platform.
directionstringThe direction of the message. Either sent for outbound messages sent through the API or received for inbound messages received from a customer.
statusstringThe status of the message. Possible values: pending, received, sent, delivered, read, unsupported, failed, and deleted.
typestringThe type of message content. Possible values: text, image, audio, video, location, file, and hsm (hsm is available only for WhatsApp).
contentContentContent of the message. The type field indicates the fields that will be populated in this object.
createdDatetimedatetimeThe datetime when the message was created (in RFC3339 format).
updatedDatetimedatetimeThe datetime when the message was updated (in RFC3339 format).

Content

AttributeTypeDescription
content.textstringRequired for type text. The plain-text content of the message.
content.imageobjectRequired for type image. An object of the form {"url": "<media url>"} containing the url of the remote media file.
content.audioobjectRequired for type audio. An object of the form {"url": "<media url>"} containing the url of the remote media file.
content.videoobjectRequired for type video. An object of the form {"url": "<media url>"} containing the url of the remote media file.
content.fileobjectRequired for type file. An object of the form {"url": "<media url>"} containing the url of the remote media file.
content.locationobjectRequired for type location. An object of the form {"latitude": lat, "longitude": lon} containing the latitude and longitude coordinates of the location. Latitude and longitude are expected as floats.
content.hsmHSMContentRequired for type hsm. Available only for WhatsApp.

HSMContent

HSM stands for "Highly Structured Message" and can only be sent over a WhatsApp channel, see HSM Messages for Whatsapp

AttributeTypeDescription
hsm.namespacestringRequired. WhatsApp namespace for your account. You will receive this value when setting up your WhatsApp account.
hsm.templateNamestringRequired. The name of the template.
hsm.languageHSMLanguageRequired.
hsm.paramsarray of HSMLocalizableParametersRequired.

HSMLanguage

AttributeTypeDescription
hsm.language.policystringRequired. 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.codestringRequired. 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.

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

Get Message

Retrieves a message with provided id.

Parameters

On the path:

ParameterTypeDescription
idstringThe unique ID that identifies the message.

Definition

GET https://conversations.messagebird.com/v1/messages/{id}

Example Request

$ curl -X "GET" "https://conversations.messagebird.com/v1/messages/5f3437fdb8444583aea093a047ac014b" \
-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM"

Response

A Message object as described above.

Example Response

{
"id": "5f3437fdb8444583aea093a047ac014b",
"conversationId": "2e15efafec384e1c82e9842075e87beb",
"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"
}

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

CodeMessage
301The message failed to send. Please check your message is valid, including any media, and/or try again later.
302The contact is not registered on WhatsApp.
470Failed 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.

URI

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

Available HTTP Methods

POST /webhooks
GET /webhooks
DELETE /webhooks/{id}

The Webhook Object

AttributeTypeDescription
idstringThe unique ID generated by the MessageBird platform that identifies this webhook.
eventsarrayA list of event name strings from the list of available events that trigger this webhook.
channelIdstringThe unique identifier for a MessageBird channel that this webhook will subcribe to events for.
urlstringThe endpoint URL on your server that requests are sent to.
statusstringThe status of the webhook. Either "enabled" or "disabled".
createdDatetimedatetimeThe date and time when this webhook was first created.
updatedDatetimedatetimeThe date and time when this webhook was updated (in RFC3339 format).

The following events are available:

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

Create Webhook

Creates a new webhook.

Parameters

ParameterTypeDescription
eventsarrayA list of event name strings from the list of available events that should trigger this webhook.
channelIdstringThe unique identifier for a MessageBird channel that this webhook will subcribe to events for.
urlstringThe 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

A Webhook object as described below.

Example request

{
"id": "985ae50937a94c64b392531ea87a0263",
"url": "https://example.com/webhook",
"channelId": "853eeb5348e541a595da93b48c61a1ae",
"events": [
"message.created",
"message.updated",
],
"status": "enabled",
"createdDatetime": "2018-08-29T10:04:23Z",
"updatedDatetime": null
}

List Webhooks

Retrieves a list of webhooks.

Definition

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

Example request

$ curl -X "GET" "https://conversations.messagebird.com/v1/webhooks/" \
-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM"

Response

AttributeTypeDescription
countintegerNumber of webhooks returned.
itemsarrayAn array of webhook objects.
limitintegerThe number of maximum objects returned on each request.
offsetintegerThe number of objects skipped.
totalCountintegerThe number of total webhook objects that can be retrieved through pagination.

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
]
}

Get Webhook

Retrieves an existing webhook by id.

Definition

GET https://conversations.messagebird.com/v1/webhooks/{id}

Example request

$ curl -X "GET" "https://conversations.messagebird.com/v1/webhooks/985ae50937a94c64b392531ea87a0263" \ -H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM"

Response

A Webhook object as described above.

Example response

{
"id": "985ae50937a94c64b392531ea87a0263",
"url": "https://example.com/webhook",
"channelId": "853eeb5348e541a595da93b48c61a1ae",
"events": [
"message.created",
"message.updated",
],
"status": "enabled",
"createdDatetime": "2018-08-29T10:04:23Z",
"updatedDatetime": null
}

Update Webhook

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

Parameters

ParameterTypeDescription
eventsarrayA list of event name strings from the list of available events that should trigger this webhook.
urlstringThe endpoint URL that requests should be sent to.
statusstringStatus 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"}'

Response

A Webhook object as described above.

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

Delete Webhook

Disables and removes an existing webhook so that it is no longer triggered.

Definition

DELETE https://conversations.messagebird.com/v1/webhooks/{id}

Example request

$ curl -X "DELETE" "https://conversations.messagebird.com/v1/webhooks/985ae50937a94c64b392531ea87a0263" \
-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM"

Example response

204 No Content

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.

Response

200 OK

Template Messages for WhatsApp

A HSM is a pre-approved, reusable message template required when messaging over WhatsApp. It allows you to just send the required parameter values instead of the full message. 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 an HSM Message

HSM message content can be provided anywhere where other message content is allowed, via POST /conversations/start or POST /conversations/{id}/messages

Go to our Help Center for steps on how to submit your HSMs for pre-approval by WhatsApp.

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!"}
]
}
}'

Response

{
"id": "2ec3d1e8725f41b1933906426738e6a5",
"conversationId": "2e15efafec384e1c82e9842075e87beb",
"channelId": "aa4c8e7cee664341a22ef9bfd9f52477",
"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"
}
cURL
PHP
Node
C#
Java
Ruby
Go
Python
Cookie Settings