Skip to main content

WhatsApp Cloud API - Settings API | Developer Documentation

WhatsApp Cloud API - Settings API

Copy for LLM
Version
The Settings API allows you to configure various features and settings
for your WhatsApp Business Account phone numbers. You can manage calling
settings, user identity change settings, payload encryption, and data
storage configurations.

Base

URL
https://graph.facebook.com

Endpoints

GET /{Version}/{Phone-Number-ID}/settings

Retrieve current settings for a WhatsApp Business phone number.
Returns calling settings, payload encryption settings, and data
storage configurations.

Request Syntax

GET /{Version}/{Phone-Number-ID}/settings
Try it
Select language
curl--requestGET \
--url'https://graph.facebook.com/{Version}/{Phone-Number-ID}/settings' \
--header'Authorization: Bearer <Token>' \
--header'Content-Type: application/json' \
--data'{}'
Select status code
{
"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"
      }
    }
  }
}
Header Parameters
User-Agentstring
The user agent string identifying the client software making the request.
Authorizationstring·required
Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.
Content-TypeOne of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·required
Media type of the request body
Path Parameters
Versionstring·required
Select language
Phone-Number-IDstring·required
Query Parameters
include_sip_credentialsboolean
Include SIP credentials in the response (requires additional permissions)
Select status code

Authentication

Scheme
Type
Location
Responses
Retrieve current settings for a WhatsApp Business phone number.bearerAuth
Returns calling settings, payload encryption settings, and data
storage configurations.
200
Current phone number settings retrieved successfully
Content Type: application/json
Schema: PhoneNumberSettingsResponse
Show child attributes
PhoneNumberSettingsResponse
callingCallingSettingsResponse·required
Show child attributes
statusOne of "enabled", "disabled"·required
Current calling feature status
call_icon_visibilityOne of "visible", "hidden"·required
Current call icon visibility setting
ip_addressesobject·required
Show child attributes
defaultarray of string·required
Default IP addresses for calling
Show child attributes
default[]string
callback_permission_statusOne of
"enabled", "disabled"·required
Callback permission status
srtp_key_exchange_protocolOne of "DTLS-SRTP", "SDES-SRTP"
SRTP key exchange protocol (optional)
call_hoursCallHoursSettings
Show child attributes
statusOne of "enabled", "disabled"·required
Call hours feature status
timezonestring
Timezone for call hours
day_of_week_startstring
Start day of the week
call_iconsCallIconsSettings
Show child attributes
restrict_to_user_countriesarray of string
List of countries where call icons are restricted
Show child attributes
restrict_to_user_countries[]string
sipSipSettingsResponse
Show child attributes
statusOne of "enabled", "disabled"·required
SIP calling status
serversarray of SipServerInfo
SIP server configuration
Show child attributes
servers[]SipServerInfo
Show child attributes
app_idstring·required
Application ID for SIP server
hostnamestring·required
SIP server hostname
portinteger
SIP server port (optional)
passwordstring
SIP password (only included when include_sip_credentials=true)
videoVideoSettingsResponse
Show child attributes
statusOne of "enabled", "disabled"·required
Video calling status
audioAudioSettingsResponse
Show child attributes
statusOne of "enabled", "disabled"
Audio calling status
restrictionsCallingRestrictionsResponse
Show child attributes
restrictionsarray of object
Show child attributes
restrictions[]object
Show child attributes
typestring
Type of restriction
expirationinteger (int64)
Expiration timestamp for the restriction
payload_encryptionPayloadEncryptionSettingsResponse
Show child attributes
statusOne of "enabled", "disabled"·required
Payload encryption status
client_encryption_key_fingerprintstring
Client encryption key fingerprint (when encryption is enabled)
cloud_encryption_keystring
Cloud encryption key (when encryption is enabled)
storage_configurationStorageConfigurationSettingsResponse·required
Show child attributes
statusOne of "default", "in_country_storage_enabled"·required
Data storage configuration status
data_localization_regionstring
Data localization region (when in-country storage is enabled)
400
Bad Request - Invalid request parameters
Content Type: application/json
403
Forbidden - Template not approved or insufficient permissions
Content Type: application/json
Select language
curl--requestGET \
--url'https://graph.facebook.com/{Version}/{Phone-Number-ID}/settings' \
--header'Authorization: Bearer <Token>' \
--header'Content-Type: application/json' \
--data'{}'
Select status code
{
"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"
      }
    }
  }
}

POST /{Version}/{Phone-Number-ID}/settings

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.

Request Syntax

POST /{Version}/{Phone-Number-ID}/settings
Try it
Select language
curl--request POST \
--url'https://graph.facebook.com/{Version}/{Phone-Number-ID}/settings' \
--header'Authorization: Bearer <Token>' \
--header'Content-Type: application/json' \
--data'{
  "calling": {
    "status": "enabled",
    "call_icon_visibility": "visible",
    "video": {
      "status": "enabled"
    }
  }
}'
Select status code
{
"Settings updated successfully": {
"value": {
"success": true
    }
  }
}
Header Parameters
User-Agentstring
The user agent string identifying the client software making the request.
Authorizationstring·required
Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.
Content-TypeOne of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·required
Media type of the request body
Path Parameters
Versionstring·required
Phone-Number-IDstring·required
Request BodyOptional
Content Type: application/json
Schema: Must be one of: CallingSettingsRequest, UserIdentityChangeSettingsRequest, PayloadEncryptionSettingsRequest, StorageConfigurationSettingsRequest
Show child attributes
Must be one of: CallingSettingsRequest, UserIdentityChangeSettingsRequest, PayloadEncryptionSettingsRequest, StorageConfigurationSettingsRequest
CallingSettingsRequest
Show child attributes
callingCallingSettings·required
Show child attributes
statusOne of "enabled", "disabled"·required
Enable or disable calling feature
call_icon_visibilityOne of "visible", "hidden"
Control visibility of the call icon
videoVideoSettings
Show child attributes
statusOne of "enabled", "disabled"·required
Enable or disable video calling
sipSipSettings
Show child attributes
statusOne of "enabled", "disabled"·required
Enable or disable SIP calling
srtp_key_exchange_protocolOne of "DTLS-SRTP", "SDES-SRTP"
SRTP key exchange protocol
UserIdentityChangeSettingsRequest
Show child attributes
user_identity_changeUserIdentityChangeSettings·required
Show child attributes
enabledboolean·required
Enable or disable user identity change notifications
PayloadEncryptionSettingsRequest
Show child attributes
payload_encryptionPayloadEncryptionSettings·required
Show child attributes
statusOne of "enabled", "disabled"·required
Enable or disable payload encryption
client_encryption_keystring
Base64-encoded public key for payload encryption
(required when enabling encryption)
StorageConfigurationSettingsRequest
Show child attributes
storage_configurationStorageConfigurationSettings·required
Show child attributes
enabledboolean·required
Enable or disable custom storage configuration
regionstring
Data storage region
Responses
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.
200
Settings updated successfully
Content Type: application/json
Schema: object
Show child attributes
successboolean
400
Bad Request - Invalid request parameters
Content Type: application/json
403
Forbidden - Template not approved or insufficient permissions
Content Type: application/json
Select language
curl--request POST \
--url'https://graph.facebook.com/{Version}/{Phone-Number-ID}/settings' \
--header'Authorization: Bearer <Token>' \
--header'Content-Type: application/json' \
--data'{
  "calling": {
    "status": "enabled",
    "call_icon_visibility": "visible",
    "video": {
      "status": "enabled"
    }
  }
}'
Select status code
{
"Settings updated successfully": {
"value": {
"success": true
    }
  }
}

Authentication

Scheme
Type
Location
bearerAuth
HTTP Bearer
Header: Authorization

Usage Examples

bearerAuth:
Include Authorization: Bearer your-token-here in request headers

Global Authentication Requirements

All endpoints require:
bearerAuth
Back to top