> ## 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.

# Phone Settings

> Configure WhatsApp business profiles and phone number settings

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:

```bash icon="terminal" title="Get Business Profile" theme={null}
curl https://api.buildwithchirp.com/v1/whatsapp/phone-numbers/{phoneNumberId}/business-profile \
  -H "Authorization: Bearer YOUR_APP_KEY"
```

### Response

```json icon="code" title="Business Profile Response" theme={null}
{
  "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:

```bash icon="terminal" title="Update Business Profile" theme={null}
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                  |

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

## Phone Settings

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

### Get Phone Settings

Retrieve the current phone settings:

```bash icon="terminal" title="Get Phone Settings" theme={null}
curl https://api.buildwithchirp.com/v1/whatsapp/phone-numbers/{phoneNumberId}/settings \
  -H "Authorization: Bearer YOUR_APP_KEY"
```

### Response

```json icon="code" title="Phone Settings Response" theme={null}
{
  "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:

```bash icon="terminal" title="Update Phone Settings" theme={null}
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

```bash icon="terminal" title="Enable Calling" theme={null}
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

```bash icon="terminal" title="Enable Video Calling" theme={null}
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"
      }
    }
  }'
```

<Info>
  Voice calling must be enabled before you can enable video calling.
</Info>

## User Identity Change Settings

Configure notifications when a user's security key changes.

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

```bash icon="terminal" title="Enable Identity Key Check" theme={null}
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
    }
  }'
```

<Warning>
  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.
</Warning>

## Payload Encryption Settings

Configure end-to-end encryption for webhook payloads.

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

```bash icon="terminal" title="Enable Payload Encryption" theme={null}
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"
    }
  }'
```

<Info>
  When enabled, webhook payloads will be encrypted using the cloud encryption key. You'll need to decrypt them using your private key.
</Info>

## 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`)            |

```bash icon="terminal" title="Configure Storage" theme={null}
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"
    }
  }'
```

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

## 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

```json icon="code" title="Error Response" theme={null}
{
  "error": "Phone number is not linked to a business profile",
  "code": "NO_BUSINESS_PROFILE"
}
```