WhatsApp Business Account Phone Number API

Version

v23.0

Copy for LLM

View as Markdown

Download OpenAPI spec

API for WhatsApp Business Account phone number operations including status management,

settings configuration, messaging setup, webhook configuration, and display name management.

This endpoint provides comprehensive management capabilities for WhatsApp Business

Account phone numbers, enabling businesses to configure phone number status, messaging settings,

webhook endpoints, and business profile information.

Base URL

Endpoints

| | | | GET | /{Version}/{Phone-Number-ID} | | POST | /{Version}/{Phone-Number-ID} |

GET /{Version}/

Retrieve comprehensive information about a WhatsApp Business phone number using its unique ID (CSID).

This endpoint provides phone number status, verification details, quality metrics, and configuration information.

Core Information Returned:

Phone number ID and display format
Verification status and verified business name
Quality rating based on message delivery performance
Code verification status for two-step verification
Display name certification status (when requested)

Quality Rating System:

The quality rating reflects how recipients have been receiving messages from this phone number:

GREEN: High quality - messages are being delivered and engaged with well
YELLOW: Medium quality - some delivery or engagement issues detected
RED: Low quality - significant delivery or engagement problems
NA: Quality rating not yet determined (new phone numbers)

Display Name Status:

When requesting the name_status field, you'll receive the current certification status:

APPROVED: Business name verified and certificate available for download
AVAILABLE_WITHOUT_REVIEW: Certificate ready without additional review required
DECLINED: Business name verification rejected
EXPIRED: Existing certificate has expired and needs renewal
PENDING_REVIEW: Name verification request is under review
NONE: No certificate or verification request exists

Code Verification Status:

Indicates the two-step verification status:

VERIFIED: Phone number has completed two-step verification
UNVERIFIED: Two-step verification is pending or incomplete

Use Cases:

Monitor phone number quality and delivery performance
Check verification and certification status
Validate phone number configuration before sending messages
Retrieve display information for business profiles
Audit phone number compliance and status

For more information on quality ratings, see WhatsApp Business Account Message Quality Rating.

Request Syntax

GET /{Version}/

Try it

Select language

cURLJavaScriptPython

curl --request GET \  
  --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}' \  
  --header 'Authorization: Bearer <Token>' \  
  --header 'Content-Type: application/json' \  
  --data '{}'

Select status code

200400401403404422429500

{  
  "default_response": {  
    "summary": "Default phone number information",  
    "description": "Basic phone number details without additional fields",  
    "value": {  
      "id": "106853218861309",  
      "display_phone_number": "+1 555-555-5555",  
      "verified_name": "Jaspers Market",  
      "quality_rating": "GREEN"  
    }  
  },  
  "with_name_status": {  
    "summary": "Phone number with display name status",  
    "description": "Includes business name certification status",  
    "value": {  
      "id": "106853218861309",  
      "display_phone_number": "+1 555-555-5555",  
      "verified_name": "Jaspers Market",  
      "quality_rating": "GREEN",  
      "name_status": "AVAILABLE_WITHOUT_REVIEW"  
    }  
  },  
  "with_verification_status": {  
    "summary": "Phone number with code verification status",  
    "description": "Includes two-step verification status",  
    "value": {  
      "id": "106853218861309",  
      "display_phone_number": "+1 555-555-5555",  
      "verified_name": "Jaspers Market",  
      "quality_rating": "GREEN",  
      "code_verification_status": "VERIFIED"  
    }  
  },  
  "comprehensive_response": {  
    "summary": "Full phone number information",  
    "description": "All available fields included in response",  
    "value": {  
      "id": "106853218861309",  
      "display_phone_number": "+1 555-555-5555",  
      "verified_name": "Jaspers Market",  
      "quality_rating": "GREEN",  
      "name_status": "APPROVED",  
      "code_verification_status": "VERIFIED"  
    }  
  }  
}

Header Parameters

User-Agentstring

The user agent string identifying the client software making the request.

Authorizationstring·required

Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.

Path Parameters

Versionstring·required

Graph API version to use for this request. Determines the API behavior and available features.

Use the latest stable version for optimal performance and feature support.

Phone-Number-IDstring·required

Your WhatsApp Business Account phone number ID (CSID). This unique identifier is assigned when you

Query Parameters

fieldsstring

Comma-separated list of additional fields to include in the response. If not specified,

only default fields (id, display_phone_number, verified_name, quality_rating) are returned.

Available Fields:

name_status: Display name certification status for business verification
code_verification_status: Two-step verification status for the phone number

Field Values:

name_status values:

APPROVED: Business name approved, certificate available for download
AVAILABLE_WITHOUT_REVIEW: Certificate ready without additional review
DECLINED: Business name verification rejected
EXPIRED: Certificate expired and needs renewal
PENDING_REVIEW: Name verification under review
NONE: No certificate or verification request exists

code_verification_status values:

VERIFIED: Phone number has completed two-step verification
UNVERIFIED: Two-step verification pending or incomplete

Responses

Retrieve comprehensive information about a WhatsApp Business phone number using its unique ID (CSID).

This endpoint provides phone number status, verification details, quality metrics, and configuration information.

Core Information Returned:

Phone number ID and display format
Verification status and verified business name
Quality rating based on message delivery performance
Code verification status for two-step verification
Display name certification status (when requested)

Quality Rating System:

The quality rating reflects how recipients have been receiving messages from this phone number:

GREEN: High quality - messages are being delivered and engaged with well
YELLOW: Medium quality - some delivery or engagement issues detected
RED: Low quality - significant delivery or engagement problems
NA: Quality rating not yet determined (new phone numbers)

Display Name Status:

When requesting the name_status field, you'll receive the current certification status:

APPROVED: Business name verified and certificate available for download
AVAILABLE_WITHOUT_REVIEW: Certificate ready without additional review required
DECLINED: Business name verification rejected
EXPIRED: Existing certificate has expired and needs renewal
PENDING_REVIEW: Name verification request is under review
NONE: No certificate or verification request exists

Code Verification Status:

Indicates the two-step verification status:

VERIFIED: Phone number has completed two-step verification
UNVERIFIED: Two-step verification is pending or incomplete

Use Cases:

Monitor phone number quality and delivery performance
Check verification and certification status
Validate phone number configuration before sending messages
Retrieve display information for business profiles
Audit phone number compliance and status

For more information on quality ratings, see WhatsApp Business Account Message Quality Rating.

200

Successfully retrieved phone number information. The response includes core phone number details

and any additional fields requested via the fields parameter.

Content Type: application/json

Schema: PhoneNumberInfo

Show child attributes

PhoneNumberInfo

idstring

The ID associated with the phone number

display_phone_numberstring

The string representation of the phone number

verified_namestring

The verified name associated with the phone number

quality_ratingOne of "GREEN", "YELLOW", "RED", "NA"

The quality rating of the phone number based on how messages have been received by recipients in recent days.

GREEN: High Quality
YELLOW: Medium Quality
RED: Low Quality
NA: Quality has not been determined

code_verification_statusOne of "VERIFIED", "UNVERIFIED"

The two-step verification status for the phone number indicating whether the number has completed two-step verification.

VERIFIED: Phone number has completed two-step verification
UNVERIFIED: Two-step verification is pending or incomplete

name_statusOne of "APPROVED", "AVAILABLE_WITHOUT_REVIEW", "DECLINED", "EXPIRED", "PENDING_REVIEW", "NONE"

The status of a display name associated with a specific phone number.

APPROVED: The name has been approved. You can download your certificate now.
AVAILABLE_WITHOUT_REVIEW: The certificate for the phone is available and display name is ready to use without review.
DECLINED: The name has not been approved. You cannot download your certificate.
EXPIRED: Your certificate has expired and can no longer be downloaded.
PENDING_REVIEW: Your name request is under review. You cannot download your certificate.
NONE: No certificate is available.

400

Bad Request - Invalid parameters or malformed request

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

401

Unauthorized - Invalid or missing access token

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

403

Forbidden - Insufficient permissions or access denied

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

404

Not Found - Phone number ID does not exist or is not accessible

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

422

Unprocessable Entity - Request parameters are valid but cannot be processed

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

429

Too Many Requests - Rate limit exceeded

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

500

Internal Server Error - Unexpected server error

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

Select language

cURLJavaScriptPython

curl --request GET \  
  --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}' \  
  --header 'Authorization: Bearer <Token>' \  
  --header 'Content-Type: application/json' \  
  --data '{}'

Select status code

200400401403404422429500

{  
  "default_response": {  
    "summary": "Default phone number information",  
    "description": "Basic phone number details without additional fields",  
    "value": {  
      "id": "106853218861309",  
      "display_phone_number": "+1 555-555-5555",  
      "verified_name": "Jaspers Market",  
      "quality_rating": "GREEN"  
    }  
  },  
  "with_name_status": {  
    "summary": "Phone number with display name status",  
    "description": "Includes business name certification status",  
    "value": {  
      "id": "106853218861309",  
      "display_phone_number": "+1 555-555-5555",  
      "verified_name": "Jaspers Market",  
      "quality_rating": "GREEN",  
      "name_status": "AVAILABLE_WITHOUT_REVIEW"  
    }  
  },  
  "with_verification_status": {  
    "summary": "Phone number with code verification status",  
    "description": "Includes two-step verification status",  
    "value": {  
      "id": "106853218861309",  
      "display_phone_number": "+1 555-555-5555",  
      "verified_name": "Jaspers Market",  
      "quality_rating": "GREEN",  
      "code_verification_status": "VERIFIED"  
    }  
  },  
  "comprehensive_response": {  
    "summary": "Full phone number information",  
    "description": "All available fields included in response",  
    "value": {  
      "id": "106853218861309",  
      "display_phone_number": "+1 555-555-5555",  
      "verified_name": "Jaspers Market",  
      "quality_rating": "GREEN",  
      "name_status": "APPROVED",  
      "code_verification_status": "VERIFIED"  
    }  
  }  
}

POST /{Version}/

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

Request Syntax

POST /{Version}/

Try it

Select language

cURLJavaScriptPython

curl --request POST \  
  --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}' \  
  --header 'Authorization: Bearer <Token>' \  
  --header 'Content-Type: application/json' \  
  --data '{  
  "connection_status": "CONNECTED"  
}'

Select status code

200400401403404422429500

{  
  "message_sent": {  
    "summary": "Message sent successfully",  
    "value": {  
      "messaging_product": "whatsapp",  
      "contacts": [  
        {  
          "input": "+1234567890",  
          "wa_id": "1234567890"  
        }  
      ],  
      "messages": [  
        {  
          "id": "wamid.HBgLMTY3NzE4NDM4NjAVAgARGBI5QTRCMEM4RjA2NzY4RTlBNAA="  
        }  
      ]  
    }  
  },  
  "settings_updated": {  
    "summary": "Settings updated successfully",  
    "value": {  
      "success": true  
    }  
  },  
  "phone_registered": {  
    "summary": "Phone number registered successfully",  
    "value": {  
      "success": true  
    }  
  },  
  "code_verified": {  
    "summary": "Verification code verified successfully",  
    "value": {  
      "success": true  
    }  
  },  
  "two_step_verification_set": {  
    "summary": "Two-step verification code set successfully",  
    "value": {  
      "success": true  
    }  
  }  
}

Header Parameters

User-Agentstring

The user agent string identifying the client software making the request.

Authorizationstring·required

Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.

Path Parameters

Versionstring·required

Graph API version to use for this request. Determines the API behavior and available features.

Phone-Number-IDstring·required

Your WhatsApp Business Account phone number ID (CSID). This ID is provided when you

Request BodyOptional

Configuration parameters for updating phone number status and settings.

All parameters are optional and can be combined in a single request.

Content Type: application/json

Schema: PhoneNumberStatusUpdateRequest

Show child attributes

PhoneNumberStatusUpdateRequest

connection_statusWhatsAppBusinessAccountToNumberStatus

Connection status between WhatsApp Business Account and phone number

webhook_urlstring (uri)

Webhook URL for receiving message notifications

whatsapp_business_api_dataWhatsAppBusinessApiData

WhatsApp Business API configuration data

Show child attributes

pinstring

Two-step verification PIN (can be empty string)

show_security_notificationsboolean

Whether to show security notifications

notify_user_change_numberboolean

Whether to notify users when changing number

pinstring

Two-step verification PIN (can be empty string)

search_visibilityWAAPIBusinessGlobalSearchStateStatus

Search visibility status for the WhatsApp Business Account

webhook_configurationWebhookConfiguration

Webhook configuration settings

Show child attributes

override_callback_uristring (uri)·required

Override callback URI for webhook notifications (can be empty string)

verify_tokenstring

Token used to verify webhook requests

new_display_namestring

New display name for name verification request

usernamestring

Username for the WhatsApp Business Account

Responses

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

200

Operation completed successfully

Content Type: application/json

Schema: Must be one of: MessageResponse, SuccessResponse

Show child attributes

Must be one of: MessageResponse, SuccessResponse

MessageResponse

Response from sending a message

Show child attributes

messaging_product"whatsapp"·required

Messaging service

contactsarray of ContactResponse·required

Contact information

Show child attributes

contacts[]ContactResponse

Show child attributes

inputstring·required

Input phone number

wa_idstring

WhatsApp ID

messagesarray of MessageResponseItem·required

Message information

Show child attributes

messages[]MessageResponseItem

Show child attributes

idstring·required

Message ID

SuccessResponse

Generic success response

Show child attributes

successboolean·required

Operation success status

400

Bad Request - Invalid parameters or malformed request

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

401

Unauthorized - Invalid or missing access token

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

403

Forbidden - Insufficient permissions or access denied

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

404

Not Found - Phone number ID does not exist or is not accessible

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

422

Unprocessable Entity - Request parameters are valid but cannot be processed

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

429

Too Many Requests - Rate limit exceeded

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

500

Internal Server Error - Unexpected server error

Content Type: application/json

Schema: GraphAPIError

Show child attributes

GraphAPIError

errorobject·required

Show child attributes

messagestring·required

Human-readable error message

typestring·required

Error category type

codeinteger·required

Numeric error code

error_subcodeinteger

More specific error subcode when available

fbtrace_idstring

Unique identifier for debugging and support requests with Meta

is_transientboolean

Indicates whether this error is temporary and the request should be retried

Select language

cURLJavaScriptPython

curl --request POST \  
  --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}' \  
  --header 'Authorization: Bearer <Token>' \  
  --header 'Content-Type: application/json' \  
  --data '{  
  "connection_status": "CONNECTED"  
}'

Select status code

200400401403404422429500

{  
  "message_sent": {  
    "summary": "Message sent successfully",  
    "value": {  
      "messaging_product": "whatsapp",  
      "contacts": [  
        {  
          "input": "+1234567890",  
          "wa_id": "1234567890"  
        }  
      ],  
      "messages": [  
        {  
          "id": "wamid.HBgLMTY3NzE4NDM4NjAVAgARGBI5QTRCMEM4RjA2NzY4RTlBNAA="  
        }  
      ]  
    }  
  },  
  "settings_updated": {  
    "summary": "Settings updated successfully",  
    "value": {  
      "success": true  
    }  
  },  
  "phone_registered": {  
    "summary": "Phone number registered successfully",  
    "value": {  
      "success": true  
    }  
  },  
  "code_verified": {  
    "summary": "Verification code verified successfully",  
    "value": {  
      "success": true  
    }  
  },  
  "two_step_verification_set": {  
    "summary": "Two-step verification code set successfully",  
    "value": {  
      "success": true  
    }  
  }  
}

Authentication

Usage Examples

bearerAuth:

Include Authorization: Bearer your-token-here in request headers

Global Authentication Requirements

All endpoints require:

bearerAuth

Upi Intent

message_template_status_update webhook reference

WhatsApp Business Account Phone Number API ​

Base URL ​

Endpoints ​

GET /{Version}/ ​

Request Syntax ​

POST /{Version}/ ​

Request Syntax ​

Authentication ​

Usage Examples ​

Global Authentication Requirements ​

WhatsApp Business Account Phone Number API

Base URL

Endpoints

GET /{Version}/

Request Syntax

POST /{Version}/

Request Syntax

Authentication

Usage Examples

Global Authentication Requirements