DEV Community

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

Posted on

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:

  1. The phone number node. Is it registered on Cloud API, connected, verified, and is its display name approved?
  2. The account (WABA). Has it passed review?
  3. The business portfolio. It owns the messaging limit, which since October 2025 is shared by every number in the portfolio.
  4. Health status. Meta's own summary of whether the number, account, business and app "can send", with error codes and suggested fixes.
  5. 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,
  };
};
Enter fullscreen mode Exit fullscreen mode

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." });
  }

  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()];
Enter fullscreen mode Exit fullscreen mode

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}/register with messaging_product: "whatsapp" and a 6-digit pin. 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 retry register in a loop.
  • A missing limit means the starting limit. New business portfolios "have a messaging limit of 250". Meta doesn't document what UNTIERED means, and the webhooks use TIER_NOT_SET for 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 BLOCKED with 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, not BLOCKED. 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()];
};
Enter fullscreen mode Exit fullscreen mode

The fields to subscribe to, all in the webhooks reference:

  • account_update: restrictions (ACCOUNT_RESTRICTION, with restriction_info), violations, DISABLED_UPDATE (with ban_info), ACCOUNT_OFFBOARDED and PARTNER_APP_UNINSTALLED. These are the urgent ones.
  • account_review_update: decision is APPROVED, REJECTED, PENDING or DEFERRED.
  • phone_number_name_update: a display name was reviewed; decision plus rejection_reason.
  • phone_number_quality_update and business_capability_update: carry the new limit in max_daily_conversations_per_business. The older current_limit and max_daily_conversation_per_phone were 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_rating and whatsapp_business_manager_messaging_limit from the phone number, and account_review_status from 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_update as soon as it arrives.
  • We don't read health_status yet. 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_apps call 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_status we show the account as verified if it's connected, and with no name_status we show the display name as approved if one exists. A readiness check should show "unknown" instead.
  • We still treat FLAGGED, RESTRICTED and RATE_LIMITED as 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_type and status === "CONNECTED" before anything else.
  • Request whatsapp_business_manager_messaging_limit, not messaging_limit_tier, and remember it's per portfolio.
  • Treat a missing or unset limit as the starting 250.
  • Request health_status on 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_update and account_alerts, and use them to trigger re-reads.
  • Don't retry register in 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)