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_IDbelow 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_APIonce 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 onlyCONNECTED. -
code_verification_status:VERIFIEDorNOT_VERIFIED, for the SMS or voice code. -
name_status:APPROVED,AVAILABLE_WITHOUT_REVIEW,PENDING_REVIEW,DECLINED,EXPIREDorNONE.EXPIREDmeans the display name certificate expired and "cannot be used to register the phone number for API use". -
account_mode:SANDBOX("The account is unverified") orLIVE. -
whatsapp_business_manager_messaging_limit: the messaging limit, asTIER_250,TIER_2K,TIER_10K,TIER_100KorTIER_UNLIMITED(the enum also listsTIER_50andUNTIERED). -
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 anadditional_infoarray explaining why. -
BLOCKED: "does not meet one or more messaging or calling requirements", with anerrorsarray oferror_code,error_descriptionandpossible_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_subcodeas 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 becomesphone: 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_appsreturnsdata[].whatsapp_business_api_data.idfor 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." });
}
fromHealth(phone.health_status, blockers, warnings);
for (const t of s.templates) fromHealth(t.health_status, blockers, warnings);
const tier = phone.whatsapp_business_manager_messaging_limit?.toUpperCase() ?? "";
const portfolioLimit = tier in TIER_LIMITS ? TIER_LIMITS[tier] : STARTING_LIMIT;
const sendWarnings = warnings.filter((w) => w.code !== "webhooks:not-subscribed");
const send = blockers.length ? "no" : sendWarnings.length || phone.health_status?.can_send_message === "LIMITED" ? "limited" : "yes";
return { send, receive, portfolioLimit, blockers: dedupe(blockers), warnings: dedupe(warnings) };
};
const dedupe = (list: Finding[]) => [...new Map(list.map((f) => [`${f.code}|${f.message}`, f])).values()];
A few rules worth explaining:
-
Registration comes first. A number added to a WABA isn't registered: Meta's phone numbers guide says adding numbers does "not register the number for Cloud API use". The fix is
POST /{PHONE_NUMBER_ID}/registerwithmessaging_product: "whatsapp"and a 6-digitpin. Watch the limit: "10 requests per business number in a 72-hour moving window". Going over it returns 133016, and the number is blocked from registering until the window clears. Don't retryregisterin a loop. -
A missing limit means the starting limit. New business portfolios "have a messaging limit of 250". Meta doesn't document what
UNTIEREDmeans, and the webhooks useTIER_NOT_SETfor a number that "has not been used to send a message yet". Our choice: when the value is either of those, or missing, plan for 250 rather than showing nothing. -
Template health is the cheapest pre-send check. A template that isn't approved comes back
BLOCKEDwith 141002, "Message templates can only be sent out if they are approved", and Meta's own fix text. Checking it before a campaign beats discovering 132001 on every recipient. -
Sandbox and display name review are warnings. Meta doesn't publish a single rule for what an unverified or not-yet-approved number can send, and its health example puts a pending display name under
LIMITED, notBLOCKED. So these become "limited", with the reason shown to the user.
Keeping it current
A readiness check run once at connect time goes stale. Accounts get restricted, names get approved, limits go up, and businesses disconnect your app from Meta's side. Meta tells you through account-level webhooks, and none of them carries the whole picture, so treat them as a signal to re-read rather than as state:
// Account-level webhooks don't carry the whole picture. Use them as a signal to re-read, and
// apply the few values they do carry directly.
export type Change = { field: string; value: Record<string, any> };
export type Recheck = { wabaId: string; reason: string; tier?: string; urgent: boolean };
const URGENT_ACCOUNT_EVENTS = new Set([
"ACCOUNT_VIOLATION", "ACCOUNT_RESTRICTION", "DISABLED_UPDATE", "ACCOUNT_DELETED",
"ACCOUNT_OFFBOARDED", "PARTNER_APP_UNINSTALLED", "PARTNER_REMOVED",
]);
export const recheckFor = (wabaId: string, change: Change): Recheck | null => {
const v = change.value ?? {};
switch (change.field) {
case "account_update":
return { wabaId, reason: `account_update ${v.event}`, urgent: URGENT_ACCOUNT_EVENTS.has(v.event) };
case "account_review_update":
return { wabaId, reason: `account review ${v.decision}`, urgent: v.decision !== "APPROVED" };
case "phone_number_name_update":
return { wabaId, reason: `display name ${v.decision} for ${v.display_phone_number}`, urgent: false };
case "phone_number_quality_update":
case "business_capability_update":
return { wabaId, reason: change.field, tier: v.max_daily_conversations_per_business, urgent: false };
case "account_alerts":
return { wabaId, reason: `alert ${v.alert_info?.alert_type}`, urgent: v.alert_info?.alert_severity === "CRITICAL" };
default:
return null; // messages, statuses, templates... handled elsewhere
}
};
// Collapse a burst of webhooks into one re-read per account, keeping the most urgent reason.
export const coalesce = (rechecks: Recheck[]): Recheck[] => {
const byWaba = new Map<string, Recheck>();
for (const r of rechecks) {
const prev = byWaba.get(r.wabaId);
if (!prev) { byWaba.set(r.wabaId, { ...r }); continue; }
byWaba.set(r.wabaId, {
wabaId: r.wabaId,
reason: prev.urgent || !r.urgent ? prev.reason : r.reason,
tier: r.tier ?? prev.tier,
urgent: prev.urgent || r.urgent,
});
}
return [...byWaba.values()];
};
The fields to subscribe to, all in the webhooks reference:
-
account_update: restrictions (ACCOUNT_RESTRICTION, withrestriction_info), violations,DISABLED_UPDATE(withban_info),ACCOUNT_OFFBOARDEDandPARTNER_APP_UNINSTALLED. These are the urgent ones. -
account_review_update:decisionisAPPROVED,REJECTED,PENDINGorDEFERRED. -
phone_number_name_update: a display name was reviewed;decisionplusrejection_reason. -
phone_number_quality_updateandbusiness_capability_update: carry the new limit inmax_daily_conversations_per_business. The oldercurrent_limitandmax_daily_conversation_per_phonewere deprecated and scheduled for removal in February 2026, so read the new field. -
account_alerts: includes the outcome of a limit increase request (INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED,…_FAILED,…_NEED_MORE_INFO).
Coalescing matters more than it looks. A restriction can arrive alongside a capability update for the same account, and you want one Graph read, flagged urgent, not two. Run urgent re-reads straight away; the rest can wait for a short debounce.
Also keep a slow periodic re-read, every few hours. Webhooks get missed, and some changes made in Meta's own tools never produce one you'd act on.
What the quality rating no longer does
A lot of older guides tell you to watch quality_rating because a drop lowers your limit, or flags the number. That changed in October 2025. Per Meta's messaging limit changes: "The Flagged phone number quality state is no longer possible", and "If your business phone number quality rating drops, its messaging limit will not be downgraded."
Quality still matters for going up. Above 2,000, the portfolio's limit "increases by one level within 6 hours" if it sends high-quality messages and has used "at least half of your current messaging limit" in the last 7 days. So show quality to the business as "how fast you can grow", not as "how close you are to being cut off". Getting from 250 to 2,000 is different: verify the business, or send 2,000 delivered messages outside customer service windows to unique users within 30 days using high-quality templates.
Mapping send errors back to readiness
When a send fails anyway, these codes mean "re-run the readiness check", not "retry the message":
| Code | Meta's description | Readiness meaning |
|---|---|---|
| 133010 | Phone number not registered on the WhatsApp Business Platform | Register the number |
| 131031 | Restricted or disabled for a policy violation, or request data such as the two-step PIN didn't match the account | Read health_status for the reason |
| 368 | The account has been restricted or disabled for violating a platform policy | Policy enforcement; see Meta's policy enforcement docs |
| 131042 | There was an error related to your payment method | Billing, not the number |
| 130497 | The account is restricted from messaging users in certain countries | Account-level restriction |
| 132001 | The template doesn't exist in the specified language or hasn't been approved | Template health |
Retrying any of these just burns the attempt and, for registration, the 10-per-72-hours budget.
What WAPGROWAI does today, and what it doesn't
Our channel settings page is a readiness check, so here's how it compares with the code above:
-
We read:
status,name_status,code_verification_status,platform_type,quality_ratingandwhatsapp_business_manager_messaging_limitfrom the phone number, andaccount_review_statusfrom the WABA, and show them as badges. -
We reconcile connection state from Meta's
status, so a number disconnected or deleted on Meta's side is marked disconnected on our side on the next read, and a reconnected one heals itself. That read happens when someone opens the channel settings page, and after a failed send. -
We update the limit from
phone_number_quality_updateas soon as it arrives. -
We don't read
health_statusyet. That's the biggest gap: a business-level restriction can sit behind a number our badges show as fine. -
We don't handle
account_update, and there's no periodic re-read. A restriction or an uninstall shows up only when someone opens the settings page or a send fails. -
A failed
subscribed_appscall during signup is only logged, which is exactly the "can send, never receives" state described above. It should fail the connection. -
Two badges guess when Meta says nothing: with no
account_review_statuswe show the account as verified if it's connected, and with noname_statuswe show the display name as approved if one exists. A readiness check should show "unknown" instead. -
We still treat
FLAGGED,RESTRICTEDandRATE_LIMITEDas connected-but-limited. That predates Meta's "connected only" wording and the retirement of the flagged state.
Checklist
- Read readiness from Meta, not from your own connect-time record.
- Check
platform_typeandstatus === "CONNECTED"before anything else. - Request
whatsapp_business_manager_messaging_limit, notmessaging_limit_tier, and remember it's per portfolio. - Treat a missing or unset limit as the starting 250.
- Request
health_statuson the number, and on the templates a campaign will use. - Treat Graph "does not exist" (100/33) as a state, and an expired token as an error.
- Verify your app is in
subscribed_apps; fail the connection if subscribing fails. - Subscribe to
account_update,account_review_update,phone_number_name_update,phone_number_quality_update,business_capability_updateandaccount_alerts, and use them to trigger re-reads. - Don't retry
registerin a loop: 10 attempts per 72 hours. - Show "unknown" when Meta doesn't say, never a guessed green.
WAPGROWAI is built by DI Solutions, a custom software and AI development company. This series covers what we've learned building WAPGROWAI on the WhatsApp Cloud API. Related: one Meta app, many businesses: routing webhooks in a multi-tenant SaaS and WhatsApp Cloud API rate limits in practice.
Top comments (0)