Chat Health

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.

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.

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.

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

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.

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 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. See the Phone Health guide for the line-level view.

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