# Connection Health

> Connection status, the live heartbeat, Check health now, delivery health, quality history, and recent calls - every part of the Health page.

Source: https://docs.theavoxai.com/health

Health is the first place to look when something feels off. It answers three questions: is your
number connected, is Meta reporting a problem with it, and are your messages getting delivered. The
header reads "Connection status and message delivery health, at a glance."

## Who can use Health

| Action | Admin | Manager |
| --- | --- | --- |
| View Health | Yes | Yes |
| Click **Check health now** | Yes | Yes |

Health needs a connected WhatsApp number. Until one is connected, the **Health** item in the sidebar
shows a lock with "This feature needs a WhatsApp connection first."
([AVX-3001](https://docs.theavoxai.com/error-codes/avx-3001)).

## Range and alerts

The `7d`, `30d`, and `90d` buttons at the top choose the window for the delivery charts and the
insights. Health opens on `30d`, and the range is part of the page address (`/health?days=7`).

Below the header, the same account alert banners as [Overview](https://docs.theavoxai.com/overview#account-alerts) appear when
something account-wide needs attention - an overdue payment, a canceled subscription, or a connection
that's in error, disconnected, or paused.

## Connection cards

Each WhatsApp number in the Switchboard gets its own card, newest first, showing:

- **Its name** (or phone number) and **Last active** - how long ago Avox last received an event for
  this number from Meta.
- **A status badge** - the connection's status, the same as on
  [Connections](https://docs.theavoxai.com/connections#connection-statuses): `connected`, `connecting`, `disconnected`,
  `error`, or `paused`. A connection paused because the subscription was canceled shows
  `billing paused`, with the line "Paused - this Switchboard's subscription was canceled." and a
  **Review billing** link.
- **A heartbeat label** with a pulsing dot - see [Heartbeat](#heartbeat).
- **Connection Health** - the **Check health now** button. See
  [Check health now](#check-health-now).

### Heartbeat

The heartbeat label tells you how recently your number was active, based on the last event Meta sent
Avox for it (a message, a status update, a template update, and so on):

| Label | Meaning |
| --- | --- |
| **Operational · heartbeat** (green) | Avox received an event for this number within the last 5 minutes. |
| **Degraded · heartbeat** (amber) | The last event arrived between 5 and 30 minutes ago. |
| **Down · heartbeat** (red) | Nothing for over 30 minutes, or nothing ever. |

> **Note**
>
> The heartbeat follows activity. A quiet number - for example overnight, when no customers message
> you - shows **Down** even though nothing is wrong. If you're unsure, click **Check health now** for
> Meta's own answer.

### Live heartbeat

Next to your connection cards, the **Live heartbeat** monitor shows the same signal as a moving trace.
It checks for new activity every few seconds:

- While the last event is under 30 minutes old, the trace beats and the counter shows "seconds since
  last heartbeat", ticking up live.
- After 30 minutes it flattens and reads "no recent heartbeat".
- Before any event has arrived, it's flat and reads "no heartbeat yet".

The monitor follows your most recently connected number.

## Check health now

**Check health now** asks Meta, live, whether your number can send messages right now. It uses Meta's
own WhatsApp Business health status, not Avox's activity data.

**1. Click Check health now**

The button shows "Checking" while Avox asks Meta.

**2. Read the checklist**

Each row has a green shield (all good) or a red shield (a problem), a label, and a plain-language
description. See the table below.

**3. See Meta's exact answer if you need it**

Click **View raw response** to open **Raw Meta response** ("Straight from Meta's health_status
field, unmodified."). This is useful when you contact [Support](https://docs.theavoxai.com/support) or check something in
WhatsApp Manager.

| Row | What it checks |
| --- | --- |
| **Can send messages** | Whether Meta allows this connection to send right now. Green reads "This connection can send messages right now."; otherwise it shows the status Meta reports. |
| **WhatsApp Business Account** | Any problem Meta reports on your WhatsApp Business Account. |
| **Phone number** | Any problem Meta reports on the phone number itself. |
| **Business verification** | Any problem Meta reports on your business portfolio. |
| **App configuration** | Any problem Meta reports on the app connected to your account. |

A row with no problems reads "No issues reported." A row with a problem shows Meta's own description,
followed by Meta's suggested fix when Meta provides one.

Results are kept for 60 seconds, for everyone in the Switchboard. Clicking again within a minute -
yours or a teammate's click - shows the same result instantly instead of asking Meta again. Before
your first check, the section reads "Not checked yet this session."

If Meta can't be reached, the section reads "Couldn't check this connection's health with Meta right
now." ([AVX-3080](https://docs.theavoxai.com/error-codes/avx-3080)). Wait a minute and try again. A connection that needs to be
reconnected also ends here - connect it again with the [setup wizard](https://docs.theavoxai.com/connections/setup).

## Delivery health

Two charts follow the selected range:

- **Delivery health right now** - a gauge showing the most recent day's delivery rate: the share of
  messages you sent that reached delivered or read. The label under the number reads **Excellent**
  (95% and up), **Good** (85% and up), **Watch this** (70% and up), or **Needs attention** (below 70%).
  With no messages, it shows `-` and "No messages yet".
- **Delivery rate** - the same percentage per day across the range. It's the same calculation as on
  [Overview](https://docs.theavoxai.com/overview) and [Analytics](https://docs.theavoxai.com/analytics), so the pages always agree.

## Quality history

A list of the quality and messaging-limit updates Meta has sent about your number, newest first. Each
row shows when it arrived and, when Meta included them:

- **Messaging tier** - your number's current messaging limit, as Meta names it (for example
  `TIER_1K`).
- **Quality event** - what changed, as Meta names it (for example `FLAGGED` or `UPGRADE`).

Before Meta sends any, the card reads "No quality updates from Meta yet." See
[Quality and limits](https://docs.theavoxai.com/whatsapp/quality-and-limits) for what these mean and how to improve them. How
long Avox keeps this history is set on [Compliance](https://docs.theavoxai.com/compliance).

## Recent calls

The 10 most recent call events for your Switchboard, with the contact, the direction and event (for
example "Inbound · Connect"), and when it happened. Use **Previous** and **Next** to page through, or
**View all →** to open [Calls](https://docs.theavoxai.com/calls). Before the first call, it reads "No calls yet."

## The Insights rail

On the right, the **Insights** card ("What's worth noticing right now") sums up the page. The
[Avox Avatar](https://docs.theavoxai.com/avox-avatar) at the top of the card is smug when all is well, unsure when something
deserves a look, and sad when something needs attention.

| Insight | When it appears |
| --- | --- |
| 1 connection hasn't reported a heartbeat in over 30 minutes. | A connection's heartbeat is **Down**. (Critical) |
| Meta flagged this number's quality recently - see Quality history below. | Quality history includes a `FLAGGED` event. |
| Delivery rate dropped 12 points over this window. | The last day's delivery rate is 10 or more points below the first day's. |
| Delivery rate has stayed strong across this window. | The last day's delivery rate is 95% or higher. |
| Nothing concerning - connections and delivery both look healthy. | None of the above apply. |

Under the card, **Learn more in the docs** opens this page.

## What to do when something's wrong

| You see | Try this |
| --- | --- |
| Status badge `error` or `disconnected` | Open the connection from [Connections](https://docs.theavoxai.com/connections) and check it. Use **Open in Meta** to look at the number in WhatsApp Manager. If it doesn't recover, reconnect the number with the setup wizard - see [Setup](https://docs.theavoxai.com/connections/setup). |
| `billing paused` | Resolve the payment on [Billing](https://docs.theavoxai.com/billing). The connection resumes on its own once the subscription is active again. |
| **Can send messages** is red | Read the description on the red rows and follow Meta's suggested fix. Then check again after a minute. |
| Delivery rate falling | Check [Quality history](#quality-history), your [templates](https://docs.theavoxai.com/templates/approval), and [Quality and limits](https://docs.theavoxai.com/whatsapp/quality-and-limits). |
| Heartbeat **Down** at a busy time | Check [Logs](https://docs.theavoxai.com/logs) for recent events and failures, then run **Check health now**. See also the [Status page](https://docs.theavoxai.com/status-page). |

For Meta's own error numbers, see [Meta error codes](https://docs.theavoxai.com/meta-error-codes).
