> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage WhatsApp phone numbers

> Register phone numbers and manage profiles, commerce, and calling settings.

## What it is

A WhatsApp business phone number is the sender identity customers see in a
conversation. Use these APIs to discover registered numbers, configure their
business profile, request a display name change, control commerce visibility,
and manage phone-specific settings.

## Before you begin

* Connect the parent WABA to YCloud.
* Add the phone number to the WABA.
* Store the WABA ID and phone number in E.164 format.
* Upload a profile picture to Meta before setting `profilePictureUrl`.

## How it works

1. List numbers or retrieve one number to inspect its state.
2. Register a number before using it for messaging.
3. Update the customer-facing business profile.
4. Update display name, commerce visibility, or calling settings as needed.
5. Retrieve the resource again to confirm the current configuration.

Display name changes and some platform settings may require asynchronous Meta
processing.

## Request

### Register a phone number

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  https://api.ycloud.com/v2/whatsapp/phoneNumbers/WABA_ID/+16315551111/register \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

### Update the business profile

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PATCH \
  https://api.ycloud.com/v2/whatsapp/phoneNumbers/WABA_ID/+16315551111/profile \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "about": "Customer support and order updates",
    "address": "100 Market Street",
    "description": "Example Store",
    "email": "support@example.com",
    "vertical": "RETAIL",
    "websites": ["https://example.com"]
  }'
```

### Update commerce visibility

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PATCH \
  https://api.ycloud.com/v2/whatsapp/phoneNumbers/WABA_ID/+16315551111/whatsappCommerceSettings \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "isCartEnabled": true,
    "isCatalogVisible": true
  }'
```

## Response

Profile and settings operations return the updated resource.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "about": "Customer support and order updates",
  "email": "support@example.com",
  "vertical": "RETAIL",
  "websites": ["https://example.com"]
}
```

Registration returns the phone number resource. Store its IDs and inspect its
registration and quality state before sending.

## Configuration areas

| Area | Use it for |
| - | - |
| Profile | About text, address, description, email, vertical, websites, and profile picture. |
| Display name | Customer-facing sender name submitted for Meta processing. |
| Commerce | Catalog visibility and shopping cart controls. |
| Settings | Phone-specific features such as WhatsApp Calling. |

## Limits and troubleshooting

* Profile fields have format and length limits; use the API Reference for the
  complete constraints.
* Website URLs must include `http://` or `https://`.
* A display name update may not become active immediately.
* Registration, quality, and WABA state can independently affect sending.
* Use the WABA ID and exact E.164 number in every path.

<CardGroup cols={2}>
  <Card title="List phone numbers" icon="list" href="/api-reference/whatsapp-phone-numbers/list-phone-numbers">
    Discover registered numbers and their parent WABA.
  </Card>

  <Card title="Update profile" icon="address-card" href="/api-reference/whatsapp-phone-numbers/update-a-phone-number-profile">
    Inspect every profile field and constraint.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.