WhatsApp Call Permissions 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: Call Permissions
  description: 'Use the **`/{Phone-Number-ID}/call_permissions`** endpoint to check whether you have permission to call a specific WhatsApp user and understand what calling-related actions are available.


    ## Prerequisites


    * User Access Token with **`whatsapp_business_messaging`** permission

    * `phone-number-id` for your registered WhatsApp Business Account

    * WhatsApp Cloud API Calling must be enabled for your phone number


    ## Permission Status Types


    - **granted**: You have active permission to call this user

    - **pending**: A permission request has been sent but not yet approved by the user

    - **denied**: The user has denied call permissions for your business

    - **expired**: Previous permission has expired and needs to be renewed


    ## Available Actions


    - **start_call**: Initiate a new call to this user (available when permission is granted)

    - **send_call_permission_request**: Send a permission request to this user (available when permission is denied or expired)


    ## Rate Limiting


    This endpoint has specific rate limits to prevent abuse. Exceeding the rate limit will result in error code 4 with subcode 2390008.


    ## Error Handling


    - **403 Forbidden**: Calling is not enabled for your phone number - **429 Too Many Requests**: Rate limit exceeded for permission checks - **400 Bad Request**: Missing or invalid `user_wa_id` parameter'
paths:
  /{Version}/{Phone-Number-ID}/call_permissions:
    parameters:
    - name: Version
      in: path
      required: true
      schema:
        type: string
        example: v21.0
      description: The API version to use
    - name: Phone-Number-ID
      in: path
      required: true
      schema:
        type: string
        example: '102290129340398'
      description: The ID of the phone number registered with your WhatsApp Business Account
    get:
      tags:
      - Call Permissions
      summary: Check Call Permissions
      description: 'Check whether you have permission to call a WhatsApp user and what actions are available. This endpoint returns the current permission status for calling a specific user, along with available actions and their limits.


        **Permission Status:**

        - `granted`: You have active permission to call this user - `pending`: A permission request has been sent but not yet approved - `denied`: The user has denied call permissions - `expired`: Previous permission has expired


        **Available Actions:**

        - `start_call`: Initiate a new call to this user - `send_call_permission_request`: Send a permission request to this user


        **Error Handling:**

        This endpoint may return various error codes including rate limiting errors if too many permission checks are made within a short period.'
      operationId: checkCallPermissions
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - name: user_wa_id
        in: query
        required: true
        schema:
          type: string
          example: '14085551234'
        description: The WhatsApp ID of the user you want to check call permissions for
      responses:
        '200':
          description: Call Permissions Check Success
          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/CallPermissionCheckResponsePayload'
              examples:
                Granted Permission:
                  value:
                    messaging_product: whatsapp
                    permission:
                      status: granted
                      expiration_time: 1735689600
                    actions:
                    - action_name: start_call
                      can_perform_action: true
                      limits:
                      - time_period: 24h
                        current_usage: 5
                        max_allowed: 100
                        limit_expiration_time: 1735689600
                    - action_name: send_call_permission_request
                      can_perform_action: false
                      limits: null
                Pending Permission:
                  value:
                    messaging_product: whatsapp
                    permission:
                      status: pending
                    actions:
                    - action_name: start_call
                      can_perform_action: false
                    - action_name: send_call_permission_request
                      can_perform_action: false
                Denied Permission:
                  value:
                    messaging_product: whatsapp
                    permission:
                      status: denied
                    actions:
                    - action_name: start_call
                      can_perform_action: false
                    - action_name: send_call_permission_request
                      can_perform_action: true
                      limits:
                      - time_period: 24h
                        current_usage: 2
                        max_allowed: 5
                        limit_expiration_time: 1735689600
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      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
    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
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      required:
      - error
    CallPermissionCheckResponsePayload:
      type: object
      properties:
        messaging_product:
          type: string
          example: whatsapp
          description: Messaging product
        permission:
          type: object
          properties:
            status:
              type: string
              enum:
              - granted
              - pending
              - denied
              - expired
              example: granted
              description: Current permission status for calling this user
            expiration_time:
              type: integer
              format: int64
              example: 1735689600
              description: Unix timestamp when the permission expires (if applicable)
          required:
          - status
          description: Call permission details
        actions:
          type: array
          items:
            type: object
            properties:
              action_name:
                type: string
                enum:
                - start_call
                - send_call_permission_request
                example: start_call
                description: Name of the action
              can_perform_action:
                type: boolean
                example: true
                description: Whether the business can perform this action
              limits:
                type: array
                items:
                  type: object
                  properties:
                    time_period:
                      type: string
                      example: 24h
                      description: Time period for the limit
                    current_usage:
                      type: integer
                      example: 5
                      description: Current usage count
                    max_allowed:
                      type: integer
                      example: 100
                      description: Maximum allowed usage
                    limit_expiration_time:
                      type: integer
                      format: int64
                      example: 1735689600
                      description: Unix timestamp when the limit resets
                  required:
                  - time_period
                  - current_usage
                  - max_allowed
                description: Rate limits for this action
            required:
            - action_name
            - can_perform_action
          description: Available actions and their restrictions
      required:
      - messaging_product
      - permission
    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
  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
  responses:
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            RateLimitExceeded:
              summary: Rate limit exceeded
              value:
                error:
                  message: Rate limit exceeded
                  type: OAuthException
                  code: 4
    InternalServerError:
      description: Internal Server Error - An unexpected error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            UnexpectedError:
              summary: Unexpected server error
              value:
                error:
                  message: An unexpected error occurred
                  type: OAuthException
                  code: 1
    BadRequest:
      description: Bad Request - Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            InvalidTemplateParameters:
              summary: Invalid template name or parameters
              value:
                error:
                  message: Invalid template name or parameters
                  type: OAuthException
                  code: 100
            MalformedRequest:
              summary: Malformed request body
              value:
                error:
                  message: Invalid JSON in request body
                  type: OAuthException
                  code: 100
            MissingFeatureSetting:
              summary: One feature setting must be specified
              value:
                error:
                  message: One feature setting must be specified
                  type: OAuthException
                  code: 100
    Forbidden:
      description: Forbidden - Template not approved or insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            TemplateNotApproved:
              summary: Template not approved for marketing use
              value:
                error:
                  message: Template not approved for marketing use
                  type: OAuthException
                  code: 200
            InsufficientPermissions:
              summary: Insufficient permissions for this operation
              value:
                error:
                  message: This operation requires additional permissions
                  type: OAuthException
                  code: 200
            FeatureNotSupported:
              summary: Feature not supported
              value:
                error:
                  message: Not supported
                  type: OAuthException
                  code: 10
  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

        '