WhatsApp Business Account Management API

openapi: 3.1.0
info:
  title: WhatsApp Business Management API
  description: >-
    The WhatsApp Business Management API enables programmatic management of
    WhatsApp Business Accounts, phone numbers, message templates, analytics,
    user assignments, product catalogs, and webhook subscriptions through
    the Meta Graph API.
  version: '21.0'
  contact:
    name: Meta Platform Support
    url: https://developers.facebook.com/support/
  termsOfService: https://www.whatsapp.com/legal/business-terms
externalDocs:
  description: WhatsApp Business Management API Documentation
  url: https://developers.facebook.com/docs/whatsapp/business-management-api
servers:
- url: https://graph.facebook.com/v21.0
  description: Meta Graph API Production Server
tags:
- name: Analytics
  description: Retrieve conversation and template analytics
- name: Assigned Users
  description: Manage user access to a WABA
- name: Business Accounts
  description: Manage WhatsApp Business Account information
- name: Message Templates
  description: Create, update, and delete message templates
- name: Phone Numbers
  description: List and manage phone numbers on a WABA
- name: Product Catalogs
  description: Connect and manage product catalogs
- name: Subscribed Apps
  description: Manage webhook subscriptions for a WABA
security:
- bearerAuth: []
paths:
  /{waba-id}:
    get:
      operationId: getWhatsAppBusinessAccount
      summary: WhatsApp Get WABA Info
      description: Retrieves information about a WhatsApp Business Account.
      tags:
      - Business Accounts
      parameters:
      - $ref: '#/components/parameters/WabaId'
      - name: fields
        in: query
        description: Comma-separated list of fields to return
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: WABA info retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsAppBusinessAccount'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{waba-id}/phone_numbers:
    get:
      operationId: listPhoneNumbers
      summary: WhatsApp List Phone Numbers
      description: Lists all phone numbers associated with a WhatsApp Business Account.
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/WabaId'
      - name: fields
        in: query
        description: Comma-separated fields to return
        schema:
          type: string
        example: example_value
      - name: limit
        in: query
        description: Pagination limit
        schema:
          type: integer
        example: 42
      - name: after
        in: query
        description: Cursor for forward pagination
        schema:
          type: string
        example: example_value
      - name: before
        in: query
        description: Cursor for backward pagination
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Phone numbers retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PhoneNumber'
                  paging:
                    $ref: '#/components/schemas/CursorPaging'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{waba-id}/message_templates:
    get:
      operationId: listMessageTemplates
      summary: WhatsApp List Message Templates
      description: Lists all message templates for a WhatsApp Business Account.
      tags:
      - Message Templates
      parameters:
      - $ref: '#/components/parameters/WabaId'
      - name: fields
        in: query
        schema:
          type: string
        example: example_value
      - name: limit
        in: query
        schema:
          type: integer
          default: 25
        example: 42
      - name: after
        in: query
        schema:
          type: string
        example: example_value
      - name: before
        in: query
        schema:
          type: string
        example: example_value
      - name: name
        in: query
        description: Filter by template name
        schema:
          type: string
        example: Example Business
      - name: language
        in: query
        description: Filter by language code
        schema:
          type: string
        example: en_US
      - name: status
        in: query
        description: Filter by approval status
        schema:
          type: string
          enum:
          - APPROVED
          - PENDING
          - REJECTED
          - PAUSED
          - DISABLED
        example: APPROVED
      - name: category
        in: query
        description: Filter by template category
        schema:
          type: string
          enum:
          - AUTHENTICATION
          - MARKETING
          - UTILITY
        example: AUTHENTICATION
      responses:
        '200':
          description: Templates retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MessageTemplate'
                  paging:
                    $ref: '#/components/schemas/CursorPaging'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createMessageTemplate
      summary: WhatsApp Create Message Template
      description: >-
        Creates a new message template for a WhatsApp Business Account.
        Templates must be approved by Meta before they can be used to send
        messages.
      tags:
      - Message Templates
      parameters:
      - $ref: '#/components/parameters/WabaId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateRequest'
      responses:
        '200':
          description: Template created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                  category:
                    type: string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteMessageTemplate
      summary: WhatsApp Delete Message Template
      description: >-
        Deletes a message template. Deleting by name removes all language
        variants. Pass hsm_id to delete a specific language version.
      tags:
      - Message Templates
      parameters:
      - $ref: '#/components/parameters/WabaId'
      - name: name
        in: query
        required: true
        description: Template name to delete
        schema:
          type: string
        example: Example Business
      - name: hsm_id
        in: query
        description: Specific template ID to delete a single language variant
        schema:
          type: string
        example: wamid.abc123
      responses:
        '200':
          description: Template deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{message-template-id}:
    post:
      operationId: updateMessageTemplate
      summary: WhatsApp Update Message Template
      description: >-
        Updates an existing message template. Only APPROVED or PAUSED templates
        can be edited. Edits re-trigger the approval process.
      tags:
      - Message Templates
      parameters:
      - name: message-template-id
        in: path
        required: true
        schema:
          type: string
        example: wamid.abc123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                components:
                  type: array
                  items:
                    $ref: '#/components/schemas/TemplateComponentDefinition'
                category:
                  type: string
                  enum:
                  - AUTHENTICATION
                  - MARKETING
                  - UTILITY
      responses:
        '200':
          description: Template updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{waba-id}/conversation_analytics:
    get:
      operationId: getConversationAnalytics
      summary: WhatsApp Get Conversation Analytics
      description: Retrieves conversation analytics for a WhatsApp Business Account.
      tags:
      - Analytics
      parameters:
      - $ref: '#/components/parameters/WabaId'
      - name: start
        in: query
        required: true
        description: Start time (Unix timestamp or YYYY-MM-DD)
        schema:
          type: string
        example: example_value
      - name: end
        in: query
        required: true
        description: End time (Unix timestamp or YYYY-MM-DD)
        schema:
          type: string
        example: example_value
      - name: granularity
        in: query
        required: true
        schema:
          type: string
          enum:
          - HALF_HOUR
          - DAILY
          - MONTHLY
        example: HALF_HOUR
      - name: phone_numbers
        in: query
        description: Filter by phone number IDs
        schema:
          type: array
          items:
            type: string
      - name: metric_types
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - CONVERSATION
            - COST
      - name: conversation_categories
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - AUTHENTICATION
            - MARKETING
            - UTILITY
            - SERVICE
            - REFERRAL_CONVERSION
      - name: dimensions
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - CONVERSATION_CATEGORY
            - CONVERSATION_TYPE
            - COUNTRY
            - PHONE
      responses:
        '200':
          description: Analytics retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationAnalytics'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{waba-id}/template_analytics:
    get:
      operationId: getTemplateAnalytics
      summary: WhatsApp Get Template Analytics
      description: Retrieves analytics for specific message templates.
      tags:
      - Analytics
      parameters:
      - $ref: '#/components/parameters/WabaId'
      - name: start
        in: query
        required: true
        schema:
          type: string
        example: example_value
      - name: end
        in: query
        required: true
        schema:
          type: string
        example: example_value
      - name: granularity
        in: query
        required: true
        schema:
          type: string
          enum:
          - DAILY
        example: DAILY
      - name: template_ids
        in: query
        required: true
        description: Template IDs to analyze (max 10)
        schema:
          type: array
          maxItems: 10
          items:
            type: string
      - name: metric_types
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - SENT
            - DELIVERED
            - READ
            - CLICKED
            - COST
      responses:
        '200':
          description: Template analytics retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateAnalytics'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{waba-id}/subscribed_apps:
    get:
      operationId: listSubscribedApps
      summary: WhatsApp List Webhook Subscriptions
      description: Lists all apps subscribed to webhook events for this WABA.
      tags:
      - Subscribed Apps
      parameters:
      - $ref: '#/components/parameters/WabaId'
      responses:
        '200':
          description: Subscriptions retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        link:
                          type: string
                        name:
                          type: string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: subscribeApp
      summary: WhatsApp Subscribe App to Webhooks
      description: Subscribes the current app to receive webhook events for this WABA.
      tags:
      - Subscribed Apps
      parameters:
      - $ref: '#/components/parameters/WabaId'
      responses:
        '200':
          description: App subscribed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: unsubscribeApp
      summary: WhatsApp Unsubscribe App from Webhooks
      description: Unsubscribes the current app from webhook events.
      tags:
      - Subscribed Apps
      parameters:
      - $ref: '#/components/parameters/WabaId'
      responses:
        '200':
          description: App unsubscribed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{waba-id}/assigned_users:
    get:
      operationId: listAssignedUsers
      summary: WhatsApp List Assigned Users
      description: Lists all users assigned to a WhatsApp Business Account.
      tags:
      - Assigned Users
      parameters:
      - $ref: '#/components/parameters/WabaId'
      responses:
        '200':
          description: Users retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        tasks:
                          type: array
                          items:
                            type: string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: assignUser
      summary: WhatsApp Assign User to WABA
      description: Assigns a user with specific tasks to a WhatsApp Business Account.
      tags:
      - Assigned Users
      parameters:
      - $ref: '#/components/parameters/WabaId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - user
              - tasks
              properties:
                user:
                  type: string
                  description: User ID to assign
                tasks:
                  type: array
                  items:
                    type: string
                    enum:
                    - MANAGE
                    - DEVELOP
                    - MANAGE_TEMPLATES
                    - MANAGE_PHONE
                    - VIEW_COST
                    - MANAGE_EXTENSIONS
      responses:
        '200':
          description: User assigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: removeAssignedUser
      summary: WhatsApp Remove Assigned User
      description: Removes a user from a WhatsApp Business Account.
      tags:
      - Assigned Users
      parameters:
      - $ref: '#/components/parameters/WabaId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - user
              properties:
                user:
                  type: string
      responses:
        '200':
          description: User removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{waba-id}/product_catalogs:
    get:
      operationId: listProductCatalogs
      summary: WhatsApp List Product Catalogs
      description: Lists product catalogs connected to a WABA.
      tags:
      - Product Catalogs
      parameters:
      - $ref: '#/components/parameters/WabaId'
      responses:
        '200':
          description: Catalogs retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: connectProductCatalog
      summary: WhatsApp Connect Product Catalog
      description: Connects a product catalog to a WABA.
      tags:
      - Product Catalogs
      parameters:
      - $ref: '#/components/parameters/WabaId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - catalog_id
              properties:
                catalog_id:
                  type: string
      responses:
        '200':
          description: Catalog connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: disconnectProductCatalog
      summary: WhatsApp Disconnect Product Catalog
      description: Disconnects a product catalog from a WABA.
      tags:
      - Product Catalogs
      parameters:
      - $ref: '#/components/parameters/WabaId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - catalog_id
              properties:
                catalog_id:
                  type: string
      responses:
        '200':
          description: Catalog disconnected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: System User Token with whatsapp_business_management permission
  parameters:
    WabaId:
      name: waba-id
      in: path
      required: true
      description: WhatsApp Business Account ID
      schema:
        type: string
  schemas:
    WhatsAppBusinessAccount:
      type: object
      properties:
        id:
          type: string
          example: wamid.abc123
        name:
          type: string
          example: Example Business
        currency:
          type: string
          example: example_value
        timezone_id:
          type: string
          example: wamid.abc123
        country:
          type: string
          example: example_value
        status:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          example: ACTIVE
        business_verification_status:
          type: string
          example: sent
        message_template_namespace:
          type: string
          example: Example Business
        owner_business:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        primary_funding_id:
          type: string
          example: wamid.abc123
        purchase_order_number:
          type: string
          example: example_value
    PhoneNumber:
      type: object
      properties:
        id:
          type: string
          example: wamid.abc123
        display_phone_number:
          type: string
          example: '+15551234567'
        verified_name:
          type: string
          example: Example Business
        quality_rating:
          type: string
          enum:
          - GREEN
          - YELLOW
          - RED
          - UNKNOWN
          example: GREEN
        code_verification_status:
          type: string
          enum:
          - VERIFIED
          - NOT_VERIFIED
          - EXPIRED
          example: VERIFIED
        is_official_business_account:
          type: boolean
          example: true
        name_status:
          type: string
          example: Example Business
        platform_type:
          type: string
          enum:
          - CLOUD_API
          - ON_PREMISE
          - NOT_APPLICABLE
          example: CLOUD_API
        throughput:
          type: object
          properties:
            level:
              type: string
              enum:
              - STANDARD
              - HIGH
        account_mode:
          type: string
          enum:
          - LIVE
          - SANDBOX
          example: LIVE
        messaging_limit_tier:
          type: string
          enum:
          - TIER_1K
          - TIER_10K
          - TIER_100K
          - TIER_UNLIMITED
          example: TIER_1K
    MessageTemplate:
      type: object
      properties:
        id:
          type: string
          example: wamid.abc123
        name:
          type: string
          example: Example Business
        status:
          type: string
          enum:
          - APPROVED
          - PENDING
          - REJECTED
          - PAUSED
          - DISABLED
          example: APPROVED
        category:
          type: string
          enum:
          - AUTHENTICATION
          - MARKETING
          - UTILITY
          example: AUTHENTICATION
        language:
          type: string
          example: en_US
        components:
          type: array
          items:
            $ref: '#/components/schemas/TemplateComponentDefinition'
        parameter_format:
          type: string
          enum:
          - POSITIONAL
          - NAMED
          example: POSITIONAL
        quality_score:
          type: object
          properties:
            score:
              type: string
    CreateTemplateRequest:
      type: object
      required:
      - name
      - language
      - category
      - components
      properties:
        name:
          type: string
          description: Template name (lowercase, underscores only, max 512 chars)
          maxLength: 512
          pattern: '^[a-z][a-z0-9_]*$'
          example: Example Business
        language:
          type: string
          description: Language code
          example: en_US
        category:
          type: string
          enum:
          - AUTHENTICATION
          - MARKETING
          - UTILITY
          example: AUTHENTICATION
        components:
          type: array
          items:
            $ref: '#/components/schemas/TemplateComponentDefinition'
        parameter_format:
          type: string
          enum:
          - POSITIONAL
          - NAMED
          example: POSITIONAL
    TemplateComponentDefinition:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - HEADER
          - BODY
          - FOOTER
          - BUTTONS
          example: HEADER
        format:
          type: string
          enum:
          - TEXT
          - IMAGE
          - VIDEO
          - DOCUMENT
          - LOCATION
          description: Header format type
          example: TEXT
        text:
          type: string
          description: Component text content
          example: Hello from WhatsApp!
        example:
          type: object
          description: Example values for variables
        buttons:
          type: array
          items:
            $ref: '#/components/schemas/TemplateButton'
        add_security_recommendation:
          type: boolean
          description: Authentication templates only
          example: true
        code_expiration_minutes:
          type: integer
          description: Authentication templates only (1-90)
          minimum: 1
          maximum: 90
          example: 42
    TemplateButton:
      type: object
      required:
      - type
      - text
      properties:
        type:
          type: string
          enum:
          - QUICK_REPLY
          - URL
          - PHONE_NUMBER
          - COPY_CODE
          - FLOW
          - OTP
          - CATALOG
          - MPM
          example: QUICK_REPLY
        text:
          type: string
          example: Hello from WhatsApp!
        url:
          type: string
          format: uri
          example: https://example.com/image.jpg
        phone_number:
          type: string
          example: '+15551234567'
        example:
          type: string
          example: example_value
        flow_id:
          type: string
          example: wamid.abc123
        flow_action:
          type: string
          example: example_value
        navigate_screen:
          type: string
          example: example_value
    ConversationAnalytics:
      type: object
      properties:
        conversation_analytics:
          type: object
          properties:
            data:
              type: array
              items:
                type: object
                properties:
                  data_points:
                    type: array
                    items:
                      type: object
                      properties:
                        start:
                          type: integer
                        end:
                          type: integer
                        conversation:
                          type: integer
                        cost:
                          type: number
    TemplateAnalytics:
      type: object
      properties:
        template_analytics:
          type: object
          properties:
            data:
              type: array
              items:
                type: object
                properties:
                  template_id:
                    type: string
                  data_points:
                    type: array
                    items:
                      type: object
                      properties:
                        start:
                          type: integer
                        end:
                          type: integer
                        sent:
                          type: integer
                        delivered:
                          type: integer
                        read:
                          type: integer
                        clicked:
                          type: integer
                        cost:
                          type: number
    CursorPaging:
      type: object
      properties:
        cursors:
          type: object
          properties:
            before:
              type: string
            after:
              type: string
        next:
          type: string
          format: uri
          example: example_value
        previous:
          type: string
          format: uri
          example: example_value
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true