openapi: 3.0.3
info:
  title: Facebook WhatsApp Business API
  description: >-
    Send and receive messages through WhatsApp Business Platform. Support text,
    media, templates, interactive messages, and manage business profiles.
  version: '21.0'
  contact:
    name: Meta Platforms
    url: https://developers.facebook.com
  x-generated-from: documentation
  x-last-validated: '2026-04-18'
servers:
  - url: https://graph.facebook.com/v21.0
    description: WhatsApp Business API v21.0
security:
  - BearerAuth: []
paths:
  /{phone-number-id}/messages:
    post:
      operationId: sendWhatsAppMessage
      summary: Facebook Send WhatsApp Message
      description: Send a message to a WhatsApp user.
      tags:
        - Messages
      parameters:
        - name: phone-number-id
          in: path
          required: true
          description: The phone number ID.
          schema:
            type: string
          example: '106540352242922'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsAppMessageRequest'
            examples:
              SendWhatsAppMessageRequestExample:
                summary: Default sendWhatsAppMessage request
                x-microcks-default: true
                value:
                  messaging_product: whatsapp
                  to: '15551234567'
                  type: text
                  text:
                    body: Hello from our business!
      responses:
        '200':
          description: Message sent successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsAppMessageResponse'
              examples:
                SendWhatsAppMessage200Example:
                  summary: Default sendWhatsAppMessage 200 response
                  x-microcks-default: true
                  value:
                    messaging_product: whatsapp
                    contacts:
                      - input: '15551234567'
                        wa_id: '15551234567'
                    messages:
                      - id: wamid.ABCdef123456
        '400':
          description: Invalid message request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{phone-number-id}/media:
    post:
      operationId: uploadWhatsAppMedia
      summary: Facebook Upload WhatsApp Media
      description: Upload media for use in WhatsApp messages.
      tags:
        - Media
      parameters:
        - name: phone-number-id
          in: path
          required: true
          description: The phone number ID.
          schema:
            type: string
          example: '106540352242922'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                messaging_product:
                  type: string
                  example: whatsapp
                file:
                  type: string
                  format: binary
                type:
                  type: string
                  example: image/jpeg
      responses:
        '200':
          description: Media uploaded successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Media ID.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{phone-number-id}:
    get:
      operationId: getWhatsAppPhoneNumber
      summary: Facebook Get WhatsApp Phone Number
      description: Retrieve phone number details.
      tags:
        - Phone Numbers
      parameters:
        - name: phone-number-id
          in: path
          required: true
          description: The phone number ID.
          schema:
            type: string
          example: '106540352242922'
      responses:
        '200':
          description: Phone number details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsAppPhoneNumber'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{waba-id}/message_templates:
    get:
      operationId: listMessageTemplates
      summary: Facebook List Message Templates
      description: Retrieve message templates for a WhatsApp Business Account.
      tags:
        - Templates
      parameters:
        - name: waba-id
          in: path
          required: true
          description: WhatsApp Business Account ID.
          schema:
            type: string
          example: '102290129340398'
      responses:
        '200':
          description: Templates retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageTemplateList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createMessageTemplate
      summary: Facebook Create Message Template
      description: Create a new message template.
      tags:
        - Templates
      parameters:
        - name: waba-id
          in: path
          required: true
          description: WhatsApp Business Account ID.
          schema:
            type: string
          example: '102290129340398'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageTemplateRequest'
      responses:
        '200':
          description: Template created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{waba-id}/phone_numbers:
    get:
      operationId: listWhatsAppPhoneNumbers
      summary: Facebook List WhatsApp Phone Numbers
      description: Retrieve phone numbers for a WhatsApp Business Account.
      tags:
        - Phone Numbers
      parameters:
        - name: waba-id
          in: path
          required: true
          description: WhatsApp Business Account ID.
          schema:
            type: string
          example: '102290129340398'
      responses:
        '200':
          description: Phone numbers retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: System user access token with whatsapp_business_messaging permission.
  schemas:
    WhatsAppMessageRequest:
      type: object
      description: Request to send a WhatsApp message.
      properties:
        messaging_product:
          type: string
          description: Must be whatsapp.
          example: whatsapp
        to:
          type: string
          description: Recipient phone number.
          example: '15551234567'
        type:
          type: string
          description: Message type.
          enum:
            - text
            - image
            - video
            - audio
            - document
            - template
            - interactive
            - location
            - contacts
            - reaction
          example: text
        text:
          type: object
          description: Text message content.
          properties:
            body:
              type: string
              description: Message body.
              example: Hello from our business!
            preview_url:
              type: boolean
              description: Whether to show URL preview.
        template:
          type: object
          description: Template message content.
          properties:
            name:
              type: string
              description: Template name.
            language:
              type: object
              properties:
                code:
                  type: string
                  description: Language code.
            components:
              type: array
              items:
                type: object
      required:
        - messaging_product
        - to
        - type
    WhatsAppMessageResponse:
      type: object
      description: Response from sending a WhatsApp message.
      properties:
        messaging_product:
          type: string
          description: Messaging product.
          example: whatsapp
        contacts:
          type: array
          items:
            type: object
            properties:
              input:
                type: string
                description: Input phone number.
              wa_id:
                type: string
                description: WhatsApp ID.
        messages:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Message ID.
                example: wamid.ABCdef123456
    WhatsAppPhoneNumber:
      type: object
      description: A WhatsApp Business phone number.
      properties:
        id:
          type: string
          description: Phone number ID.
          example: '106540352242922'
        display_phone_number:
          type: string
          description: Display phone number.
          example: '+1 555 123 4567'
        verified_name:
          type: string
          description: Verified business name.
          example: Example Business
        quality_rating:
          type: string
          description: Phone number quality rating.
          enum:
            - GREEN
            - YELLOW
            - RED
          example: GREEN
        status:
          type: string
          description: Phone number status.
          example: CONNECTED
    MessageTemplate:
      type: object
      description: A WhatsApp message template.
      properties:
        id:
          type: string
          description: Template ID.
          example: '800001234567890'
        name:
          type: string
          description: Template name.
          example: order_confirmation
        language:
          type: string
          description: Template language.
          example: en_US
        status:
          type: string
          description: Template approval status.
          enum:
            - APPROVED
            - PENDING
            - REJECTED
          example: APPROVED
        category:
          type: string
          description: Template category.
          enum:
            - MARKETING
            - UTILITY
            - AUTHENTICATION
          example: UTILITY
        components:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - HEADER
                  - BODY
                  - FOOTER
                  - BUTTONS
              text:
                type: string
    MessageTemplateRequest:
      type: object
      description: Request to create a message template.
      properties:
        name:
          type: string
          description: Template name.
          example: order_update
        language:
          type: string
          description: Template language.
          example: en_US
        category:
          type: string
          description: Template category.
          enum:
            - MARKETING
            - UTILITY
            - AUTHENTICATION
        components:
          type: array
          items:
            type: object
      required:
        - name
        - language
        - category
        - components
    MessageTemplateList:
      type: object
      description: Paginated list of message templates.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/MessageTemplate'
        paging:
          type: object
          properties:
            cursors:
              type: object
              properties:
                before:
                  type: string
                after:
                  type: string
    PhoneNumberList:
      type: object
      description: List of WhatsApp phone numbers.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WhatsAppPhoneNumber'