API Reference

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.

API Endpoint

All URLs referenced in MessageBird's Conversations API documentation have the base URL in the code snippet on the right side:

API Endpoint

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

Endpoint Summary

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

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.

Error Object Example

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

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.

URI

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

Available HTTP Methods

POST /send

Definition

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

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}
tag	MessageTag	Mark the message with a particular MessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.
trackId	string	Optional field, useful for grouping messages accross conversations. Limit is 36 characters.

Example request

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

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.

Example response

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

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.

Example request

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

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.

Currently, our Fallback API is in beta and supports fallbacks only between SMS and WhatsApp channels. You can set a fallback for a WhatsApp session message with SMS as the secondary channel, or from a SMS message to WhatsApp as the secondary channel. Please note that fallback configuration using WhatsApp media template messages (content.hsm.components) and location (content.location) are not supported at this time.

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

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'll also receive a message.fallbackTriggered webhook 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.
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.

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

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.
lastUsedPlatformId	string	The platform of the channel most recently used to send or receive a message in this conversation, for example: sms, whatsapp or messenger.

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.
tag	MessageTag	Mark the message with a particular MessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.
trackId	string	Optional field, useful for grouping messages accross conversations. Limit is 36 characters.

Definition

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

Example request

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

A Conversation object as described in the code snippet on your right.

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",
  "lastUsedPlatformId": "whatsapp",
  "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

Definition

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

Example request

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

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

Get Conversation

Allows you to retrieve 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 test_gshuPaZoeEG6ovbc8M79w0QyM"

Response

A Conversation object as described in the code snippet on your right.

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",
  "lastUsedPlatformId": "sms",
  "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 test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "archived"
  }'

Response

A Conversation object as described in the code snippet on your right.

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",
  "lastUsedPlatformId": "sms",
  "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 test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json" \
  -d '{
  "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.
tag	MessageTag	Mark the message with a particular MessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.
trackId	string	Optional field, useful for grouping messages accross conversations. Limit is 36 characters.

Response

A Message object as described in the code snippet on your right.

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.

Definition

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

Example request

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

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.

URI

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

Available HTTP Methods

GET https://conversations.messagebird.com/v1/conversations/{conversationId}/messages
 GET https://conversations.messagebird.com/v1/messages/{id}
 GET https://conversations.messagebird.com/v1/messages?ids={ids}

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}
tag	MessageTag	MessageBird Message Tag. The meaning and effect of each tag depend on each specific platform.

Example request

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

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	Email	Required for type email. Available only for Email channels.

Example response

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

Media

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

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 when a regular template is needed to be used. Otherwise must not be set.
hsm.components	array of HSMComponents	Required when a media template is needed to be used, otherwise must not be set.

HSMLanguage

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
hsm.language.policy	string	Default value: deterministic. If the fallback value is provided (supported until January 2020), it will be overrided by deterministic.
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.

HSMComponents

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
hsm.components.type	string	Required. Value could be set to header or body
hsm.components.parameters	array of HSMComponentParameters	Required.

HSMComponentParameters

Component parameters are the values that put into the hsm message. text, currency and dateTime fills up the message parameters. When hsm.components.type is set to body, the media types can not be set as parameter. image or document types can only be used when hsm.components.type is set to header. Image and document can not be use more than 1 in header

Attribute	Type	Description
hsm.components.type	string	Required. Value could be set to text, currency, date_time, image or document. Image and document could be set when hsm.components.type is header.
hsm.components.text	string	Required for type text
hsm.components.currency	object	Required for type currency. 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.components.dateTime	string	Required for type date_time Can be present only if currency object is not present. RFC3339 representation of the date and time.
hsm.components.document	Media	Required for type document
hsm.components.image	Media	Required for type image

MessageTag

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/

Email object

The email object is the same as used by the Email 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 section.

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.
tracking	Tracking	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 Attachment	Optional. List of files attached to a message.
inlineImages	array of InlineImage	Optional. List of inline images added to the message content.

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

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)

Attachment

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.

Inline images

The Inline Image object represents a 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.

Email object 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><br><img src="cid:mb-logo"><p>Best regards,<br>Customer Support</p>"
  },
  "inlineImages": [
    {
      "ID": "6505d283-7a8d-493c-9ea0-6d38c6bd495a"
      "contentId": "mb-logo"
    }
   ],
   "attachments": [
     {
        "ID": "ebf6acee-d7ae-4375-b726-e247318d3377"
     }
   ]
}

Upload attachments and inline images

Before sending an email with attachments or inline images, they need to be uploaded to the Messaging API. It is mandatory to provide the Content-Type in the HTTP headers, and also chucked transmission is not supported yet.

Definition

POST https://messaging.messagebird.com/v1/files

Example: Uploading a file to Messaging API

curl -X POST https://messaging.messagebird.com/v1/files
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'
  -H 'Content-Disposition: attachment; filename="testing_image.png"'
  -H 'Content-Type: image/png'
  --data-binary @input_image.png

Response

Returns an object with an ID, which you can used while sending an email with attachments or inline image.

Example response

{
  "id": "ebf6acee-d7ae-4375-b726-e247318d3377",
}

Fetching files

You need to provide the ID for fetching the attachment/inline image. The ID has given you when you uploaded the attachment/inline image.

Definition

GET https://messaging.messagebird.com/v1/files/<file-id>

Example: Fetches the file from Messaging API

curl -X GET https://messaging.messagebird.com/v1/files/ebf6acee-d7ae-4375-b726-e247318d3377
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'
  --output uploaded_image.png

Get Message

Retrieves a message with provided id.

Parameters

On the path:

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

Response

A Message object as described in the code snippet on your right.

Example Response

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

Get multiple Messages

Retrieves messages with provided ids.

Parameters

In the query:

Parameter	Type	Description
ids	string	Comma separated string with the unique IDs that identifies the messages.

Definition

GET https://conversations.messagebird.com/v1/messages?ids={ids}

Example Request

curl -X GET "https://conversations.messagebird.com/v1/messages?ids=5f3437fdb8444583aea093a047ac014b,4abc37fdb8444583aea093a047ac014c" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"

Response

A List Message objects, message ids that were not found will be skipped.

Example Response

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

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.

URI

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

Available HTTP Methods

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

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 subscribe 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).
settings	Settings	The webhook extra settings.

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.

Settings

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

Create Webhook

Creates a new webhook.

The webhooks are divided into 2 types:

Channel: they belong to a specific channel. This webhook will be called when you send to or receive from this specific channel.
Generic: they don't belong to a specific channel. This webhook will be called when you send to or receive from any channel.

Please note: You are allowed to create 10 channel webhook, plus 5 generic webhooks.

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 subscribe to events for.
url	string	The endpoint URL that requests should be sent to.
settings	Settings	The webhook extra settings.

Definition

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

Example request

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

A Webhook object as described in the code snippet on your right.

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,
  "settings": {
       "expected_http_code" : "2xx",
       "headers": {
          "from" : "messagebird"
        },
       "query_params" : "transactionID=1312435365",
       "username" : "user20121",
       "password" : "mypass1213",
       "retry": 2,
       "timeout": 14
    }
}

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

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,
    "settings": {
     }
  },
  // ... 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 test_gshuPaZoeEG6ovbc8M79w0QyM"

Response

A Webhook object as described in the code snippet on your right.

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,
  "settings": {
       "expected_http_code" : "2xx",
       "headers": {
          "from" : "messagebird"
        },
       "query_params" : "transactionID=1312435365",
       "username" : "user20121",
       "password" : "mypass1213",
       "retry": 2,
       "timeout": 14
    }
}

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"
settings	Settings	The webhook extra settings.

Definition

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

Example request

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

A Webhook object as described in the code snippet on your right.

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",
  "settings": {
       "expected_http_code" : "2xx",
       "headers": {
          "from" : "messagebird"
        },
       "query_params" : "transactionID=1312435365",
       "username" : "user20121",
       "password" : "mypass1213",
       "retry": 6,
       "timeout": 26
    }
}

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

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

WhatsApp API

MessageBird’s WhatsApp Business allows you to send and receive WhatsApp messages for alerts, notifications, customer support, as well as two-factor authentication. You’ll be able to add all WhatsApp Business features through a single API.

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

Template Messages

Template messages are used to start a conversation with a customer or reply to a customer's message outside the 24-hour window.

They use one of your pre-approved WhatsApp Templates (alerts, appointment reminders, shipping notifications, etc) and need to be submitted and approved by WhatsApp before they can be used. You can submit WhatsApp Templates via the WhatsApp Template Manager on the MessageBird Dashboard.

As they are 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 Template Message

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

The id in the URL refers to the conversation ID.

Check out our quickstart on how to write and send Message Templates for pre-approval by WhatsApp.

Example template message

Hi {{1}}, your order has been shipped and should arrive {{2}}

Example request using POST /send

curl -X POST "https://conversations.messagebird.com/v1/send" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "type": "hsm",
    "from": "aa4c8e7cee664341a22ef9bfd9f52477",
    "content":{
      "hsm": {
        "namespace": "5ba2d0b7_f2c6_433b_a66e_57b009ceb6ff",
        "templateName": "order_update",
        "language": {
        "policy": "deterministic",
        "code": "en"
        },
        "params": [
          {"default": "Bob"},
          {"default": "tomorrow!"}
        ]
      }
    }
  }'

Example response

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

Example request using POST /conversations/start

curl -X POST "https://conversations.messagebird.com/v1/conversations/start" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "type": "hsm",
    "channelId": "aa4c8e7cee664341a22ef9bfd9f52477",
    "content":{
    "hsm": {
      "namespace": "5ba2d0b7_f2c6_433b_a66e_57b009ceb6ff",
      "templateName": "order_update",
      "language": {
      "policy": "deterministic",
      "code": "en"
      },
      "params": [
        {"default": "Bob"},
        {"default": "tomorrow!"}
      ]
    }
  }'

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

How to Send a Media Template Message

Media templates must be pre-approved by WhatsApp. Media templates can be submitted to WhatsApp by sending an email to our Customer Support team (support@messagebird.com), who will ask for the required template data. Once this is received, the Support team will then confirm with you if the template has been approved by WhatsApp.

Please note: media template submissions are not currently possible through the WhatsApp Template Manager.

The Media Template Message content must be provided in the content.hsm property via POST /send, POST /conversations/start or POST /conversations/{id}/messages. Currently, we support two media types - document and image.

Example media template message

Header:
Document content

Body:
Sorry for the delay. Your flight {{1}} is rescheduled to {{2}}. You can find the attachment document here.

Footer:
Best Regard, Messagebird

Example request using POST /send

curl -X POST "https://conversations.messagebird.com/v1/send" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "type": "hsm",
    "from": "aa4c8e7cee664341a22ef9bfd9f52477",
    "content": {
      "hsm": {
        "namespace": "20332cd4_f095_b080_d255_35677159aaff",
        "templateName": "test_media_complex",
        "language": {
          "policy": "deterministic",
          "code": "en"
        },
        "components": [
          {
            "type": "header",
            "parameters": [
              {
                "type": "document",
                "document": {
                  "url": "https://example.com/flight.pdf",
                  "caption": "flight.pdf"
                }
              }
            ]
          },
          {
            "type": "body",
            "parameters": [
              {
                "type": "text",
                "text": "TK 1073"
              },
              {
                "type": "text",
                "text": "18.04.2020"
              }
            ]
          }
        ]
      }
    }
  }'

Example response

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

Example request using POST /conversations/start

curl -X POST "https://conversations.messagebird.com/v1/conversations/start" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "aa4c8e7cee664341a22ef9bfd9f52477",
    "to": "+31612345678",
    "type": "hsm",
    "content":{
    "hsm": {
      "namespace": "20332cd4_f095_b080_d255_35677159aaff",
      "templateName": "test_media_complex",
      "language": {
        "policy": "deterministic",
        "code": "en"
      },
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "document",
              "document": {
                "url": "https://example.com/flight.pdf",
                "caption": "flight.pdf"
              }
            }
          ]
        },
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "TK 1073"
            },
            {
              "type": "text",
              "text": "18.04.2020"
            }
          ]
        }
      ]
    }
  }
}'

Example response

{
  "id": "2ec3d1e8725f41b1933906426738e6a5",
  "conversationId": "2e15efafec384e1c82e9842075e87beb",
  "channelId": "aa4c8e7cee664341a22ef9bfd9f52477",
  "platform": "whatsapp",
  "status": "pending",
  "type": "hsm",
  "direction": "sent",
  "content": {
    "hsm": {
      "namespace": "20332cd4_f095_b080_d255_35677159aaff",
      "templateName": "test_media_complex",
      "language": {
        "policy": "deterministic",
        "code": "en"
      },
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "document",
              "document": {
                "url": "https://example.com/flight.pdf",
                "caption": "flight.pdf"
              }
            }
          ]
        },
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "TK 1073"
            },
            {
              "type": "text",
              "text": "18.04.2020"
            }
          ]
        }
      ]
    }
  },
  "createdDatetime": "2018-08-29T13:53:44.642664784Z",
  "updatedDatetime": "2018-08-29T13:53:44.673850825Z"
}

List WhatsApp Templates

This will return a list of your WhatsApp templates.

Definition

GET https://integrations.messagebird.com/v1/public/whatsapp/templates

Example request

curl "https://integrations.messagebird.com/v1/public/whatsapp/templates" \
-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM"

Example response

[
  {
    "name": "afternoon_delivery",
    "language": "en",
    "status": "APPROVED",
    "content": "Your order has been dispatched for delivery today and you will receive it between 2pm and 6pm this afternoon.",
    "id": "1152561714947990",
    "category": "SHIPPING_UPDATE",
    "createdAt": "2019-07-16T16:04:03.021974161Z",
    "updatedAt": "2019-07-17T16:28:11.906161841Z"
  },
  {
    "name": "account_update",
    "language": "en",
    "status": "APPROVED",
    "content": "Hi {{1}}, a new payment of {{2}} has been made to your account.",
    "id": "705758919879483",
    "category": "ACCOUNT_UPDATE",
    "createdAt": "2019-05-17T09:46:04.634345884Z",
    "updatedAt": "2019-05-24T16:22:27.705346523Z"
  },
  {
    "name": "testing_template",
    "language": "en",
    "status": "APPROVED",
    "content": "Hi {{1}} your new car is ready for collection at {{2}}",
    "id": "586780288479647",
    "category": "SHIPPING_UPDATE",
    "createdAt": "2019-05-22T15:17:07.655357427Z",
    "updatedAt": "2019-05-22T16:39:03.384391637Z"
  }
]

Get WhatsApp Templates By Template Name

This will return your WhatsApp template that is mapped to a specific template name.

Definition

GET https://integrations.messagebird.com/v1/public/whatsapp/templates/{template_name}

Example request

curl "https://integrations.messagebird.com/v1/public/whatsapp/templates/hsm_test1" \
-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM"

Example response

[
  {
    "name": "hsm_test1",
    "language": "en_US",
    "status": "PENDING",
    "content": "Hello {{1}}! Let's send out first message template",
    "id": "428330567879700",
    "category": "RESERVATION_UPDATE",
    "createdAt": "2019-11-04T09:56:40.323528663Z",
    "updatedAt": "2019-11-04T09:58:19.878895703Z"
  }
]

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.

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

Head over to /Webhooks for more details.

Please keep in mind that we do not support message.updated events for the sandbox channel at this time.

Is this page useful?

Next upOmnichannel Widget

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