The MessageBird Conversations API provides a unified interface for managing omnichannel messaging across platforms such as SMS, WhatsApp, Facebook Messenger, Telegram, and more. It consolidates messages from multiple channels into a single conversation thread per contact, enabling consistent customer communication. The API supports sending and receiving messages, managing conversation state, and handling webhooks for real-time event processing.
openapi: 3.1.0
info:
title: MessageBird Conversations API
description: >-
The MessageBird Conversations API provides a unified interface for
managing omnichannel messaging across platforms such as SMS, WhatsApp,
Facebook Messenger, Telegram, and more. It consolidates messages from
multiple channels into a single conversation thread per contact,
enabling consistent customer communication. The API supports sending
and receiving messages, managing conversation state, and handling
webhooks for real-time event processing.
version: '1.0'
contact:
name: MessageBird Support
url: https://support.messagebird.com
termsOfService: https://www.messagebird.com/en/terms
externalDocs:
description: Conversations API Documentation
url: https://developers.messagebird.com/api/conversations/
servers:
- url: https://conversations.messagebird.com/v1
description: Production Server
tags:
- name: Conversations
description: >-
Operations for listing and managing conversations across channels.
- name: Messages
description: >-
Operations for sending and retrieving messages within conversations.
- name: Webhooks
description: >-
Operations for managing conversation webhooks that receive real-time
event notifications.
security:
- accessKey: []
paths:
/conversations:
get:
operationId: listConversations
summary: List conversations
description: >-
Retrieves a paginated list of all conversations. Conversations are
returned in reverse chronological order based on the last received
message.
tags:
- Conversations
parameters:
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
- name: status
in: query
required: false
description: >-
Filter conversations by status.
schema:
type: string
enum:
- active
- archived
responses:
'200':
description: A list of conversations
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationList'
'401':
description: Unauthorized
/conversations/start:
post:
operationId: startConversation
summary: Start a conversation
description: >-
Starts a new conversation by sending a message to a contact. If a
conversation already exists with the contact, the message is added
to the existing conversation.
tags:
- Conversations
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationStart'
responses:
'200':
description: Conversation started
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
'400':
description: Bad request
'401':
description: Unauthorized
/conversations/{conversationId}:
get:
operationId: viewConversation
summary: View a conversation
description: >-
Retrieves the details of a specific conversation by its unique
identifier.
tags:
- Conversations
parameters:
- $ref: '#/components/parameters/conversationIdParam'
responses:
'200':
description: Conversation details
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
'401':
description: Unauthorized
'404':
description: Conversation not found
patch:
operationId: updateConversation
summary: Update a conversation
description: >-
Updates the status of an existing conversation, such as archiving
or reactivating it.
tags:
- Conversations
parameters:
- $ref: '#/components/parameters/conversationIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationUpdate'
responses:
'200':
description: Conversation updated
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Conversation not found
/conversations/{conversationId}/messages:
get:
operationId: listConversationMessages
summary: List messages in a conversation
description: >-
Retrieves a paginated list of all messages within a specific
conversation. Messages are returned with the newest first.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/conversationIdParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
responses:
'200':
description: A list of messages
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationMessageList'
'401':
description: Unauthorized
'404':
description: Conversation not found
post:
operationId: sendConversationMessage
summary: Send a message in a conversation
description: >-
Sends a new message within an existing conversation. The message
will be delivered through the channel associated with the
conversation.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/conversationIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationMessageSend'
responses:
'200':
description: Message sent
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationMessage'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Conversation not found
/send:
post:
operationId: sendMessage
summary: Send a message
description: >-
Sends a message to a recipient without requiring an existing
conversation. MessageBird will automatically match or create a
conversation for the recipient.
tags:
- Messages
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageSend'
responses:
'200':
description: Message accepted
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationMessage'
'400':
description: Bad request
'401':
description: Unauthorized
/messages/{messageId}:
get:
operationId: viewMessage
summary: View a message
description: >-
Retrieves the details of a specific message by its unique
identifier.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/messageIdParam'
responses:
'200':
description: Message details
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationMessage'
'401':
description: Unauthorized
'404':
description: Message not found
/webhooks:
get:
operationId: listWebhooks
summary: List webhooks
description: >-
Retrieves a list of all configured conversation webhooks. The
platform supports up to 10 channel-specific webhooks and 5
generic webhooks.
tags:
- Webhooks
parameters:
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
responses:
'200':
description: A list of webhooks
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookList'
'401':
description: Unauthorized
post:
operationId: createWebhook
summary: Create a webhook
description: >-
Creates a new webhook to receive real-time notifications for
conversation events. Webhooks can be channel-specific or generic.
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookCreate'
responses:
'200':
description: Webhook created
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'400':
description: Bad request
'401':
description: Unauthorized
/webhooks/{webhookId}:
get:
operationId: viewWebhook
summary: View a webhook
description: >-
Retrieves the details of a specific webhook by its unique
identifier.
tags:
- Webhooks
parameters:
- $ref: '#/components/parameters/webhookIdParam'
responses:
'200':
description: Webhook details
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'401':
description: Unauthorized
'404':
description: Webhook not found
patch:
operationId: updateWebhook
summary: Update a webhook
description: >-
Updates the configuration of an existing webhook.
tags:
- Webhooks
parameters:
- $ref: '#/components/parameters/webhookIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookCreate'
responses:
'200':
description: Webhook updated
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Webhook not found
delete:
operationId: deleteWebhook
summary: Delete a webhook
description: >-
Deletes an existing webhook by its unique identifier.
tags:
- Webhooks
parameters:
- $ref: '#/components/parameters/webhookIdParam'
responses:
'204':
description: Webhook deleted
'401':
description: Unauthorized
'404':
description: Webhook not found
components:
securitySchemes:
accessKey:
type: apiKey
in: header
name: Authorization
description: >-
Access key authentication in the form of 'AccessKey {accessKey}'.
parameters:
conversationIdParam:
name: conversationId
in: path
required: true
description: >-
The unique identifier of the conversation.
schema:
type: string
messageIdParam:
name: messageId
in: path
required: true
description: >-
The unique identifier of the message.
schema:
type: string
webhookIdParam:
name: webhookId
in: path
required: true
description: >-
The unique identifier of the webhook.
schema:
type: string
offsetParam:
name: offset
in: query
required: false
description: >-
The number of items to skip.
schema:
type: integer
default: 0
limitParam:
name: limit
in: query
required: false
description: >-
The maximum number of items to return.
schema:
type: integer
default: 20
schemas:
ConversationStart:
type: object
required:
- to
- type
- content
- channelId
properties:
to:
type: string
description: >-
The identifier of the recipient, such as a phone number or
platform-specific ID.
type:
type: string
description: >-
The type of message content being sent.
enum:
- text
- image
- video
- audio
- file
- location
- hsm
content:
$ref: '#/components/schemas/MessageContent'
channelId:
type: string
description: >-
The unique identifier of the channel to use for sending.
reportUrl:
type: string
format: uri
description: >-
The URL to receive delivery status callbacks.
ConversationUpdate:
type: object
properties:
status:
type: string
description: >-
The new status for the conversation.
enum:
- active
- archived
ConversationMessageSend:
type: object
required:
- type
- content
properties:
type:
type: string
description: >-
The type of message content.
enum:
- text
- image
- video
- audio
- file
- location
- hsm
content:
$ref: '#/components/schemas/MessageContent'
channelId:
type: string
description: >-
The channel to use for sending. If omitted, the last used
channel in the conversation is used.
reportUrl:
type: string
format: uri
description: >-
The URL for delivery status callbacks.
MessageSend:
type: object
required:
- to
- from
- type
- content
properties:
to:
type: string
description: >-
The recipient identifier.
from:
type: string
description: >-
The channel identifier to send from.
type:
type: string
description: >-
The type of message content.
enum:
- text
- image
- video
- audio
- file
- location
- hsm
content:
$ref: '#/components/schemas/MessageContent'
reportUrl:
type: string
format: uri
description: >-
The URL for delivery status callbacks.
MessageContent:
type: object
description: >-
The content of the message. The structure depends on the message
type.
properties:
text:
type: string
description: >-
The text content of the message, used when type is text.
image:
type: object
description: >-
The image content, used when type is image.
properties:
url:
type: string
format: uri
description: >-
The URL of the image.
caption:
type: string
description: >-
An optional caption for the image.
video:
type: object
description: >-
The video content, used when type is video.
properties:
url:
type: string
format: uri
description: >-
The URL of the video.
caption:
type: string
description: >-
An optional caption for the video.
audio:
type: object
description: >-
The audio content, used when type is audio.
properties:
url:
type: string
format: uri
description: >-
The URL of the audio file.
file:
type: object
description: >-
The file content, used when type is file.
properties:
url:
type: string
format: uri
description: >-
The URL of the file.
caption:
type: string
description: >-
An optional caption for the file.
location:
type: object
description: >-
The location content, used when type is location.
properties:
latitude:
type: number
format: double
description: >-
The latitude coordinate.
longitude:
type: number
format: double
description: >-
The longitude coordinate.
hsm:
type: object
description: >-
The HSM (Highly Structured Message) template content, used
for WhatsApp template messages.
properties:
namespace:
type: string
description: >-
The namespace of the template.
templateName:
type: string
description: >-
The name of the template.
language:
type: object
properties:
policy:
type: string
description: >-
The language policy.
code:
type: string
description: >-
The language code.
params:
type: array
description: >-
The template parameters.
items:
type: object
properties:
default:
type: string
description: >-
The default value for the parameter.
Conversation:
type: object
properties:
id:
type: string
description: >-
The unique identifier of the conversation.
contactId:
type: string
description: >-
The unique identifier of the contact.
contact:
$ref: '#/components/schemas/Contact'
channels:
type: array
description: >-
The channels used in this conversation.
items:
$ref: '#/components/schemas/Channel'
status:
type: string
description: >-
The status of the conversation.
enum:
- active
- archived
createdDatetime:
type: string
format: date-time
description: >-
The date and time when the conversation was created.
updatedDatetime:
type: string
format: date-time
description: >-
The date and time when the conversation was last updated.
lastReceivedDatetime:
type: string
format: date-time
description: >-
The date and time of the last received message.
lastUsedChannelId:
type: string
description: >-
The identifier of the last channel used in the conversation.
messages:
$ref: '#/components/schemas/ConversationMessageList'
ConversationList:
type: object
properties:
offset:
type: integer
description: >-
The offset of the result set.
limit:
type: integer
description: >-
The limit applied to the result set.
count:
type: integer
description: >-
The number of items returned.
totalCount:
type: integer
description: >-
The total number of conversations.
items:
type: array
items:
$ref: '#/components/schemas/Conversation'
ConversationMessage:
type: object
properties:
id:
type: string
description: >-
The unique identifier of the message.
conversationId:
type: string
description: >-
The conversation this message belongs to.
channelId:
type: string
description: >-
The channel through which the message was sent or received.
platform:
type: string
description: >-
The platform of the channel.
to:
type: string
description: >-
The recipient identifier.
from:
type: string
description: >-
The sender identifier.
direction:
type: string
description: >-
The direction of the message.
enum:
- sent
- received
status:
type: string
description: >-
The delivery status of the message.
enum:
- accepted
- pending
- sent
- delivered
- read
- failed
- deleted
type:
type: string
description: >-
The type of message content.
content:
$ref: '#/components/schemas/MessageContent'
createdDatetime:
type: string
format: date-time
description: >-
The date and time when the message was created.
updatedDatetime:
type: string
format: date-time
description: >-
The date and time when the message was last updated.
ConversationMessageList:
type: object
properties:
offset:
type: integer
description: >-
The offset of the result set.
limit:
type: integer
description: >-
The limit applied to the result set.
count:
type: integer
description: >-
The number of items returned.
totalCount:
type: integer
description: >-
The total number of messages.
items:
type: array
items:
$ref: '#/components/schemas/ConversationMessage'
Contact:
type: object
properties:
id:
type: string
description: >-
The unique identifier of the contact.
href:
type: string
format: uri
description: >-
The URL of the contact resource.
msisdn:
type: string
description: >-
The phone number of the contact.
displayName:
type: string
description: >-
The display name of the contact.
firstName:
type: string
description: >-
The first name of the contact.
lastName:
type: string
description: >-
The last name of the contact.
customDetails:
type: object
description: >-
Custom details associated with the contact.
createdDatetime:
type: string
format: date-time
description: >-
The date and time when the contact was created.
updatedDatetime:
type: string
format: date-time
description: >-
The date and time when the contact was last updated.
Channel:
type: object
properties:
id:
type: string
description: >-
The unique identifier of the channel.
name:
type: string
description: >-
The name of the channel.
platformId:
type: string
description: >-
The platform identifier for the channel.
enum:
- sms
- whatsapp
- facebook
- telegram
- line
- wechat
- email
status:
type: string
description: >-
The status of the channel.
enum:
- active
- inactive
- pending
createdDatetime:
type: string
format: date-time
description: >-
The date and time when the channel was created.
updatedDatetime:
type: string
format: date-time
description: >-
The date and time when the channel was last updated.
WebhookCreate:
type: object
required:
- channelId
- url
- events
properties:
channelId:
type: string
description: >-
The channel to subscribe to. Omit for a generic webhook that
receives events from all channels.
url:
type: string
format: uri
description: >-
The URL to receive webhook payloads.
events:
type: array
description: >-
The list of events to subscribe to.
items:
type: string
enum:
- message.created
- message.updated
- conversation.created
- conversation.updated
Webhook:
type: object
properties:
id:
type: string
description: >-
The unique identifier of the webhook.
channelId:
type: string
description: >-
The channel the webhook is subscribed to.
url:
type: string
format: uri
description: >-
The URL that receives webhook payloads.
events:
type: array
description: >-
The events the webhook is subscribed to.
items:
type: string
status:
type: string
description: >-
The status of the webhook.
enum:
- enabled
- disabled
createdDatetime:
type: string
format: date-time
description: >-
The date and time when the webhook was created.
updatedDatetime:
type: string
format: date-time
description: >-
The date and time when the webhook was last updated.
WebhookList:
type: object
properties:
offset:
type: integer
description: >-
The offset of the result set.
limit:
type: integer
description: >-
The limit applied to the result set.
count:
type: integer
description: >-
The number of items returned.
totalCount:
type: integer
description: >-
The total number of webhooks.
items:
type: array
items:
$ref: '#/components/schemas/Webhook'