WhatsApp WhatsApp Business 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 API
  description: WhatsApp Business Platform APIs for messaging, account management, and partner integrations.
paths:
  /{Version}/{Application-ID}/whatsapp_business_solution:
    post:
      summary: Create Multi-Partner Solution
      description: 'Create a new Multi-Partner Solution that defines permission distribution between

        a solution owner app and a partner app for WhatsApp Business messaging collaboration.


        **Permission Logic:**

        - Only one partner (owner or partner app) can have MESSAGING permission

        - At least one partner must have MESSAGING permission

        - Both partners automatically receive default solution partner permissions

        - Empty permission arrays indicate no configurable permissions for that partner


        **Solution Lifecycle:**

        - Solutions are created with INITIATED status

        - Require subsequent activation workflow through solution management

        - Can be managed through Partner Dashboard or solution management APIs


        **Rate Limiting:**

        Standard Graph API rate limits apply with WhatsApp Business Management throttling.

        Use appropriate retry logic with exponential backoff for rate-limited requests.


        **Validation:**

        - Partner app must be accessible and have proper capabilities

        - Permission combinations are validated against business logic rules

        - Solution names must meet length and content requirements'
      operationId: createWhatsAppBusinessSolution
      tags:
      - WhatsApp Business API
      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 API behavior and available features.

          Use the latest stable version for new integrations.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: Application-ID
        in: path
        required: true
        description: 'Your Facebook Application ID that will serve as the solution owner.

          This application will be the primary owner of the created solution.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsAppBusinessSolutionCreateRequest'
            examples:
              owner_has_messaging:
                summary: Owner app has messaging permission
                description: Solution where the owner app handles messaging operations
                value:
                  owner_permissions:
                  - MESSAGING
                  partner_app_id: '9876543210987654'
                  partner_permissions: []
                  solution_name: Owner-Managed Messaging Solution
              partner_has_messaging:
                summary: Partner app has messaging permission
                description: Solution where the partner app handles messaging operations
                value:
                  owner_permissions: []
                  partner_app_id: '9876543210987654'
                  partner_permissions:
                  - MESSAGING
                  solution_name: Partner-Managed Messaging Solution
      responses:
        '200':
          description: 'Multi-Partner Solution created successfully. The solution is created with INITIATED status

            and can be managed through subsequent API calls or Partner Dashboard.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsAppBusinessSolutionCreateResponse'
              examples:
                successful_creation:
                  summary: Successful solution creation
                  value:
                    solution_id: '1234567890123456'
        '400':
          description: 'Bad Request - Invalid parameters provided. This includes validation failures

            for permission logic, malformed IDs, or constraint violations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                invalid_permissions:
                  summary: Invalid permission combination
                  value:
                    error:
                      message: Invalid Permissions for either of the partners
                      type: OAuthException
                      code: 100
                      fbtrace_id: A1B2C3D4E5F6G7H8
                invalid_app_id:
                  summary: Invalid partner application ID
                  value:
                    error:
                      message: Invalid parameter value for partner_app_id
                      type: OAuthException
                      code: 100
                      fbtrace_id: A1B2C3D4E5F6G7H8
        '401':
          description: 'Unauthorized - Authentication required or invalid access token provided.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                invalid_token:
                  summary: Invalid or expired access token
                  value:
                    error:
                      message: Invalid OAuth access token
                      type: OAuthException
                      code: 190
                      error_subcode: 463
                      fbtrace_id: A1B2C3D4E5F6G7H8
        '403':
          description: 'Forbidden - Insufficient permissions or missing required capabilities.

            App may lack whatsapp_business_management permission or required granular scopes.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                insufficient_permissions:
                  summary: Missing required permissions
                  value:
                    error:
                      message: Insufficient permissions for this operation
                      type: OAuthException
                      code: 200
                      fbtrace_id: A1B2C3D4E5F6G7H8
                      error_user_title: Permission Denied
                      error_user_msg: Your app doesn't have permission to access this resource
        '404':
          description: 'Not Found - Application ID not found or not accessible to the requesting entity.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                app_not_found:
                  summary: Application not found
                  value:
                    error:
                      message: Application not found
                      type: GraphMethodException
                      code: 803
                      fbtrace_id: A1B2C3D4E5F6G7H8
        '422':
          description: 'Unprocessable Entity - Request is well-formed but contains business logic violations.

            This includes cases where both partners have MESSAGING permission or neither has it.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                business_logic_violation:
                  summary: Business logic constraint violation
                  value:
                    error:
                      message: Invalid Permissions for either of the partners
                      type: GraphMethodException
                      code: 100
                      fbtrace_id: A1B2C3D4E5F6G7H8
        '429':
          description: 'Too Many Requests - Rate limiting threshold exceeded.

            Implement exponential backoff retry logic.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                rate_limited:
                  summary: Rate limit exceeded
                  value:
                    error:
                      message: Application request limit reached
                      type: OAuthException
                      code: 4
                      is_transient: true
                      fbtrace_id: A1B2C3D4E5F6G7H8
        '500':
          description: 'Internal Server Error - Unexpected server-side error occurred.

            These errors are typically transient and should be retried.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                server_error:
                  summary: Internal server error
                  value:
                    error:
                      message: An unexpected error occurred
                      type: GraphMethodException
                      code: 2
                      is_transient: true
                      fbtrace_id: A1B2C3D4E5F6G7H8
      security:
      - bearerAuth: []
  /{Version}/{Solution-ID}/accept:
    post:
      summary: Accept Multi-Partner Solution Invitation
      description: 'Accept an invitation to participate in a Multi-Partner Solution as a partner application.

        This endpoint transitions the partner''s status from NOTIFICATION_SENT to ACCEPTED,

        enabling the solution to progress toward ACTIVE status once all required partners accept.


        **Use Cases:**

        - Accept partnership invitations for Multi-Partner Solutions

        - Activate partner participation in existing solutions

        - Confirm partner app''s commitment to solution terms and conditions

        - Enable solution workflow progression from INITIATED to ACTIVE status


        **Business Logic:**

        - Only invited partner apps can accept solution invitations

        - Solution must be in INITIATED status to accept partnerships

        - Partner status transitions from NOTIFICATION_SENT to ACCEPTED

        - Solution may become ACTIVE once all required partners accept

        - Acceptance creates formal partnership agreement between apps


        **Rate Limiting:**

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


        **Validation:**

        - Partner app must have received a valid solution invitation

        - Solution must exist and be accessible to the partner app

        - Partner app must have proper permissions and capabilities

        - Acceptance request must include valid partner app identification'
      operationId: acceptWhatsAppBusinessSolution
      tags:
      - WhatsApp Business API
      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: Solution-ID
        in: path
        required: true
        description: 'ID of the Multi-Partner Solution to accept. This ID is provided in the original

          invitation and can be found in partner notifications or solution management interfaces.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsAppBusinessSolutionAcceptRequest'
            examples:
              partner_acceptance:
                summary: Partner app accepting solution invitation
                description: Standard acceptance request from an invited partner application
                value:
                  partner_app_id: '9876543210987654'
                  log_session_id: session_12345_accept_solution
              minimal_acceptance:
                summary: Minimal acceptance request
                description: Acceptance request with only required fields
                value:
                  partner_app_id: '9876543210987654'
      responses:
        '200':
          description: 'Multi-Partner Solution invitation accepted successfully. The partner''s status has been

            updated to ACCEPTED and the solution may progress toward ACTIVE status.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsAppBusinessSolutionAcceptResponse'
              examples:
                successful_acceptance:
                  summary: Successful solution acceptance
                  value:
                    solution_id: '1234567890123456'
                    partner_status: ACCEPTED
                    success: true
                    message: Solution partnership accepted successfully
                    update_time: '2024-01-15T10:30:00Z'
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: partner_app_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 not invited to solution
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Your app is not invited to participate in this Multi-Partner Solution
                  type: OAuthException
                  code: 200
                  error_subcode: 1349175
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Permission Denied
                  error_user_msg: Your app doesn't have permission to accept this solution invitation
        '404':
          description: Not Found - Solution ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Multi-Partner Solution not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Solution cannot be accepted in current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Solution cannot be accepted: solution is not in INITIATED status'
                  type: GraphMethodException
                  code: 100
                  error_subcode: 2207051
                  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:
    WhatsAppBusinessSolutionCreateResponse:
      type: object
      description: Successful response containing the created solution identifier
      required:
      - solution_id
      properties:
        solution_id:
          type: string
          description: 'Unique identifier for the newly created Multi-Partner Solution.

            Use this ID for subsequent solution management operations.

            '
          pattern: ^[0-9]+$
          example: '1234567890123456'
    WhatsAppBusinessSolutionAcceptRequest:
      type: object
      description: Request payload for accepting a Multi-Partner Solution invitation
      required:
      - partner_app_id
      properties:
        partner_app_id:
          type: string
          description: 'ID of the partner application accepting the solution invitation.

            This must match the app ID that received the original invitation.

            '
          pattern: ^[0-9]+$
          example: '9876543210987654'
        log_session_id:
          type: string
          description: 'Optional session identifier for logging and debugging purposes.

            Used to track the acceptance flow across multiple API calls.

            '
          example: session_12345_accept_solution
    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
    WhatsAppBusinessSolutionCreateRequest:
      type: object
      description: Request payload for creating a Multi-Partner Solution
      required:
      - owner_permissions
      - partner_app_id
      - partner_permissions
      - solution_name
      properties:
        owner_permissions:
          type: array
          description: 'Configurable permissions granted to the solution owner app. Currently supports

            only MESSAGING permission. Use empty array if owner should not have configurable permissions.

            '
          items:
            $ref: '#/components/schemas/WhatsAppBusinessAccountConfigurablePermissionTask'
          maxItems: 1
          example:
          - MESSAGING
        partner_app_id:
          type: string
          description: 'Facebook Application ID of the partner app that will participate in this solution.

            Must be a valid application ID accessible to the requesting entity.

            '
          pattern: ^[0-9]+$
          example: '9876543210987654'
        partner_permissions:
          type: array
          description: 'Configurable permissions granted to the partner app. Currently supports

            only MESSAGING permission. Use empty array if partner should not have configurable permissions.

            '
          items:
            $ref: '#/components/schemas/WhatsAppBusinessAccountConfigurablePermissionTask'
          maxItems: 1
          example: []
        solution_name:
          type: string
          description: 'Human-readable name for the Multi-Partner Solution. Used for identification

            and management purposes in partner dashboards and solution management interfaces.

            '
          minLength: 2
          maxLength: 75
          example: E-commerce Integration Solution
    WhatsAppBusinessSolutionAcceptResponse:
      type: object
      description: Successful response confirming solution acceptance
      required:
      - solution_id
      - partner_status
      - success
      properties:
        solution_id:
          type: string
          description: ID of the Multi-Partner Solution that was accepted
          example: '1234567890123456'
        partner_status:
          $ref: '#/components/schemas/WhatsAppBusinessSolutionPartnerStatus'
        success:
          type: boolean
          description: Indicates whether the acceptance was successful
          example: true
        message:
          type: string
          description: Human-readable confirmation message
          example: Solution partnership accepted successfully
        update_time:
          type: string
          format: date-time
          description: Timestamp when the acceptance was processed
          example: '2024-01-15T10:30:00Z'
    WhatsAppBusinessAccountConfigurablePermissionTask:
      type: string
      description: 'Configurable permission tasks for WhatsApp Business Account access in Multi-Partner Solutions.

        Currently only MESSAGING permission is configurable through this API.

        '
      enum:
      - MESSAGING
      example: MESSAGING
    WhatsAppBusinessSolutionPartnerStatus:
      type: string
      description: Current status of the partner's participation in the Multi-Partner Solution
      enum:
      - DRAFT
      - INITIATED
      - NOTIFICATION_SENT
      - ACCEPTED
      - REJECTED
      - DEACTIVATED
      example: ACCEPTED
  parameters:
    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
    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...
  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

        '