---
title: "Update WhatsApp Business Account Phone Number Status and Configuration"
method: POST
path: "/{Version}/{Phone-Number-ID}"
tags: ["Phone Numbers"]
---

# Update WhatsApp Business Account Phone Number Status and Configuration

`POST /{Version}/{Phone-Number-ID}`

## Request

- Base URL: `https://graph.facebook.com`
- URL: `https://graph.facebook.com/{Version}/{Phone-Number-ID}`
- Auth: HTTP bearer

Update the status and configuration of a WhatsApp Business Account phone number.
This endpoint supports comprehensive phone number management including status updates,
webhook configuration, security settings, and business profile management.

**Supported Operations:**
- Update connection status between WhatsApp Business Account and phone number
- Configure webhook endpoints for message delivery notifications
- Set up two-step verification and security notifications
- Update display names for name verification
- Configure search visibility and privacy settings
- Set username for the WhatsApp Business Account
- Override webhook callback URIs for message notifications

**Business Logic Requirements:**
- App must be linked to the WhatsApp Business Account
- Webhook subscription must exist before configuring callback URI overrides
- Callback URI verification is performed for external URLs
- Internal URLs are allowed for development environments

**Rate Limiting:**
WhatsApp use case throttling applies. Use appropriate retry logic with exponential backoff.

**Security Validations:**
- App-to-WABA linking validation enforced
- Webhook callback URI verification required for external URLs
- Business integration system user checks for AI bot onboarding
- Capability checks for first-party app access

## Path parameters

- `Version` string, required
- `Phone-Number-ID` string, required

## Headers

- `User-Agent` string
- `Authorization` string, required

## Request body

- PhoneNumberStatusUpdateRequest: Request to update phone number status and configuration
  - `connection_status` 'CONNECTED' | 'DISCONNECTED' | 'PENDING' | 'FLAGGED' | 'RESTRICTED' | 'RATE_LIMITED' | 'MESSAGING_LIMIT_TIER_0' | 'MESSAGING_LIMIT_TIER_1' | 'MESSAGING_LIMIT_TIER_2' | 'MESSAGING_LIMIT_TIER_3' | 'MESSAGING_LIMIT_TIER_4': Connection status between WhatsApp Business Account and phone number
  - `webhook_url` string, uri: Webhook URL for receiving message notifications
  - `whatsapp_business_api_data` WhatsAppBusinessApiData: WhatsApp Business API configuration data
    - `pin` string: Two-step verification PIN (can be empty string)
    - `show_security_notifications` boolean: Whether to show security notifications
    - `notify_user_change_number` boolean: Whether to notify users when changing number
  - `pin` string: Two-step verification PIN (can be empty string)
  - `search_visibility` 'VISIBLE' | 'HIDDEN': Search visibility status for the WhatsApp Business Account
  - `webhook_configuration` WebhookConfiguration: Webhook configuration settings
    - `override_callback_uri` string, uri, required: Override callback URI for webhook notifications (can be empty string)
    - `verify_token` string: Token used to verify webhook requests
  - `new_display_name` string: New display name for name verification request
  - `username` string: Username for the WhatsApp Business Account

## Response `200`

Operation completed successfully

- union
  - MessageResponse: Response from sending a message
    - `messaging_product` 'whatsapp', required: Messaging service
    - `contacts` ContactResponse[], required: Contact information
      - `input` string, required: Input phone number
      - `wa_id` string: WhatsApp ID
    - `messages` MessageResponseItem[], required: Message information
      - `id` string, required: Message ID
  - SuccessResponse: Generic success response
    - `success` boolean, required: Operation success status

## Other responses

- `400`: Bad Request - Invalid parameters or malformed request
- `401`: Unauthorized - Invalid or missing access token
- `403`: Forbidden - Insufficient permissions or access denied
- `404`: Not Found - Phone number ID does not exist or is not accessible
- `422`: Unprocessable Entity - Request parameters are valid but cannot be processed
- `429`: Too Many Requests - Rate limit exceeded
- `500`: Internal Server Error - Unexpected server error

---

[API](https://skmtc.dev/meta/apis/whatsapp-business-messaging.md) - [All operations](https://skmtc.dev/meta/apis/whatsapp-business-messaging/llms.txt) - [OpenAPI document](https://skmtc.dev/meta/apis/whatsapp-business-messaging/revisions/5c1973265369?raw)