WhatsApp Encrypted Messages 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: Encrypted Messages
  description: 'Payload encryption provides an additional layer of security on top of existing standard TLS/SSL that secures communication between Cloud API and businesses. When enabled, all message requests and message echoes webhooks will undergo encryption using JWE (JSON Web Encryption) format.


    ## Key Features


    - **Additional Security Layer**: Adds payload-level encryption on top of standard TLS/SSL

    - **JWE Format**: Uses JSON Web Encryption standard for encrypting message payloads

    - **Selective Encryption**: Only successful responses are encrypted; errors remain unencrypted

    - **Standard Compatibility**: Encrypted payloads contain the same structure as `/messages` endpoint

    - **Phone-Number Level**: Encryption is configured per phone number within a WABA


    ## Setup Requirements


    1. **Enable Payload Encryption**: Use `POST //settings` to enable encryption

    2. **RSA Key Pair**: Generate and provide a 2048-bit RSA public key (base64 encoded)

    3. **Algorithm Support**: Multiple algorithms supported for content and key encryption

    4. **Access Token**: User Access Token with `whatsapp_business_messaging` permission


    ## Supported Algorithms


    - **Content Encryption**: A128GCM, A256GCM, A128CBC-HS256, A192CBC-HS384, A256CBC-HS512

    - **Key Encryption**: RSA1_5, RSA-OAEP

    - **WhatsApp Standard**: A256GCM + RSA-OAEP for responses and webhooks'
paths:
  /{Version}/{Phone-Number-ID}/messages_encrypted:
    post:
      tags:
      - Encrypted Messages
      summary: Send Encrypted Message
      description: 'Send encrypted messages using JWE (JSON Web Encryption) format. This endpoint provides an additional layer of security on top of existing standard TLS/SSL by accepting pre-encrypted message payloads and returning encrypted responses.


        **Important Notes:**

        - Only successful responses will be encrypted

        - Error responses will be returned unencrypted if the underlying JSON is incorrectly formatted

        - Payload encryption must be enabled for the phone number using the `POST //settings` endpoint

        - The encrypted payload must follow the same structure as the original `/messages` endpoint


        **Prerequisites:**

        - User Access Token with `whatsapp_business_messaging` permission

        - Valid `Phone-Number-ID` for your registered WhatsApp Business account

        - Payload encryption enabled for the phone number

        - Properly formatted JWE token containing encrypted message payload using supported algorithms


        **Supported Algorithms:**

        - **Content Encryption:** A128GCM, A256GCM...'
      operationId: sendEncryptedMessage
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - name: Version
        in: path
        required: true
        description: API version (e.g., v21.0, v22.0)
        schema:
          type: string
          example: v22.0
      - name: Phone-Number-ID
        in: path
        required: true
        description: The ID of the phone number used to send the message. Retrieved from the WhatsApp Business Account.
        schema:
          type: string
          example: '1234567890123456'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EncryptedMessageRequest'
            examples:
              Send Encrypted Text Message:
                summary: Send an encrypted text message
                value:
                  messaging_product: whatsapp
                  encrypted_contents: eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ...
              Send Encrypted Media Message:
                summary: Send an encrypted media message
                value:
                  messaging_product: whatsapp
                  encrypted_contents: eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ.encrypted_media_payload...
              Send Encrypted Template Message:
                summary: Send an encrypted template message
                value:
                  messaging_product: whatsapp
                  encrypted_contents: eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ.encrypted_template_payload...
      responses:
        '200':
          description: Encrypted message sent successfully
          headers:
            Access-Control-Allow-Origin:
              $ref: '#/components/headers/Access-Control-Allow-Origin'
            Alt-Svc:
              $ref: '#/components/headers/Alt-Svc'
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            Connection:
              $ref: '#/components/headers/Connection'
            Content-Length:
              $ref: '#/components/headers/Content-Length'
            Date:
              $ref: '#/components/headers/Date'
            Expires:
              $ref: '#/components/headers/Expires'
            Pragma:
              $ref: '#/components/headers/Pragma'
            Strict-Transport-Security:
              $ref: '#/components/headers/Strict-Transport-Security'
            Vary:
              $ref: '#/components/headers/Vary'
            X-FB-Connection-Quality:
              $ref: '#/components/headers/X-FB-Connection-Quality'
            X-FB-Debug:
              $ref: '#/components/headers/X-FB-Debug'
            facebook-api-version:
              $ref: '#/components/headers/facebook-api-version'
            x-business-use-case-usage:
              $ref: '#/components/headers/x-business-use-case-usage'
            x-fb-request-id:
              $ref: '#/components/headers/x-fb-request-id'
            x-fb-rev:
              $ref: '#/components/headers/x-fb-rev'
            x-fb-trace-id:
              $ref: '#/components/headers/x-fb-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EncryptedMessageResponse'
              examples:
                Encrypted Message Success Response:
                  summary: Successful encrypted message response
                  value:
                    encrypted_contents: eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ.encrypted_response_payload...
                Encrypted Text Message Response:
                  summary: Response for encrypted text message
                  value:
                    encrypted_contents: eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ...
                Encrypted Media Message Response:
                  summary: Response for encrypted media message
                  value:
                    encrypted_contents: eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ.media_response...
        '400':
          description: 'Bad Request - Invalid JWE token or malformed request. Note: Error responses are returned unencrypted even when payload encryption is enabled.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Invalid JWE Token:
                  summary: Invalid JWE token format
                  value:
                    error:
                      message: Invalid JWE token format
                      type: OAuthException
                      code: 400
                      error_subcode: 1234567
                Missing Required Fields:
                  summary: Missing required fields
                  value:
                    error:
                      message: Missing required field messaging_product
                      type: OAuthException
                      code: 400
                      error_subcode: 1234568
        '401':
          description: 'Unauthorized - Invalid access token. Note: Error responses are returned unencrypted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Invalid Access Token:
                  summary: Invalid access token
                  value:
                    error:
                      message: Invalid OAuth access token
                      type: OAuthException
                      code: 190
                      error_subcode: 460
        '403':
          description: 'Forbidden - Insufficient permissions. Note: Error responses are returned unencrypted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Insufficient Permissions:
                  summary: Insufficient permissions
                  value:
                    error:
                      message: Insufficient permissions for this operation
                      type: OAuthException
                      code: 403
                      error_subcode: 1234569
        '429':
          description: 'Too Many Requests - Rate limit exceeded. Note: Error responses are returned unencrypted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Rate Limit Exceeded:
                  summary: Rate limit exceeded
                  value:
                    error:
                      message: Rate limit exceeded
                      type: OAuthException
                      code: 4
                      error_subcode: 2018001
        '500':
          description: 'Internal Server Error. Note: Error responses are returned unencrypted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal Server Error:
                  summary: Internal server error
                  value:
                    error:
                      message: An internal error occurred
                      type: OAuthException
                      code: 2
                      error_subcode: 1675030
      security:
      - bearerAuth: []
components:
  schemas:
    EncryptedMessageRequest:
      type: object
      additionalProperties: false
      properties:
        messaging_product:
          type: string
          description: Messaging service used for the request. Use whatsapp.
          example: whatsapp
          enum:
          - whatsapp
        encrypted_contents:
          type: string
          description: JWE payload with encrypted messages structure. This should be a valid JWE token containing the encrypted message payload.
          example: eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ...
      required:
      - messaging_product
      - encrypted_contents
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      required:
      - error
    EncryptedMessageResponse:
      type: object
      properties:
        encrypted_contents:
          type: string
          description: JWE payload with encrypted messages response structure. Contains the encrypted response from the WhatsApp Business API.
          example: eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ...
      required:
      - encrypted_contents
    ErrorObject:
      type: object
      properties:
        message:
          type: string
          description: Human-readable description of the error
        type:
          type: string
          description: Error type classification
        code:
          type: integer
          description: Numeric error code
      required:
      - message
      - type
      - code
  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
    ContentType:
      name: Content-Type
      in: header
      description: Media type of the request body
      required: true
      schema:
        type: string
        enum:
        - application/json
        - application/x-www-form-urlencoded
        - multipart/form-data
        default: application/json
        example: application/json
  headers:
    Content-Length:
      schema:
        type: string
        example: '25'
      description: Size of the response body in bytes
    x-fb-request-id:
      schema:
        type: string
        example: AGaOBl2yM-g8gdON-dhzl5y
      description: Unique identifier for the request for debugging purposes
    Expires:
      schema:
        type: string
        example: Sat, 01 Jan 2000 00:00:00 GMT
      description: Expiration date for cached responses
    Access-Control-Allow-Origin:
      schema:
        type: string
        example: '*'
      description: CORS policy allowing access from any origin
    x-fb-trace-id:
      schema:
        type: string
        example: E7riEe9OW2e
      description: Facebook trace identifier for request tracking
    Vary:
      schema:
        type: string
        example: Accept-Encoding
      description: Headers that affect caching and content negotiation
    x-business-use-case-usage:
      schema:
        type: string
        example: '{"102290129340398":[{"type":"whatsapp_business_management","call_count":1,"total_cputime":1,"total_time":1,"estimated_time_to_regain_access":0},{"type":"whatsapp","call_count":1,"total_cputime":1,"total_time":1,"estimated_time_to_regain_access":0}]}'
      description: Business use case usage metrics and rate limiting information
    X-FB-Debug:
      schema:
        type: string
        example: 52zkUgodnaVRhbBE+3RiGz6TnmjmDEGunwYd+vKSc4synE+Xii//dy6twB/7yKgOJiMUuV0OF248UAZ1qL3v0A==
      description: Facebook debug information for troubleshooting
    Connection:
      schema:
        type: string
        example: keep-alive
      description: Connection management directive
    facebook-api-version:
      schema:
        type: string
        example: v22.0
      description: Facebook Graph API version used for the request
    Strict-Transport-Security:
      schema:
        type: string
        example: max-age=15552000; preload
      description: HSTS header enforcing HTTPS connections
    X-FB-Connection-Quality:
      schema:
        type: string
        example: EXCELLENT; q=0.9, rtt=7, rtx=0, c=10, mss=1380, tbw=372, tp=-1, tpl=-1, uplat=527, ullat=0
      description: Facebook connection quality metrics
    Pragma:
      schema:
        type: string
        example: no-cache
      description: Legacy cache control directive
    Alt-Svc:
      schema:
        type: string
        example: h3=":443"; ma=86400
      description: Alternative service advertisement for HTTP/3
    Cache-Control:
      schema:
        type: string
        example: private, no-cache, no-store, must-revalidate
      description: Cache control directives for the response
    Date:
      schema:
        type: string
        example: Fri, 24 Jan 2025 00:48:41 GMT
      description: Date and time when the response was generated
    x-fb-rev:
      schema:
        type: string
        example: '1019544279'
      description: Facebook internal revision number
  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

        '