WhatsApp Settings 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: Settings
paths:
  /{Version}/{Phone-Number-ID}/settings:
    get:
      tags:
      - Settings
      summary: Get phone number settings
      description: 'Retrieve current settings for a WhatsApp Business phone number.

        Returns calling settings, payload encryption settings, and data

        storage configurations.'
      operationId: getPhoneNumberSettings
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - name: Version
        in: path
        required: true
        schema:
          type: string
          example: v22.0
      - name: Phone-Number-ID
        in: path
        required: true
        schema:
          type: string
          example: '123456789012345'
      - name: include_sip_credentials
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: Include SIP credentials in the response (requires additional permissions)
      responses:
        '200':
          description: Current phone number settings retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberSettingsResponse'
              examples:
                Basic settings response:
                  value:
                    calling:
                      status: enabled
                      call_icon_visibility: visible
                      ip_addresses:
                        default:
                        - 157.240.0.1
                        - 157.240.0.2
                      callback_permission_status: enabled
                      video:
                        status: enabled
                    payload_encryption:
                      status: disabled
                    storage_configuration:
                      status: default
                Settings with SIP and encryption:
                  value:
                    calling:
                      status: enabled
                      call_icon_visibility: visible
                      ip_addresses:
                        default:
                        - 157.240.0.1
                        - 157.240.0.2
                      callback_permission_status: enabled
                      srtp_key_exchange_protocol: DTLS-SRTP
                      sip:
                        status: enabled
                        servers:
                        - app_id: '12345'
                          hostname: sip.whatsapp.com
                          port: 5060
                      video:
                        status: enabled
                    payload_encryption:
                      status: enabled
                      client_encryption_key_fingerprint: SHA256:abcd1234...
                      cloud_encryption_key: eyJhbGc...
                    storage_configuration:
                      status: in_country_storage_enabled
                      data_localization_region: us
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
      - bearerAuth: []
    post:
      tags:
      - Settings
      summary: Update phone number settings
      description: 'Update various settings for a WhatsApp Business phone number.

        You can configure calling settings, user identity change settings,

        payload encryption, and data storage configurations.

        Only one feature setting can be specified per request.'
      operationId: updatePhoneNumberSettings
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - name: Version
        in: path
        required: true
        schema:
          type: string
          example: v22.0
      - name: Phone-Number-ID
        in: path
        required: true
        schema:
          type: string
          example: '123456789012345'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              oneOf:
              - $ref: '#/components/schemas/CallingSettingsRequest'
              - $ref: '#/components/schemas/UserIdentityChangeSettingsRequest'
              - $ref: '#/components/schemas/PayloadEncryptionSettingsRequest'
              - $ref: '#/components/schemas/StorageConfigurationSettingsRequest'
            examples:
              Enable calling with video:
                value:
                  calling:
                    status: enabled
                    call_icon_visibility: visible
                    video:
                      status: enabled
              Disable calling:
                value:
                  calling:
                    status: disabled
              Enable SIP calling:
                value:
                  calling:
                    status: enabled
                    sip:
                      status: enabled
                    srtp_key_exchange_protocol: DTLS-SRTP
              Enable payload encryption:
                value:
                  payload_encryption:
                    status: enabled
                    client_encryption_key: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJOUUVGQUFLQ0FRRUEzT2RoQzloK1FjYUpwUGxXWWJ0NE40NTFucFRKUHBnWAotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0=
              Disable payload encryption:
                value:
                  payload_encryption:
                    status: disabled
              Enable user identity change:
                value:
                  user_identity_change:
                    enabled: true
              Configure data storage:
                value:
                  storage_configuration:
                    enabled: true
                    region: us
      responses:
        '200':
          description: Settings updated 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:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
              examples:
                Settings updated successfully:
                  value:
                    success: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
      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
    PayloadEncryptionSettingsResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - enabled
          - disabled
          description: Payload encryption status
        client_encryption_key_fingerprint:
          type: string
          description: Client encryption key fingerprint (when encryption is enabled)
        cloud_encryption_key:
          type: string
          description: Cloud encryption key (when encryption is enabled)
      required:
      - status
    CallingSettingsRequest:
      type: object
      properties:
        calling:
          $ref: '#/components/schemas/CallingSettings'
      required:
      - calling
    StorageConfigurationSettingsResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - default
          - in_country_storage_enabled
          description: Data storage configuration status
        data_localization_region:
          type: string
          description: Data localization region (when in-country storage is enabled)
      required:
      - status
    UserIdentityChangeSettings:
      type: object
      properties:
        enabled:
          type: boolean
          description: Enable or disable user identity change notifications
      required:
      - enabled
    StorageConfigurationSettingsRequest:
      type: object
      properties:
        storage_configuration:
          $ref: '#/components/schemas/StorageConfigurationSettings'
      required:
      - storage_configuration
    SipServerInfo:
      type: object
      properties:
        app_id:
          type: string
          description: Application ID for SIP server
        hostname:
          type: string
          description: SIP server hostname
        port:
          type: integer
          description: SIP server port (optional)
        password:
          type: string
          description: SIP password (only included when include_sip_credentials=true)
      required:
      - app_id
      - hostname
    UserIdentityChangeSettingsRequest:
      type: object
      properties:
        user_identity_change:
          $ref: '#/components/schemas/UserIdentityChangeSettings'
      required:
      - user_identity_change
    PhoneNumberSettingsResponse:
      type: object
      properties:
        calling:
          $ref: '#/components/schemas/CallingSettingsResponse'
        payload_encryption:
          $ref: '#/components/schemas/PayloadEncryptionSettingsResponse'
        storage_configuration:
          $ref: '#/components/schemas/StorageConfigurationSettingsResponse'
      required:
      - calling
      - storage_configuration
    SipSettingsResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - enabled
          - disabled
          description: SIP calling status
        servers:
          type: array
          items:
            $ref: '#/components/schemas/SipServerInfo'
          description: SIP server configuration
      required:
      - status
    PayloadEncryptionSettingsRequest:
      type: object
      properties:
        payload_encryption:
          $ref: '#/components/schemas/PayloadEncryptionSettings'
      required:
      - payload_encryption
    CallingSettings:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - enabled
          - disabled
          description: Enable or disable calling feature
          example: enabled
        call_icon_visibility:
          type: string
          enum:
          - visible
          - hidden
          description: Control visibility of the call icon
          example: visible
    CallingSettingsResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - enabled
          - disabled
          description: Current calling feature status
        call_icon_visibility:
          type: string
          enum:
          - visible
          - hidden
          description: Current call icon visibility setting
        ip_addresses:
          type: object
          properties:
            default:
              type: array
              items:
                type: string
              description: Default IP addresses for calling
          required:
          - default
        callback_permission_status:
          type: string
          enum:
          - enabled
          - disabled
          description: Callback permission status
        srtp_key_exchange_protocol:
          type: string
          enum:
          - DTLS-SRTP
          - SDES-SRTP
          description: SRTP key exchange protocol (optional)
        call_hours:
          $ref: '#/components/schemas/CallHoursSettings'
        call_icons:
          $ref: '#/components/schemas/CallIconsSettings'
        sip:
          $ref: '#/components/schemas/SipSettingsResponse'
        video:
          $ref: '#/components/schemas/VideoSettingsResponse'
        audio:
          $ref: '#/components/schemas/AudioSettingsResponse'
        restrictions:
          $ref: '#/components/schemas/CallingRestrictionsResponse'
      required:
      - status
      - call_icon_visibility
      - ip_addresses
      - callback_permission_status
    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
    CallingRestrictionsResponse:
      type: object
      properties:
        restrictions:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                description: Type of restriction
              expiration:
                type: integer
                format: int64
                description: Expiration timestamp for the restriction
    AudioSettingsResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - enabled
          - disabled
          description: Audio calling status
    CallIconsSettings:
      type: object
      properties:
        restrict_to_user_countries:
          type: array
          items:
            type: string
          description: List of countries where call icons are restricted
    VideoSettingsResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - enabled
          - disabled
          description: Video calling status
      required:
      - status
    PayloadEncryptionSettings:
      type: object
      properties:
        status:
          type: string
          enum:
          - enabled
          - disabled
          description: Enable or disable payload encryption
        client_encryption_key:
          type: string
          description: 'Base64-encoded public key for payload encryption

            (required when enabling encryption)

            '
      required:
      - status
    StorageConfigurationSettings:
      type: object
      properties:
        enabled:
          type: boolean
          description: Enable or disable custom storage configuration
        region:
          type: string
          description: Data storage region
      required:
      - enabled
    CallHoursSettings:
      type: object
      properties:
        status:
          type: string
          enum:
          - enabled
          - disabled
          description: Call hours feature status
        timezone:
          type: string
          description: Timezone for call hours
        day_of_week_start:
          type: string
          description: Start day of the week
      required:
      - status
  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
    Vary:
      schema:
        type: string
        example: Accept-Encoding
      description: Headers that affect caching and content negotiation
    x-fb-trace-id:
      schema:
        type: string
        example: E7riEe9OW2e
      description: Facebook trace identifier for request tracking
    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
    Connection:
      schema:
        type: string
        example: keep-alive
      description: Connection management directive
    X-FB-Debug:
      schema:
        type: string
        example: 52zkUgodnaVRhbBE+3RiGz6TnmjmDEGunwYd+vKSc4synE+Xii//dy6twB/7yKgOJiMUuV0OF248UAZ1qL3v0A==
      description: Facebook debug information for troubleshooting
    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:
    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

        '