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:
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" : "[email protected] " , "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:
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": "[email protected] ", "websites": ["https://www.example.com"], "vertical": "RETAIL" }'
Business Profile Fields Field Type Description aboutstring Short description (max 139 characters) addressstring Business address descriptionstring Full business description emailstring Business contact email websitesarray Business websites (max 2) verticalstring Business category
Business Verticals The vertical field accepts the following values:
Value Description 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:
curl https://api.buildwithchirp.com/v1/whatsapp/phone-numbers/{phoneNumberId}/settings \ -H "Authorization: Bearer YOUR_APP_KEY"
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:
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 statusenum enabled or disabledcallIconVisibilityenum visible or hiddenvideo.statusenum 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 enableIdentityKeyCheckboolean 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 statusenum 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 statusenum default or in_country_storage_enableddataLocalizationRegionstring Region code (e.g., US, EU)
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_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" : "Phone number is not linked to a business profile" , "code" : "NO_BUSINESS_PROFILE" }
