---
title: Chat Health | API Docs
description: How we score the health of a chat and how it relates to your line's standing.
---

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 intent signals as the scoring gets smarter.

Every chat carries a `health_status` — the field you can check **before sending** to decide what to do with the next outbound on that conversation. While there isn’t a direct link between deliverability and chat health, it is a prediction and analysis of messaging behavior. You’ll see it on every chat-related webhook event and on every chat read. Treat it as a pre-send gate, not as much a report.

## How to use it

We recommend you do whatever is best for your messaging use case, but one example could be to cache the most recent `health_status.status` from your webhook stream and check it as a pre-flight before queueing each outbound:

```
switch (chat.health_status.status) {
  case 'HEALTHY':   send(message); break;
  case 'AT_RISK':   checkReplyRate(); break;
  case 'CRITICAL':  pause(chat); break;
  case 'OPTED_OUT': skip(chat); // terminal — never resume sending
}
```

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)     | Healthy conversation.                                                                               | Send normally.                                        |
| [`AT_RISK`](#at-risk)     | Poor engagement signals, which may lead to worsening health if current messaging patterns continue. | Slow outbound on this chat and check your reply rate. |
| [`CRITICAL`](#critical)   | Strong signals that messages aren’t landing well.                                                   | Pause messaging on this chat until healthy.           |
| [`OPTED_OUT`](#opted-out) | The recipient asked you to stop.                                                                    | Terminal. Immediately stop messaging this chat.       |

### healthy

The chat looks like a normal conversation. Replies are landing, delivery signals look good, and no opt-out language has been detected. No action needed.

### at-risk

One or more soft signals suggest this chat is heading in the wrong direction. Common drivers:

- **Low engagement.** The ratio of recipient replies to your sends is low.

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

- **Slow outbound on this chat.** Reduce send frequency until you see a reply.
- **Check your reply rate.** If the recipient isn’t responding, sending more rarely helps — adjust your message content to be more likely engaged with.
- **Vary your content.** Repeated near-identical messages amplify the signal.

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

### critical

Strong signals that messages on this chat aren’t reaching the recipient the way you expect. Continuing to send is unlikely to help and may make the situation worse for the broader line.

Recommended action: Pause this chat. Re-engage only after chat becomes healthy again.

### opted-out

The recipient sent an opt-out keyword on this chat. This is terminal: regardless of any other signals, do not send further outbound messages on this chat.

The full set of opt-out keywords:

`STOP`, `UNSUBSCRIBE`, `OPTOUT`, `CANCEL`, `END`, `QUIT`

Currently, matching is exact and case-sensitive against the inbound message.

If the recipient later sends the opt-in keyword `OPTIN` (same matching rules), the opt-out clears and the chat moves back to whichever health bucket current signals indicate.

## Chat health and line health

Chat health rolls up into the overall [health of the line](/guides/phone-numbers/phone-health/index.md) it was sent from. Many `AT_RISK` or `CRITICAL` chats on a single line increase the chance that the line will be flagged by our systems or carriers.

That said, **chat health is not the only thing that affects line standing.** We are continuously improving our models to create a healthy ecosystem. See the [Phone Health guide](/guides/phone-numbers/phone-health/index.md) for the line-level view.

## Tips

- New chats start as `HEALTHY` and move to `AT_RISK`, `CRITICAL`, or `OPTED_OUT` as signals warrant.
- `updated_at` tells you when the status last changed; use it to detect rapid status drops in your dashboards.
- Switch on `health_status` according to the use cases above.