Phone Settings

Manage your WhatsApp Business phone number settings including business profiles, calling options, and security configurations.

Prerequisites

Before updating phone settings, ensure:

Your phone number is registered with Chirp
The phone number is assigned to your application
Your phone number has a linked WhatsApp Business Profile

Business Profile

The business profile contains information displayed to users when they view your WhatsApp Business account.

Get Business Profile

Retrieve the current business profile for a phone number:

Get Business Profile

curl https://api.buildwithchirp.com/v1/whatsapp/phone-numbers/{phoneNumberId}/business-profile \
  -H "Authorization: Bearer YOUR_APP_KEY"

Response

Business Profile Response

{
  "about": "We provide excellent customer service",
  "address": "123 Main St, San Francisco, CA 94105",
  "description": "Your trusted partner for quality products and services...",
  "email": "contact@example.com",
  "profilePictureUrl": "https://example.com/profile.jpg",
  "websites": ["https://www.example.com", "https://shop.example.com"],
  "vertical": "RETAIL"
}

Update Business Profile

Update the business profile for a phone number:

Update Business Profile

curl -X PATCH https://api.buildwithchirp.com/v1/whatsapp/phone-numbers/{phoneNumberId}/business-profile \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "about": "We provide excellent customer service",
    "address": "123 Main St, San Francisco, CA 94105",
    "email": "contact@example.com",
    "websites": ["https://www.example.com"],
    "vertical": "RETAIL"
  }'

Business Profile Fields

Field	Type	Description
`about`	string	Short description (max 139 characters)
`address`	string	Business address
`description`	string	Full business description
`email`	string	Business contact email
`websites`	array	Business websites (max 2)
`vertical`	string	Business category

Business Verticals

The vertical field accepts the following values:

Value	Description
`AUTO`	Automotive
`BEAUTY`	Beauty, Spa, and Salon
`APPAREL`	Clothing and Apparel
`EDU`	Education
`ENTERTAIN`	Entertainment
`EVENT_PLAN`	Event Planning
`FINANCE`	Finance
`GROCERY`	Grocery
`GOVT`	Government
`HOTEL`	Hotel
`HEALTH`	Health
`NONPROFIT`	Non-profit
`PROF_SERVICES`	Professional Services
`RETAIL`	Retail
`TRAVEL`	Travel
`RESTAURANT`	Restaurant
`OTHER`	Other

Choose the vertical that best represents your business. This helps WhatsApp categorize your account and may affect how your business appears to users.

Phone Settings

Phone settings control advanced features like calling, security, and data storage.

Get Phone Settings

Retrieve the current phone settings:

Get Phone Settings

curl https://api.buildwithchirp.com/v1/whatsapp/phone-numbers/{phoneNumberId}/settings \
  -H "Authorization: Bearer YOUR_APP_KEY"

Response

Phone Settings Response

{
  "calling": {
    "status": "enabled",
    "callIconVisibility": "visible",
    "video": {
      "status": "enabled"
    },
    "ipAddresses": ["192.168.1.1"],
    "callbackPermissionStatus": "granted",
    "sip": {
      "server": "sip.example.com",
      "username": "user123"
    }
  },
  "userIdentityChange": {
    "enableIdentityKeyCheck": true
  },
  "payloadEncryption": {
    "status": "disabled",
    "clientEncryptionKeyFingerprint": null,
    "cloudEncryptionKey": null
  },
  "storageConfiguration": {
    "status": "default",
    "dataLocalizationRegion": "US"
  }
}

Update Phone Settings

Update phone settings with a partial update:

Update Phone Settings

curl -X PATCH https://api.buildwithchirp.com/v1/whatsapp/phone-numbers/{phoneNumberId}/settings \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "calling": {
      "status": "enabled",
      "callIconVisibility": "visible",
      "video": {
        "status": "enabled"
      }
    }
  }'

Calling Settings

Control voice and video calling features for your WhatsApp Business number.

Field	Type	Description
`status`	enum	`enabled` or `disabled`
`callIconVisibility`	enum	`visible` or `hidden`
`video.status`	enum	`enabled` or `disabled`

Enable Calling

curl -X PATCH https://api.buildwithchirp.com/v1/whatsapp/phone-numbers/{phoneNumberId}/settings \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "calling": {
      "status": "enabled",
      "callIconVisibility": "visible"
    }
  }'

Enable Video Calling

curl -X PATCH https://api.buildwithchirp.com/v1/whatsapp/phone-numbers/{phoneNumberId}/settings \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "calling": {
      "video": {
        "status": "enabled"
      }
    }
  }'

Voice calling must be enabled before you can enable video calling.

User Identity Change Settings

Configure notifications when a user’s security key changes.

Field	Type	Description
`enableIdentityKeyCheck`	boolean	Enable security key change notifications

Enable Identity Key Check

curl -X PATCH https://api.buildwithchirp.com/v1/whatsapp/phone-numbers/{phoneNumberId}/settings \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userIdentityChange": {
      "enableIdentityKeyCheck": true
    }
  }'

When enabled, you’ll receive a webhook notification when a user’s identity key changes. This may indicate the user reinstalled WhatsApp or switched devices.

Payload Encryption Settings

Configure end-to-end encryption for webhook payloads.

Field	Type	Description
`status`	enum	`enabled` or `disabled`

Enable Payload Encryption

curl -X PATCH https://api.buildwithchirp.com/v1/whatsapp/phone-numbers/{phoneNumberId}/settings \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payloadEncryption": {
      "status": "enabled"
    }
  }'

When enabled, webhook payloads will be encrypted using the cloud encryption key. You’ll need to decrypt them using your private key.

Storage Configuration

Configure data localization and storage region settings.

Field	Type	Description
`status`	enum	`default` or `in_country_storage_enabled`
`dataLocalizationRegion`	string	Region code (e.g., `US`, `EU`)

Configure Storage

curl -X PATCH https://api.buildwithchirp.com/v1/whatsapp/phone-numbers/{phoneNumberId}/settings \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storageConfiguration": {
      "status": "in_country_storage_enabled",
      "dataLocalizationRegion": "EU"
    }
  }'

Enable in-country storage if you have data residency requirements. This ensures message data is stored in the specified region.

Error Handling

Common Error Codes

Code	Description
`PHONE_NOT_FOUND`	Phone number not found or not assigned to your app
`NO_BUSINESS_PROFILE`	Phone number not linked to a business profile
`UPDATE_FAILED`	Update was not confirmed by Meta
`META_API_ERROR`	Error from Meta’s API
`META_API_UNAVAILABLE`	Meta’s API returned an invalid response

Example Error Response

Error Response

{
  "error": "Phone number is not linked to a business profile",
  "code": "NO_BUSINESS_PROFILE"
}

Getting Started

Concepts

Webhooks

SMS

WhatsApp

Calling

Resources

Phone Settings

Prerequisites

Business Profile

Get Business Profile

Response

Update Business Profile

Business Profile Fields

Business Verticals

Phone Settings

Get Phone Settings

Response

Update Phone Settings

Calling Settings

Enable Calling

Enable Video Calling

User Identity Change Settings

Payload Encryption Settings

Storage Configuration

Error Handling

Common Error Codes

Example Error Response

​Prerequisites

​Business Profile

​Get Business Profile

​Response

​Update Business Profile

​Business Profile Fields

​Business Verticals

​Phone Settings

​Get Phone Settings

​Response

​Update Phone Settings

​Calling Settings

​Enable Calling

​Enable Video Calling

​User Identity Change Settings

​Payload Encryption Settings

​Storage Configuration

​Error Handling

​Common Error Codes

​Example Error Response

Prerequisites

Business Profile

Get Business Profile

Response

Update Business Profile

Business Profile Fields

Business Verticals

Phone Settings

Get Phone Settings

Response

Update Phone Settings

Calling Settings

Enable Calling

Enable Video Calling

User Identity Change Settings

Payload Encryption Settings

Storage Configuration

Error Handling

Common Error Codes

Example Error Response