messagebird WhatsApp Messages API

openapi: 3.2.0
info:
  title: MessageBird WhatsApp WhatsApp Messages 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
servers:
- url: https://conversations.messagebird.com/v1
  description: Production Server
security:
- accessKey: []
tags:
- name: WhatsApp Messages
  description: Operations for sending and receiving WhatsApp messages through the Conversations API interface.
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:
  schemas:
    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'
    MessageList:
      type: object
      properties:
        offset:
          type: integer
        limit:
          type: integer
        count:
          type: integer
        totalCount:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/WhatsAppMessage'
    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.
    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
    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.
  parameters:
    offsetParam:
      name: offset
      in: query
      required: false
      description: The number of items to skip.
      schema:
        type: integer
        default: 0
    conversationIdParam:
      name: conversationId
      in: path
      required: true
      description: The unique identifier of the conversation.
      schema:
        type: string
    limitParam:
      name: limit
      in: query
      required: false
      description: The maximum number of items to return.
      schema:
        type: integer
        default: 20
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: Authorization
      description: Access key authentication in the form of 'AccessKey {accessKey}'.
externalDocs:
  description: WhatsApp API Documentation
  url: https://developers.messagebird.com/api/whatsapp