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.

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. Recommended playbook:

1. Check chat health. Pull chat health for the line’s conversations to find the AT_RISK and CRITICAL chats, and fix those first.
2. Slow the line’s overall pace. Reduce total send volume until signals recover.
3. Bias outbound toward messages that elicit replies. Questions and follow-ups outperform broadcasts.
4. Spread activity out. Avoid contacting many new recipients or opening many new conversations in a single burst.
5. 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.

Does phone health read message content or store any PII?

No. Phone health scoring runs on anonymous, aggregate signals — line-level volume, send/receive ratios, recipient counts, conversation pace, and similar metadata. Linq does not collect or store message content or other PII to compute health_status for phone numbers.

Why is there no OPTED_OUT on phone line health?

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.

Why are most of my high-volume lines AT_RISK?

Volume alone shouldn’t cause this. Check whether user reply rates dropped on those lines as they scaled — phone health weighs engagement relative to volume, not necessarily volume on its own; although, too many new chats sent at once within a short period can cause AT_RISK signals.

Is AT_RISK reversible?

Yes. The status reflects recent behavior. Improving send pace and engagement on the line returns it to HEALTHY as new signals come in.

Should I migrate users off an AT_RISK line?

No — fix the line. Migrating users off carries the same underlying sending pattern to a new line and spreads the issue rather than solving it. Use chat health to find the conversations dragging the line down, address those, and let the line recover.

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