openapi: 3.1.0
info:
  title: MessageBird Balance Available Numbers WhatsApp Messages API
  description: The MessageBird Balance API provides developers with access to their account balance information. It returns the current payment type, available amount, and currency for the account associated with the API key. This API is useful for monitoring credit usage, building billing dashboards, and setting up automated alerts when account balances fall below a threshold.
  version: '1.0'
  contact:
    name: MessageBird Support
    url: https://support.messagebird.com
  termsOfService: https://www.messagebird.com/en/terms
servers:
- url: https://rest.messagebird.com
  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:
  parameters:
    limitParam:
      name: limit
      in: query
      required: false
      description: The maximum number of items to return.
      schema:
        type: integer
        default: 20
    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
  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.
    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.
    MessageList:
      type: object
      properties:
        offset:
          type: integer
        limit:
          type: integer
        count:
          type: integer
        totalCount:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/WhatsAppMessage'
    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
    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'
    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.
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: Authorization
      description: Access key authentication in the form of 'AccessKey {accessKey}'.
externalDocs:
  description: Balance API Documentation
  url: https://developers.messagebird.com/api/balance/