---
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` — a single enum that tells you, at a glance, the state and what to do with that chat. You’ll see it on chat-related webhook events. Use it as an early signal for which conversations are at risk of flagging a 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 degraded delivery. | Slow outbound on this chat and check your reply rate. |
| [`critical`](#critical)   | Strong signals that messages aren’t landing well.             | Stop the campaign on this chat; wait before retrying. |
| [`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.
- **Delivery may be degraded.** We’re seeing patterns consistent with reduced deliverability on this conversation.

`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 status returns to its previous state automatically.

## Chat health and line health

Chat health rolls up into the overall health of the line 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.

## Tips

- Switch on `health_status` according to the use cases above.
- 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.