Phone Health

Every phone line carries a health_status — a line-level read on whether the line as a whole is in good standing. It’s the line-wide companion to chat health, but it is not simply a sum of it.

Phone health draws on two kinds of signals:

• Patterns across the conversations on the line — engagement and deliverability across the line’s chats, in aggregate. This is the larger driver, and it’s closely related to chat health.
• Line-level activity that no single conversation reveals — how many different recipients the line messages in a short window, how many brand-new conversations it starts in a day, and its overall send pace.

You’ll see health_status on each number returned by GET /v3/phone_numbers. It’s distinct from the runtime status field (ACTIVE / FLAGGED): status is the line’s current sending state, health_status is a prediction of where the line is heading. Treat it as a pre-send gate, not a report.

• GET /v3/phone_numbers — every line in the list response carries its current health_status.
• phone_number.status_updated webhook — fires on both status (ACTIVE ↔ FLAGGED) and health_status changes. The payload carries previous_health_status and new_health_status, so you can react the moment a line moves to AT_RISK or CRITICAL.

Check health_status shape and value before you queue outbound messages for a line — the same pre-send gate pattern as chat health, one level up. Use it to route work toward your healthiest lines: if a line is CRITICAL, onboard new recipients onto a HEALTHY line instead and let the CRITICAL one recover before you send more on it.

const { phone_numbers } = await client.phoneNumbers.list();

for (const pn of phone_numbers) {
  switch (pn.health_status.status) {
    case 'HEALTHY':  break;                 // send normally, safe to onboard new recipients
    case 'AT_RISK':  reviewLine(pn); break; // slow the pace, check chat health
    case 'CRITICAL': pauseLine(pn); break;  // stop outbound, route new recipients elsewhere
  }
}

Acting on the status before each send is what turns the signal into delivery improvement — ultimately leading to a healthier line.

Unlike chat health, phone health has no OPTED_OUT status. Opt-out is a per-recipient signal scoped to a single conversation — it can’t apply to a whole line. You’ll only ever see OPTED_OUT on chat health.

The line looks like it’s operating normally. Engagement and deliverability across its conversations look good, and its overall activity is within a normal range. No action needed.

One or more soft signals suggest the line as a whole is heading in the wrong direction. Common drivers fall into two groups:

• Conversation patterns. Engagement is low across many of the line’s chats Chat health is the best place to see this per-conversation.
• Line-level activity. The line is reaching a large number of different recipients in a short window, starting many brand-new conversations in a single day, or its overall send volume spiked — patterns that look risky at the line level even when individual chats are fine.

AT_RISK is a warning, not a hard stop. What to do:

• Slow the line’s overall pace. Reduce total send volume until signals recover.
• Spread activity out. Avoid contacting many new recipients or opening many new conversations in a single burst.
• Check chat health. Pull chat health for the line’s conversations to find the AT_RISK and CRITICAL chats, and fix those first.
• Vary your content. Repeated near-identical messages across the line amplify the signal.

Watch for the line moving back to HEALTHY (good) or down to CRITICAL (act fast).

Strong signals that messages from this line aren’t reaching recipients the way you expect and could cause the line to become flagged. Continuing to send is unlikely to help and may make the situation worse.

Recommended action: pause outbound on the line. Re-engage only after it returns to HEALTHY.

Chat health and phone health are related but answer different questions:

• Chat health scores a single conversation — is this recipient engaging, are messages landing.
• Phone health scores the line — both the aggregate of its conversations and line-level activity that no single conversation reveals, like how broadly and how fast the line is messaging.

• New lines start as HEALTHY and move to AT_RISK or CRITICAL as signals warrant.

• Phone Numbers — discover and monitor your lines
• Chat Health — per-conversation health scoring
• API Reference: List Phone Numbers