---
title: Phone Health | API Docs
description: How we score the health of a phone line and how to check it before you send.
---

Note

This feature is currently in beta and may be inaccurate at times. We are actively improving our health score models. Expect additional engagement and activity signals as the scoring gets smarter.

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](/guides/chats/chat-health/index.md), 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](/guides/chats/chat-health/index.md).
- **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`](/api/resources/phone_numbers/methods/list/index.md). It’s distinct from the runtime [`status`](/guides/phone-numbers#status-changes/index.md) 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.

## How to use it

- **[`GET /v3/phone_numbers`](/api/resources/phone_numbers/methods/list/index.md)** — every line in the list response carries its current `health_status`.
- **[`phone_number.status_updated`](/guides/webhooks/events#phone-number-events/index.md) 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.

## Statuses

| status                  | What it means                                                       | What to do                                                                          |
| ----------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [`HEALTHY`](#healthy)   | The line is in good standing.                                       | Send normally.                                                                      |
| [`AT_RISK`](#at-risk)   | The line’s conversations or its overall activity are trending down. | Slow the line’s overall send pace and use chat health to find conversations to fix. |
| [`CRITICAL`](#critical) | Strong signals that messages from this line aren’t landing well.    | Pause outbound on the line until it recovers.                                       |

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](/guides/chats/chat-health#opted-out/index.md).

### healthy

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.

### at-risk

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](/guides/chats/chat-health/index.md) 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](/guides/chats/chat-health/index.md) 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).

### critical

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`.

## Phone health and chat health

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

- **[Chat health](/guides/chats/chat-health/index.md)** 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.

## Tips

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

## Related

- [Phone Numbers](/guides/phone-numbers/index.md) — discover and monitor your lines
- [Chat Health](/guides/chats/chat-health/index.md) — per-conversation health scoring
- [API Reference: List Phone Numbers](/api/resources/phone_numbers/methods/list/index.md)