Is This WhatsApp Number Ready to Send? Reading Status, Quality and Limits From the Graph API
DEV Community

Is This WhatsApp Number Ready to Send? Reading Status, Quality and Limits From the Graph API

Embedded Signup finishes, the customer's phone number appears in your database, and your UI shows a green "Connected". Then the first template send comes back with 133010 ("Phone number not registered on the WhatsApp Business Platform"), or it goes out fine but no reply ever arrives, or the campaign stops at 250 recipients and nobody knows why.

None of those are send bugs. They're readiness problems, and Meta reports every one of them through the Graph API before you send anything, spread across a phone number, an account, a business portfolio and your app's webhook subscription.

This post builds a readiness check in TypeScript: one function that reads those resources, and one pure function that turns them into a verdict ("can send, can receive, limit is N") with the reasons and the fixes. It also covers the account-level webhooks that tell you when the answer changes.

It's based on what we read and show in WAPGROWAI's channel settings, including the parts we haven't built yet. The code below was run with node --experimental-strip-types and 11 tests against fixtures shaped like Meta's documented responses.

A naming note: Meta is splitting the WhatsApp Business Account into a "WhatsApp account" and a "Messaging account". Per the account model docs , "Existing WABA IDs remain the same and denote Messaging account IDs", so every WABA_ID below still works. I'll keep saying WABA because that's what the endpoints and error texts still say.

Where readiness lives

There's no single "ready" flag. Five things decide whether a number can send and whether you'll hear back:

  • The phone number node. Is it registered on Cloud API, connected, verified, and is its display name approved?
  • The account (WABA). Has it passed review?
  • The business portfolio. It owns the messaging limit, which since October 2025 is shared by every number in the portfolio.
  • Health status. Meta's own summary of whether the number, account, business and app "can send", with error codes and suggested fixes.
  • Your app's subscription to the account. Without it, sends work and webhooks never arrive.

Most integrations check the first one at connect time and never again. That's how you end up with a green badge on a number that can't send.

The fields worth reading

On GET /{PHONE_NUMBER_ID}, these are the fields that matter, with the values Meta documents:

  • platform_type: CLOUD_API once the number is registered for Cloud API. Meta's docs show only that value in examples, so I treat anything else, including a missing field, as "not registered yet".
  • status: Meta's phone numbers guide says numbers "must have a status of 'connected' in order to send and receive messages via the API". Meta doesn't publish the full list of other values, so the check below accepts only CONNECTED.
  • code_verification_status: VERIFIED or NOT_VERIFIED, for the SMS or voice code.
  • name_status: APPROVED, AVAILABLE_WITHOUT_REVIEW, PENDING_REVIEW, DECLINED, EXPIRED or NONE. EXPIRED means the display name certificate expired and "cannot be used to register the phone number for API use".
  • account_mode: SANDBOX ("The account is unverified") or LIVE.
  • whatsapp_business_manager_messaging_limit: the messaging limit, as TIER_250, TIER_2K, TIER_10K, TIER_100K or TIER_UNLIMITED (the enum also lists TIER_50 and UNTIERED).
  • health_status: covered below.

Two traps here: messaging_limit_tier is deprecated. Meta's messaging limits page says it "has been deprecated. Request the whatsapp_business_manager_messaging_limit field instead." In our integration the old field came back empty, so we read whatsapp_business_manager_messaging_limit first and fall back to the old one only for numbers that haven't moved over. (Meta's changelog describes the old field differently, as returning the portfolio's limit from v24.0, so don't rely on it either way.)

The limit belongs to the portfolio, not the number. Since October 2025, "Messaging limits are calculated and set at the business portfolio level and are shared by all business phone numbers within a portfolio." Two numbers on TIER_2K don't give you 4,000. They share 2,000 unique users per rolling 24 hours, counted for messages sent outside a customer service window.

On the WABA, account_review_status is PENDING, APPROVED or REJECTED. The account_review_update webhook is blunt about pending: the account "currently cannot be used with our APIs".

Health status: Meta's own verdict

health_status is the field most integrations don't know about. Request it on a phone number, a WABA or a message template, and Meta returns whether it "can send", plus the entities behind that answer. From the health status docs:

  • AVAILABLE: "meets all messaging or calling requirements".
  • LIMITED: "meets messaging or calling requirements, but has some limitations", with an additional_info array explaining why.
  • BLOCKED: "does not meet one or more messaging or calling requirements", with an errors array of error_code, error_description and possible_solution.

The overall value is the worst of the entities: blocked if any is blocked, else limited if any is limited. And the entity list goes beyond what you asked about. A phone number's health includes its WABA, the business and your app, which is how a business-level restriction shows up on a number that looks fine.

Meta's example of a LIMITED reason is "Your display name has not been approved yet." Meta itself points here when things break: under error 131031 (account locked), the error codes page suggests "the Health Status API, which may provide additional insight into the reason or reasons for the account lock."

Reading it all in one call

fetchSnapshot reads the number, the WABA, the app subscriptions and, optionally, the templates you're about to send. GraphGet is a thin wrapper over fetch against https://graph.facebook.com/<VERSION>, injected so the tests can fake it.

export type CanSend = "AVAILABLE" | "LIMITED" | "BLOCKED" ;
export type HealthError = { error_code : number ; error_description : string ; possible_solution ?: string } ;
export type HealthEntity = { entity_type : string ; // PHONE_NUMBER, MESSAGE_TEMPLATE, WABA, BUSINESS, APP id : string ; can_send_message : CanSend ; errors ?: HealthError [ ] ; additional_info ?: string [ ] ; } ;
export type HealthStatus = { can_send_message : CanSend ; entities : HealthEntity [ ] } ;
export type PhoneNode = { id : string ; display_phone_number ?: string ; verified_name ?: string ; status ?: string ; name_status ?: string ; code_verification_status ?: string ; quality_rating ?: string ; platform_type ?: string ; account_mode ?: string ; whatsapp_business_manager_messaging_limit ?: string ; health_status ?: HealthStatus ; } ;
export type WabaNode = { id : string ; account_review_status ?: string } ;
export type TemplateNode = { id : string ; name ?: string ; health_status ?: HealthStatus } ;
export type Snapshot = { phone : PhoneNode | null ; // null: the number is gone, or this token can't see it waba : WabaNode | null ; templates : TemplateNode [ ] ; subscribedAppIds : string [ ] ; ourAppId : string ; } ;
export const PHONE_FIELDS = [ "display_phone_number" , "verified_name" , "status" , "name_status" , "code_verification_status" , "quality_rating" , "platform_type" , "account_mode" , "whatsapp_business_manager_messaging_limit" , "health_status" , ] . join ( "," ) ;
export type GraphGet = ( path : string , params : Record < string , string > ) => Promise < { status : number ; body : any } > ;
// Code 100 with subcode 33: what Graph still returns, in our experience, for a number that's gone.
export const isGone = ( body : any ) => body ? . error ? . code === 100 && body ? . error ? . error_subcode === 33 ;
export const fetchSnapshot = async ( graph : GraphGet , ids : { phoneNumberId : string ; wabaId : string ; appId : string ; templateIds ?: string [ ] } , ) : Promise < Snapshot > => { const [ phoneRes , wabaRes , subsRes , . . . templateRes ] = await Promise . all ( [ graph ( `/${ids.phoneNumberId}` , { fields : PHONE_FIELDS } ) , graph ( `/${ids.wabaId}` , { fields : "account_review_status" } ) , graph ( `/${ids.wabaId}/subscribed_apps` , { } ) , . . . ( ids . templateIds ?? [ ] ) . map ( ( id ) => graph ( `/${id}` , { fields : "name,health_status" } ) ) , ] ) ; if ( phoneRes . status >= 400 && ! isGone ( phoneRes . body ) ) { throw new Error ( `phone number read failed: ${phoneRes.body?.error?.message ?? phoneRes.status}` ) ; } if ( subsRes . status >= 400 ) { throw new Error ( `subscribed_apps read failed: ${subsRes.body?.error?.message ?? subsRes.status}` ) ; } return { phone : phoneRes . status < 400 ? phoneRes . body : null , waba : wabaRes . status < 400 ? wabaRes . body : null , templates : templateRes . filter ( ( r ) => r . status < 400 ) . map ( ( r ) => r . body ) , subscribedAppIds : ( subsRes . body ? . data ?? [ ] ) . map ( ( d : any ) => d . whatsapp_business_api_data ? . id ) . filter ( Boolean ) , ourAppId : ids . appId , } ; } ;

Two decisions in there are deliberate: "Does not exist" is an answer, not an error. In our experience, Graph returns code 100 with subcode 33 when the number has been deleted or moved, or the token lost access to it. Meta's error docs list error_subcode as deprecated from v16.0, so log the message too, in case that changes. That's a state to show the user ("this number is gone"), so it becomes phone: null.

An expired token (190) is a real error and throws: you can't say anything about readiness without a working token.

The subscription check is mandatory. GET /{WABA_ID}/subscribed_apps returns data[].whatsapp_business_api_data.id for each subscribed app. If yours isn't in the list, you get a classic "WhatsApp is down" report: the business can send, and every reply and delivery status goes nowhere.

Turning it into a verdict

The verdict has three parts: can it send (yes, limited, no), will you receive webhooks, and what's the portfolio limit. Blockers stop sends; warnings mean it works with limits.

export type Finding = { code : string ; message : string ; fix ?: string } ;
export type Verdict = { send : "yes" | "limited" | "no" ; receive : "yes" | "no" ; portfolioLimit : number | null ; // unique users per rolling 24h outside a service window; null = unlimited blockers : Finding [ ] ; warnings : Finding [ ] ; } ;
const TIER_LIMITS : Record < string , number | null > = { TIER_50 : 50 , TIER_250 : 250 , TIER_2K : 2_000 , TIER_10K : 10_000 , TIER_100K : 100_000 , TIER_UNLIMITED : null , } ;
// New business portfolios start here; TIER_NOT_SET, UNTIERED or a missing value fall back to it.
const STARTING_LIMIT = 250 ;
const fromHealth = ( health : HealthStatus | undefined , blockers : Finding [ ] , warnings : Finding [ ] ) => { for ( const entity of health ? . entities ?? [ ] ) { if ( entity . can_send_message === "AVAILABLE" ) continue ; const into = entity . can_send_message === "BLOCKED" ? blockers : warnings ; const where = `${entity.entity_type} ${entity.id}` ; for ( const e of entity . errors ?? [ ] ) { into . push ( { code : `health:${entity.entity_type}:${e.error_code}` , message : `${where}: ${e.error_description}` , fix : e . possible_solution } ) ; } for ( const info of entity . additional_info ?? [ ] ) { into . push ( { code : `health:${entity.entity_type}:info` , message : `${where}: ${info}` } ) ; } if ( ! entity . errors ? . length && ! entity . additional_info ? . length ) { into . push ( { code : `health:${entity.entity_type}` , message : `${where} is ${entity.can_send_message}` } ) ; } } } ;
export const assess = ( s : Snapshot ) : Verdict => { const blockers : Finding [ ] = [ ] ; const warnings : Finding [ ] = [ ] ; const receive = s . subscribedAppIds . includes ( s . ourAppId ) ? "yes" : "no" ; if ( receive === "no" ) { warnings . push ( { code : "webhooks:not-subscribed" , message : "Your app isn't subscribed to this account, so replies and delivery statuses never reach you." , fix : "POST /{WABA_ID}/subscribed_apps with the business token" , } ) ; } const phone = s . phone ; if ( ! phone ) { blockers . push ( { code : "phone:gone" , message : "The number can't be read: deleted, moved, or the token lost access." } ) ; return { send : "no" , receive , portfolioLimit : null , blockers , warnings } ; } if ( phone . platform_type !== "CLOUD_API" ) { blockers . push ( { code : "phone:not-registered" , message : `platform_type is ${phone.platform_type ?? "missing"}: the number isn't registered on Cloud API.` , fix : "POST /{PHONE_NUMBER_ID}/register with messaging_product and a 6-digit pin" , } ) ; } else if ( phone . status !== "CONNECTED" ) { blockers . push ( { code : `status:${phone.status}` , message : `Number status is ${phone.status}; only CONNECTED numbers send and receive.` } ) ; } if ( phone . code_verification_status === "NOT_VERIFIED" ) { warnings . push ( { code : "phone:not-verified" , message : "The number hasn't completed SMS/voice verification." } ) ; } if ( phone . name_status === "EXPIRED" ) { blockers . push ( { code : "name:expired" , message : "The display name certificate expired; the number can't be registered with it." } ) ; } else if ( phone . name_status === "DECLINED" ) { warnings . push ( { code : "name:declined" , message : "The display name was declined." , fix : "Submit a name that follows the display name guidelines" } ) ; } else if ( phone . name_status === "PENDING_REVIEW" ) { warnings . push ( { code : "name:pending" , message : "The display name is still in review." } ) ; } if ( phone . account_mode === "SANDBOX" ) { warnings . push ( { code : "mode:sandbox" , message : "account_mode is SANDBOX: the business is unverified (trial experience)." } ) ; } const review = s . waba ? . account_review_status ; if ( review === "REJECTED" ) { blockers . push ( { code : "waba:rejected" , message : "The account failed review against Meta's policies." } ) ; } else if ( review === "PENDING" ) { blockers . push ( { code : "waba:pending" , message : "The account is still in review and can't be used with the APIs yet." } )
Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.