Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Prerequisites

Before updating phone settings, ensure:
  1. Your phone number is registered with Chirp
  2. The phone number is assigned to your application
  3. 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

FieldTypeDescription
aboutstringShort description (max 139 characters)
addressstringBusiness address
descriptionstringFull business description
emailstringBusiness contact email
websitesarrayBusiness websites (max 2)
verticalstringBusiness category

​
Business Verticals

The vertical field accepts the following values:
ValueDescription
AUTOAutomotive
BEAUTYBeauty, Spa, and Salon
APPARELClothing and Apparel
EDUEducation
ENTERTAINEntertainment
EVENT_PLANEvent Planning
FINANCEFinance
GROCERYGrocery
GOVTGovernment
HOTELHotel
HEALTHHealth
NONPROFITNon-profit
PROF_SERVICESProfessional Services
RETAILRetail
TRAVELTravel
RESTAURANTRestaurant
OTHEROther
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.
FieldTypeDescription
statusenumenabled or disabled
callIconVisibilityenumvisible or hidden
video.statusenumenabled or disabled

​
Enable Calling

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

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.
FieldTypeDescription
enableIdentityKeyCheckbooleanEnable 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.
FieldTypeDescription
statusenumenabled 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.
FieldTypeDescription
statusenumdefault or in_country_storage_enabled
dataLocalizationRegionstringRegion 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

CodeDescription
PHONE_NOT_FOUNDPhone number not found or not assigned to your app
NO_BUSINESS_PROFILEPhone number not linked to a business profile
UPDATE_FAILEDUpdate was not confirmed by Meta
META_API_ERRORError from Meta’s API
META_API_UNAVAILABLEMeta’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"
}