WhatsApp Business Encryption 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: Business Encryption
  description: APIs for managing WhatsApp Business Account encryption configuration
paths:
  /{Version}/{Phone-Number-ID}/whatsapp_business_encryption:
    get:
      summary: Get Business Encryption Public Key
      description: 'Retrieve the current business public key and its signature verification status.


        This endpoint returns the public key that is currently configured for encrypting

        message payloads and indicates whether the stored signature is valid or has a mismatch.


        **Use Cases:**

        - Verify current encryption configuration

        - Check public key signature validation status

        - Retrieve public key for client-side encryption setup

        - Monitor encryption key status for security compliance


        **Rate Limiting:**

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


        **Caching:**

        Public key information can be cached for moderate periods, but signature status

        may change and should be checked regularly for security validation.'
      operationId: getBusinessEncryptionPublicKey
      tags:
      - Business Encryption
      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: Phone-Number-ID
        in: path
        required: true
        description: 'Your WhatsApp Business phone number ID. This ID represents the phone number

          entity and can be obtained from your WhatsApp Business Account phone numbers list.

          '
        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,

          all available fields will be returned.

          Available fields: business_public_key, business_public_key_signature_status

          '
        schema:
          type: string
        example: business_public_key,business_public_key_signature_status
      responses:
        '200':
          description: Successfully retrieved business encryption public key information
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WhatsAppBusinessEncryptionInfo'
              examples:
                valid_key:
                  summary: Valid public key with verified signature
                  value:
                    data:
                    - business_public_key: '-----BEGIN PUBLIC KEY-----

                        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...

                        -----END PUBLIC KEY-----

                        '
                      business_public_key_signature_status: VALID
                mismatch_key:
                  summary: Public key with signature mismatch
                  value:
                    data:
                    - business_public_key: ' '
                      business_public_key_signature_status: MISMATCH
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: phone_number_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 phone number
                  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 - Phone number ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business phone number 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 phone number
                  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: Set Business Encryption Public Key
      description: 'Upload and configure a business public key for message payload encryption.


        This endpoint accepts a business public key in PEM format, validates it,

        and stores it with a cryptographic signature for future use in encrypting

        message payloads and data channel requests.


        **Use Cases:**

        - Initial setup of encryption for WhatsApp Business messaging

        - Update existing public key for key rotation

        - Enable secure payload encryption for sensitive business communications

        - Configure encryption keys for compliance requirements


        **Key Requirements:**

        - Must be a valid RSA public key in PEM format

        - Key must meet Meta''s security standards for encryption

        - Only one active public key per phone number at a time

        - Previous keys are replaced when new ones are uploaded


        **Rate Limiting:**

        Standard Graph API rate limits apply. Key uploads may have additional

        security-related rate limiting to prevent abuse.'
      operationId: setBusinessEncryptionPublicKey
      tags:
      - Business Encryption
      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: Phone-Number-ID
        in: path
        required: true
        description: 'Your WhatsApp Business phone number ID. This ID represents the phone number

          entity and can be obtained from your WhatsApp Business Account phone numbers list.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/WhatsAppBusinessEncryptionUploadRequest'
            examples:
              upload_key:
                summary: Upload business public key
                value:
                  business_public_key: '-----BEGIN PUBLIC KEY-----

                    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...

                    -----END PUBLIC KEY-----

                    '
      responses:
        '200':
          description: Successfully uploaded and configured business encryption public key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsAppBusinessEncryptionUploadResponse'
              examples:
                success:
                  summary: Successful key upload
                  value:
                    success: true
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                invalid_key:
                  summary: Invalid public key format
                  value:
                    error:
                      message: Business public key is invalid
                      type: OAuthException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                      error_user_title: Invalid Public Key
                      error_user_msg: The provided public key format is invalid
                missing_parameter:
                  summary: Missing required parameter
                  value:
                    error:
                      message: 'Missing required parameter: business_public_key'
                      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 encryption settings for this WhatsApp Business phone number
                  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 - Phone number ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business phone number 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: Phone number is not eligible for encryption configuration
                  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:
  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
  schemas:
    WhatsAppBusinessEncryptionInfo:
      type: object
      description: Business encryption public key information and verification status
      required:
      - business_public_key
      - business_public_key_signature_status
      properties:
        business_public_key:
          type: string
          description: 'The business public key used for encrypting message payloads.

            This key is used to encrypt data channel requests and responses.

            '
          example: '-----BEGIN PUBLIC KEY-----

            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...

            -----END PUBLIC KEY-----

            '
        business_public_key_signature_status:
          $ref: '#/components/schemas/BusinessPublicKeyVerificationStatus'
    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
    BusinessPublicKeyVerificationStatus:
      type: string
      description: Status of business public key signature verification
      enum:
      - VALID
      - MISMATCH
      example: VALID
    WhatsAppBusinessEncryptionUploadRequest:
      type: object
      description: Request payload for uploading business public key
      required:
      - business_public_key
      properties:
        business_public_key:
          type: string
          description: 'The business public key in PEM format to be uploaded and signed.

            Must be a valid RSA public key that will be used for payload encryption.

            '
          example: '-----BEGIN PUBLIC KEY-----

            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...

            -----END PUBLIC KEY-----

            '
    WhatsAppBusinessEncryptionUploadResponse:
      type: object
      description: Response after successful public key upload
      required:
      - success
      properties:
        success:
          type: boolean
          description: Indicates whether the public key was successfully uploaded and signed
          example: true
  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

        '