How do I check if my WhatsApp number can send messages via the API?

Request `health_status` on the phone number: `GET /{PHONE_NUMBER_ID}?fields=health_status`. AVAILABLE means you can send; LIMITED or BLOCKED entities explain what is restricting it and how to fix it.

What does BLOCKED mean in WhatsApp health status?

At least one requirement for sending is unmet. The blocked entity — phone number, template, WABA, business or app — lists `errors` with an error code, a description and a possible solution to follow.

Is health status the same as quality rating?

No. Health status says whether an asset can send at all and why not; quality rating grades recent recipient feedback on your messages. A number can be rated GREEN yet be BLOCKED by a portfolio-level issue.

Which permission does the health_status field need?

Typically `whatsapp_business_management`, the permission for reading WhatsApp Business Accounts and their phone numbers and templates, on a token that has access to that WABA — for example a system user token assigned to it.

WhatsApp Health Status API: Can This Number Send?

Description

What is the Health Status API?

The Health Status API is not a separate endpoint but a field: health_status, requested with an ordinary Graph API GET on a WhatsApp Business phone number, a WhatsApp Business Account (WABA) or a message template — GET /v26.0/{PHONE_NUMBER_ID}?fields=health_status. The answer says whether messages can be sent through that object right now and, if not, which object in the chain is responsible.

The response holds an overall can_send_message value and an entities array. Each entity has an entity_type — PHONE_NUMBER when you query a number, MESSAGE_TEMPLATE when you query a template, and always WABA, BUSINESS (the business portfolio) and APP — plus its own id and can_send_message. AVAILABLE means every requirement is met; LIMITED means you can send with limitations described in additional_info; BLOCKED means a requirement is unmet, described in errors with error_code, error_description and possible_solution. The overall value is the worst of the entities. Phone number and app entities also report can_receive_call_sip for SIP calling, which is not rolled into any overall value.

It answers a different question from Quality Rating, which grades how recipients are receiving your messages (GREEN, YELLOW, RED) and feeds into Messaging Limits & Tiers. A number can be GREEN and still BLOCKED because of a business portfolio or app restriction. It is also not a health check of your own servers: it reports Meta's view of your WhatsApp assets, not whether your webhook endpoint is up.

Key takeaways

The Health Status API is the health_status field you request on a phone number, WABA or template to see whether it can send.
can_send_message is AVAILABLE, LIMITED or BLOCKED overall and for each entity: phone number or template, WABA, business and app.
BLOCKED entities list errors with a code, description and possible solution; LIMITED ones list additional_info.
The overall status is the worst of its parts: one blocked entity makes the whole check BLOCKED.
Health status says whether you can send at all; quality rating grades how recipients are receiving your messages.

Usage

The Health Status API in code

1curl -G "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}" \
2  -H "Authorization: Bearer {ACCESS_TOKEN}" \
3  --data-urlencode "fields=health_status"

Properties

The Health Status API: key facts and limits

Request: GET /{node-id}?fields=health_status
Nodes: Phone number, WABA, message template
Values: AVAILABLE · LIMITED · BLOCKED
Entity types: PHONE_NUMBER, MESSAGE_TEMPLATE, WABA, BUSINESS, APP
Overall rule: Worst entity wins: BLOCKED > LIMITED > AVAILABLE
BLOCKED detail: errors[]: error_code, error_description, possible_solution
LIMITED detail: additional_info[] strings
Calling: can_receive_call_sip on phone number and app entities

Mechanics

How does the Health Status API work?

step 1 — Request the field
GET the node with fields=health_status — like any Field Expansion, it is returned only when requested — using a token that can read the WABA. Query a Phone Number ID to check a sender, a template to check one message, or the WABA for an account-wide view.
step 2 — Read the overall value
health_status.can_send_message is the summary: BLOCKED if any entity is blocked, otherwise LIMITED if any is limited, otherwise AVAILABLE.
step 3 — Find the entity at fault
Walk entities and pick out any entry that is not AVAILABLE. Its entity_type and id tell you whether the number, template, WABA, business portfolio or app needs attention.
step 4 — Act on errors and additional_info
BLOCKED entities carry errors with error_code, error_description and possible_solution; LIMITED ones carry additional_info strings. Route each to whoever can fix it.
step 5 — Check at the right moments
Run it before campaigns, on a schedule and when error rates rise, and pair it with the Account Update Webhook and quality webhooks so changes reach you without constant polling.

Caveats

Common mistakes with the Health Status API

Confusing it with quality rating
A GREEN number can be BLOCKED by a portfolio or app problem, and a YELLOW one can be AVAILABLE. Read both: health for whether you can send, quality for how well it is going.
Only reading the overall value
The summary hides which layer is at fault. Log every entity that is not AVAILABLE with its errors or additional_info, so the fix reaches the person who can make it.
Treating LIMITED as fine
LIMITED means you can send with restrictions — for example while a display name awaits approval. Surface it before a large campaign rather than discovering it through failures.
Calling it before every message
It is a management read that counts against Graph rate limits. Check before campaigns, on a schedule and when errors spike — not once per send.

Example

Example: A pre-campaign check in Lucknow

Before a 50,000-recipient festive offer, a Lucknow apparel chain's campaign tool requests health_status on the marketing template and on the sending number. The template returns AVAILABLE, but the number comes back LIMITED with an additional_info note that its new display name is still awaiting approval, which keeps the number's sending capacity low. Instead of watching most of the broadcast fail, the team sends to its 2,000 most engaged customers first and schedules the rest for after the name is approved.

Why it matters

Why does the Health Status API matter?

When sends start failing, the slow part is finding which layer is at fault — the number, the template, the WABA, the business portfolio or the app. Health status answers that in one call, with Meta's own error code and suggested fix, so support can tell a customer exactly what to do instead of guessing from a pile of failed sends. Checked before a campaign, it stops a 50,000-recipient broadcast from failing message by message, and it gives on-call engineers a first command to run when the inbox goes quiet.

Notes

Best practices for the Health Status API

Make health status the first check in your support runbook when a customer says messages are not going out.
Check the template's health before a big broadcast, not just the sending number's.
Store each result with a timestamp so support can see when a status changed.
Map common error_code values to plain-language fixes in your admin panel.

Questions

Health Status API FAQs

How do I check if my WhatsApp number can send messages via the API?: Request health_status on the phone number: GET /{PHONE_NUMBER_ID}?fields=health_status. AVAILABLE means you can send; LIMITED or BLOCKED entities explain what is restricting it and how to fix it.
What does BLOCKED mean in WhatsApp health status?: At least one requirement for sending is unmet. The blocked entity — phone number, template, WABA, business or app — lists errors with an error code, a description and a possible solution to follow.
Is health status the same as quality rating?: No. Health status says whether an asset can send at all and why not; quality rating grades recent recipient feedback on your messages. A number can be rated GREEN yet be BLOCKED by a portfolio-level issue.
Which permission does the health_status field need?: Typically whatsapp_business_management, the permission for reading WhatsApp Business Accounts and their phone numbers and templates, on a token that has access to that WABA — for example a system user token assigned to it.

See InfiQ pricing

Health Status API

Run the pre-send health check

What is the Health Status API?

The Health Status API in code

The Health Status API: key facts and limits

How does the Health Status API work?

Common mistakes with the Health Status API

Confusing it with quality rating

Only reading the overall value

Treating LIMITED as fine

Calling it before every message

Example: A pre-campaign check in Lucknow

Why does the Health Status API matter?

Best practices for the Health Status API

Health Status API FAQs

See how this works on InfiQ

Put Health Status API to work

See how this works on InfiQ