WhatsApp WhatsApp Business Account API

openapi: 3.2.0
info:
  title: Meta Graph API - Application Connected Client Businesses…
  version: v23.0
  description: 'API for retrieving connected client businesses associated with a Meta application.


    This endpoint allows applications to retrieve information about businesses that have

    established client connections through the application. This is essential for managing

    business relationships and understanding client business configurations.'
  contact:
    name: Meta Business Platform Team
    url: https://developers.facebook.com/support
  license:
    name: Meta Platform Terms
    url: https://developers.facebook.com/terms
  termsOfService: https://developers.facebook.com/terms
servers:
- url: https://graph.facebook.com
  description: Production Graph API server
- url: https://graph.facebook.com
- url: https://graph.facebook.com
  description: WhatsApp Business Cloud API
- url: https://graph.facebook.com
  description: Meta Graph API production server
tags:
- name: WhatsApp Business Account
  description: APIs for managing WhatsApp Business Account details and configuration
paths:
  /{Version}/{WABA-ID}:
    get:
      summary: Get WhatsApp Business Account Details
      description: 'Retrieve comprehensive details about a WhatsApp Business Account, including its

        configuration, status, and settings.


        **Use Cases:**

        - Retrieve WhatsApp Business Account configuration and details

        - Monitor account status and verification state

        - Check account ownership and business information

        - Validate account state before messaging operations


        **Rate Limiting:**

        Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.


        **Caching:**

        Account details can be cached for moderate periods, but verification status may change.

        Implement appropriate cache invalidation strategies.'
      operationId: getWhatsAppBusinessAccountDetails
      tags:
      - WhatsApp Business Account
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: Version
        in: path
        required: true
        description: 'Graph API version to use for this request. Determines the API behavior and available features.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: WABA-ID
        in: path
        required: true
        description: 'Your WhatsApp Business Account ID. This ID is provided when you create the account

          and can be found in your WhatsApp Manager or through business management APIs.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      - name: fields
        in: query
        required: false
        description: 'Comma-separated list of fields to include in the response. If not specified,

          default fields will be returned (id, name). Available fields: id, name, timezone_id,

          message_template_namespace, account_review_status, business_verification_status,

          country, ownership_type, primary_business_location

          '
        schema:
          type: string
        example: id,name,timezone_id,account_review_status
      responses:
        '200':
          description: Successfully retrieved WhatsApp Business Account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsAppBusinessAccount'
              examples:
                verified_account:
                  summary: Verified WhatsApp Business Account with full details
                  value:
                    id: '1234567890123456'
                    name: My Business WhatsApp Account
                    timezone_id: '1'
                    message_template_namespace: ba30dd89_2ebd_41e4_b805_f2c05ae04cc9
                    account_review_status: APPROVED
                    business_verification_status: VERIFIED
                    country: US
                    ownership_type: SELF_OWNED
                    primary_business_location: US
                basic_account:
                  summary: Basic WhatsApp Business Account with minimal details
                  value:
                    id: '2345678901234567'
                    name: Test Business Account
                    timezone_id: '1'
                    account_review_status: PENDING
                    business_verification_status: UNVERIFIED
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: whatsapp_business_account_id must be a valid numeric string'
                  type: OAuthException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '401':
          description: Unauthorized - Invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
                  error_subcode: 463
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '403':
          description: Forbidden - Insufficient permissions or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Your app doesn't have permission to access this WhatsApp Business Account
                  type: OAuthException
                  code: 200
                  error_subcode: 1349174
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Permission Denied
                  error_user_msg: Your app doesn't have permission to access this resource
        '404':
          description: Not Found - WhatsApp Business Account ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business Account not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request parameters are valid but cannot be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: The requested fields are not available for this account
                  type: GraphMethodException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Application request limit reached
                  type: OAuthException
                  code: 4
                  error_subcode: 2446079
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: An unexpected error occurred. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
    post:
      summary: Update WhatsApp Business Account
      description: 'Update configuration and settings for a WhatsApp Business Account.


        **Use Cases:**

        - Update WhatsApp Business Account name and configuration

        - Modify account settings and preferences

        - Update business information and verification details


        **Rate Limiting:**

        Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.'
      operationId: updateWhatsAppBusinessAccount
      tags:
      - WhatsApp Business Account
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: Version
        in: path
        required: true
        description: 'Graph API version to use for this request. Determines the API behavior and available features.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: WABA-ID
        in: path
        required: true
        description: 'Your WhatsApp Business Account ID. This ID is provided when you create the account

          and can be found in your WhatsApp Manager or through business management APIs.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Updated name for the WhatsApp Business Account
                  minLength: 1
                  maxLength: 100
                  example: Updated Business Name
                timezone_id:
                  type: string
                  description: Updated timezone identifier for the WhatsApp Business Account
                  example: '2'
            examples:
              update_name:
                summary: Update account name
                value:
                  name: Updated Business Name
              update_timezone:
                summary: Update timezone
                value:
                  timezone_id: '2'
      responses:
        '200':
          description: Successfully updated WhatsApp Business Account
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
              example:
                success: true
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: name must be a non-empty string'
                  type: OAuthException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '401':
          description: Unauthorized - Invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
                  error_subcode: 463
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '403':
          description: Forbidden - Insufficient permissions or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Your app doesn't have permission to modify this WhatsApp Business Account
                  type: OAuthException
                  code: 200
                  error_subcode: 1349174
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Permission Denied
                  error_user_msg: Your app doesn't have permission to modify this resource
        '404':
          description: Not Found - WhatsApp Business Account ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business Account not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request parameters are valid but cannot be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: The account cannot be updated at this time
                  type: GraphMethodException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Application request limit reached
                  type: OAuthException
                  code: 4
                  error_subcode: 2446079
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: An unexpected error occurred. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
components:
  schemas:
    MessageTemplate:
      type: object
      description: Message template information
      properties:
        id:
          type: string
          description: Template ID
          example: template_123456
        name:
          type: string
          description: Template name
          example: welcome_message
        status:
          type: string
          enum:
          - APPROVED
          - PENDING
          - REJECTED
          - DISABLED
          example: APPROVED
    PhoneNumber:
      type: object
      description: Phone number associated with the WABA
      properties:
        id:
          type: string
          description: Phone number ID
          example: '1234567890123456'
        display_phone_number:
          type: string
          description: Formatted phone number for display
          example: +1 (555) 123-4567
        verified_name:
          type: string
          description: Verified business name for the phone number
          example: Example Business
    OwnershipType:
      type: string
      description: Type of ownership for the WhatsApp Business Account
      enum:
      - SELF_OWNED
      - CLIENT_OWNED
      - AGENCY_OWNED
      example: CLIENT_OWNED
    GraphAPIError:
      type: object
      description: Standard Graph API error response
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          - type
          - code
          properties:
            message:
              type: string
              description: Human-readable error message
              example: Invalid parameter
            type:
              type: string
              description: Error category type
              example: OAuthException
            code:
              type: integer
              description: Numeric error code
              example: 100
            error_subcode:
              type: integer
              description: More specific error subcode when available
              example: 33
            fbtrace_id:
              type: string
              description: Unique identifier for debugging and support requests with Meta
              example: AXsgnV2Cm3ZMGF3dF_cfYIn
            is_transient:
              type: boolean
              description: Indicates whether this error is temporary and the request should be retried
              example: false
            error_user_title:
              type: string
              description: User-friendly error title for display purposes
              example: Permission Denied
            error_user_msg:
              type: string
              description: User-friendly error message for display purposes
              example: Your app doesn't have permission to access this resource
    WhatsAppBusinessAccount:
      type: object
      description: WhatsApp Business Account details and configuration
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Unique identifier for the WhatsApp Business Account
          example: '1234567890123456'
        name:
          type: string
          description: Human-readable name of the WhatsApp Business Account
          minLength: 1
          maxLength: 255
          example: My WhatsApp Business Account
        account_review_status:
          $ref: '#/components/schemas/AccountReviewStatus'
        purchase_order_number:
          type: string
          description: Purchase order number associated with the account
          example: PO-2023-001234
        audiences:
          type: array
          description: List of audience segments associated with the account
          items:
            type: string
          example:
          - customers
          - prospects
        ownership_type:
          $ref: '#/components/schemas/OwnershipType'
        subscribed_apps:
          type: array
          description: List of applications subscribed to this WABA
          items:
            $ref: '#/components/schemas/SubscribedApp'
        business_verification_status:
          $ref: '#/components/schemas/BusinessVerificationStatus'
        country:
          type: string
          description: Country code where the WABA is registered
          pattern: ^[A-Z]{2}$
          example: US
        currency:
          type: string
          description: Currency code for the WABA
          pattern: ^[A-Z]{3}$
          example: USD
        timezone_id:
          type: string
          description: Timezone identifier for the WABA
          example: '1'
        on_behalf_of_business_info:
          $ref: '#/components/schemas/OnBehalfOfBusinessInfo'
        schedules:
          type: array
          description: Business hours and scheduling information
          items:
            $ref: '#/components/schemas/BusinessSchedule'
        is_enabled_for_insights:
          type: boolean
          description: Whether insights are enabled for this WABA
          example: true
        dcc_config:
          $ref: '#/components/schemas/DCCConfig'
        message_templates:
          type: array
          description: Message templates associated with the WABA
          items:
            $ref: '#/components/schemas/MessageTemplate'
        phone_numbers:
          type: array
          description: Phone numbers associated with the WABA
          items:
            $ref: '#/components/schemas/PhoneNumber'
    BusinessSchedule:
      type: object
      description: Business hours schedule information
      properties:
        day_of_week:
          type: string
          enum:
          - MONDAY
          - TUESDAY
          - WEDNESDAY
          - THURSDAY
          - FRIDAY
          - SATURDAY
          - SUNDAY
          example: MONDAY
        open_time:
          type: string
          description: Opening time in HH:MM format
          pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
          example: 09:00
        close_time:
          type: string
          description: Closing time in HH:MM format
          pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
          example: '17:00'
    DCCConfig:
      type: object
      description: Data and Content Control configuration
      properties:
        enabled:
          type: boolean
          description: Whether DCC is enabled
          example: true
        policy_url:
          type: string
          description: URL to the DCC policy
          example: https://example.com/dcc-policy
    SubscribedApp:
      type: object
      description: Application subscribed to the WABA
      properties:
        id:
          type: string
          description: Application ID
          example: '9876543210987654'
        name:
          type: string
          description: Application name
          example: WhatsApp Integration App
    OnBehalfOfBusinessInfo:
      type: object
      description: Information about the business on whose behalf the WABA operates
      properties:
        id:
          type: string
          description: Business ID
          example: '5678901234567890'
        name:
          type: string
          description: Business name
          example: Partner Business Inc
    AccountReviewStatus:
      type: string
      description: Review status of the WhatsApp Business Account
      enum:
      - APPROVED
      - PENDING
      - REJECTED
      - RESTRICTED
      example: APPROVED
    BusinessVerificationStatus:
      type: string
      description: Verification status of the connected client business
      enum:
      - VERIFIED
      - UNVERIFIED
      - PENDING
      - REJECTED
      example: VERIFIED
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: 'Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.

        '
      required: true
      schema:
        type: string
        pattern: ^Bearer\s+[A-Za-z0-9\-_.]+.*$
        example: Bearer EAABwzLixnjYBOzYmNMJJGfHq9DgNh...
    UserAgent:
      name: User-Agent
      in: header
      description: The user agent string identifying the client software making the request.
      required: false
      schema:
        type: string
        default: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
        pattern: ^[a-zA-Z0-9\-_]+\/[0-9]+\.[0-9]+\.[0-9]+(;[a-zA-Z0-9\-=\.]+)?(\s+[a-zA-Z0-9\-_]+\/[0-9\-\.]+)?$
        example: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'System user access token with whatsapp_business_management permission. Format: Bearer YOUR_SYSTEM_USER_ACCESS_TOKEN

        '