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'