The MessageBird WhatsApp API allows developers to send and receive WhatsApp messages for alerts, notifications, customer support, and two-factor authentication. It provides access to all WhatsApp Business features through a single API, including template messages, media messages, and interactive message types. The API supports rich media content and provides delivery and read receipts for message tracking.
openapi: 3.1.0
info:
title: MessageBird WhatsApp API
description: >-
The MessageBird WhatsApp API allows developers to send and receive
WhatsApp messages for alerts, notifications, customer support, and
two-factor authentication. It provides access to all WhatsApp Business
features through a single API, including template messages, media
messages, and interactive message types. The API supports rich media
content and provides delivery and read receipts for message tracking.
version: '1.0'
contact:
name: MessageBird Support
url: https://support.messagebird.com
termsOfService: https://www.messagebird.com/en/terms
externalDocs:
description: WhatsApp API Documentation
url: https://developers.messagebird.com/api/whatsapp
servers:
- url: https://conversations.messagebird.com/v1
description: Production Server
tags:
- name: WhatsApp Messages
description: >-
Operations for sending and receiving WhatsApp messages through
the Conversations API interface.
security:
- accessKey: []
paths:
/send:
post:
operationId: sendWhatsAppMessage
summary: Send a WhatsApp message
description: >-
Sends a WhatsApp message to a recipient. Supports text, image,
video, audio, document, location, and template (HSM) message
types. Template messages require pre-approved templates from
the WhatsApp Business platform.
tags:
- WhatsApp Messages
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsAppMessageSend'
responses:
'200':
description: Message accepted
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsAppMessage'
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Unprocessable entity
/conversations:
get:
operationId: listWhatsAppConversations
summary: List WhatsApp conversations
description: >-
Retrieves a list of WhatsApp conversations. Conversations contain
all messages exchanged with a specific WhatsApp contact.
tags:
- WhatsApp Messages
parameters:
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
responses:
'200':
description: A list of conversations
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationList'
'401':
description: Unauthorized
/conversations/{conversationId}/messages:
get:
operationId: listWhatsAppConversationMessages
summary: List messages in a WhatsApp conversation
description: >-
Retrieves all messages in a specific WhatsApp conversation.
tags:
- WhatsApp 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/MessageList'
'401':
description: Unauthorized
'404':
description: Conversation not found
post:
operationId: replyWhatsAppMessage
summary: Reply in a WhatsApp conversation
description: >-
Sends a reply message in an existing WhatsApp conversation.
tags:
- WhatsApp Messages
parameters:
- $ref: '#/components/parameters/conversationIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsAppReply'
responses:
'200':
description: Reply sent
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsAppMessage'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Conversation 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
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:
WhatsAppMessageSend:
type: object
required:
- to
- from
- type
- content
properties:
to:
type: string
description: >-
The recipient WhatsApp phone number in international format.
from:
type: string
description: >-
The WhatsApp channel identifier to send from.
type:
type: string
description: >-
The type of WhatsApp message content.
enum:
- text
- image
- video
- audio
- file
- location
- hsm
- interactive
content:
$ref: '#/components/schemas/WhatsAppContent'
reportUrl:
type: string
format: uri
description: >-
The URL for delivery and read receipt callbacks.
WhatsAppReply:
type: object
required:
- type
- content
properties:
type:
type: string
description: >-
The type of reply content.
enum:
- text
- image
- video
- audio
- file
- location
- hsm
- interactive
content:
$ref: '#/components/schemas/WhatsAppContent'
WhatsAppContent:
type: object
description: >-
The content of the WhatsApp message. The structure depends on
the message type.
properties:
text:
type: string
description: >-
The text content, 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.
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.
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/document content, used when type is file.
properties:
url:
type: string
format: uri
description: >-
The URL of the document.
caption:
type: string
description: >-
An optional caption.
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 template message content, used when type is hsm.
properties:
namespace:
type: string
description: >-
The template namespace.
templateName:
type: string
description: >-
The template name.
language:
type: object
properties:
policy:
type: string
description: >-
The language policy.
enum:
- fallback
- deterministic
code:
type: string
description: >-
The BCP 47 language code.
params:
type: array
description: >-
The template parameter values.
items:
type: object
properties:
default:
type: string
description: >-
The parameter value.
interactive:
type: object
description: >-
Interactive message content for buttons and lists.
properties:
type:
type: string
description: >-
The type of interactive message.
enum:
- button
- list
- product
- product_list
header:
type: object
description: >-
The header content of the interactive message.
body:
type: object
description: >-
The body content of the interactive message.
properties:
text:
type: string
description: >-
The body text.
footer:
type: object
description: >-
The footer content.
properties:
text:
type: string
description: >-
The footer text.
action:
type: object
description: >-
The action configuration for buttons or list items.
WhatsAppMessage:
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 WhatsApp channel identifier.
platform:
type: string
description: >-
The platform identifier.
enum:
- whatsapp
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.
enum:
- accepted
- pending
- sent
- delivered
- read
- failed
- deleted
type:
type: string
description: >-
The type of message content.
content:
$ref: '#/components/schemas/WhatsAppContent'
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.
ConversationList:
type: object
properties:
offset:
type: integer
limit:
type: integer
count:
type: integer
totalCount:
type: integer
items:
type: array
items:
type: object
properties:
id:
type: string
description: >-
The conversation identifier.
status:
type: string
description: >-
The conversation status.
createdDatetime:
type: string
format: date-time
updatedDatetime:
type: string
format: date-time
lastReceivedDatetime:
type: string
format: date-time
MessageList:
type: object
properties:
offset:
type: integer
limit:
type: integer
count:
type: integer
totalCount:
type: integer
items:
type: array
items:
$ref: '#/components/schemas/WhatsAppMessage'