# Message statuses

> Every status a message can have, how it looks in the chat, what changes it, and what the common failure reasons mean.

Source: https://docs.soosh.io/reference/message-statuses/

Each message you send shows its status as a small icon next to the time in
[**Inbox > Chats**](https://app.soosh.io/chat). WhatsApp reports progress as it happens, and the icon
updates without a refresh.

## The statuses

| Status | In the chat | What it means | What changes it |
|---|---|---|---|
| <span class="tag">Pending</span> | Grey clock | Soosh has saved the message and not yet handed it to WhatsApp. | WhatsApp accepts it (**Sent**) or refuses it (**Failed**). A campaign retry also puts failed messages back to **Pending**. A message still **Pending** after 15 minutes becomes **Failed**: see [Messages Soosh gave up on](#messages-soosh-gave-up-on). |
| <span class="tag">Sent</span> | One grey tick | WhatsApp accepted the message. It hasn't reached the customer's phone yet. | WhatsApp reports delivery (**Delivered**), a read (**Read**) or an error (**Failed**). |
| <span class="tag">Delivered</span> | Two grey ticks | The message reached the customer's phone. | WhatsApp reports a read (**Read**) or an error (**Failed**). |
| <span class="tag">Read</span> | Two blue ticks | The customer opened the message. | Nothing. **Read** is the last step. |
| <span class="tag">Failed</span> | Red alert icon, **Not delivered** under the last message of a run, and the reason under the message | The message did not reach the customer. | Nothing. A failed message stays failed. |
| <span class="tag">Received</span> | No icon | A message from the customer. Only messages you send have a status icon. | Not applicable. |

The app shows the grey clock for **Pending** and for any status it doesn't
recognise.

## How a message moves between statuses

- A message only moves forward: **Pending**, **Sent**, **Delivered**, **Read**.
  It can skip a step. For example, **Sent** can go straight to **Read** if
  WhatsApp reports the read first.
- A late report for an earlier step is ignored. A **Delivered** report that
  arrives after **Read** changes nothing.
- **Failed** can replace any other status, once. After that the message stays
  **Failed**.
- Campaign recipients use the same statuses, with the same order. See
  [Campaign statuses](https://docs.soosh.io/reference/campaign-statuses/).

### Messages imported from the WhatsApp Business app

When you [connect a number you use in the app](https://docs.soosh.io/guides/workspace/connect-a-number-you-use-in-the-app/),
Soosh imports earlier messages with the status WhatsApp had for them.

| WhatsApp reports | Soosh shows |
|---|---|
| Read or played | Read |
| Delivered | Delivered |
| Error | Failed |
| Anything else, or nothing | Sent |

## What you can do with a failed message

| Message | What the chat offers |
|---|---|
| Text, media and other messages you typed | A **Retry** button beside the bubble when you point at it. It sends the same content as a new message and removes the failed one from the chat. |
| Template messages | The reason only. There is no retry button. |

## Failure reasons in the chat

The reason appears under a failed message, and in the **Status** column of a
campaign's recipient list. If WhatsApp gives a code Soosh has no wording for,
the app shows WhatsApp's own description. If it has no description either, the
message shows **Failed to send**.

### Sending and delivery

| What the app says | What it means |
|---|---|
| It's been more than 24 hours since this customer last messaged you. Send an approved template to restart the conversation. | The 24-hour window is closed, so only a template can go out. See [The 24-hour window](https://docs.soosh.io/concepts/the-24-hour-window/). |
| WhatsApp couldn't deliver to this number. The person may not use WhatsApp, or may need to update the app or accept its latest terms. | The number can't receive this message right now. |
| This customer has stopped marketing messages from your business. | The customer turned off your marketing messages in WhatsApp. Soosh marks the contact as opted out of marketing. A customer who replies `STOP` is marked before any send fails. See [Marketing opt-out](https://docs.soosh.io/concepts/marketing-opt-out/). |
| WhatsApp held back this marketing message so the customer doesn't get too many. Try again after 24 hours. | WhatsApp limits how many marketing messages one person gets. |
| Too many messages were sent to this contact in a short time. Wait a little before sending another. | WhatsApp's limit on messages to one contact was reached. |
| This number is sending messages faster than WhatsApp allows. Wait a moment and try again. | The number hit WhatsApp's sending speed limit. |
| WhatsApp is limiting messages from this number because of its quality rating. Check it in WhatsApp Manager. | The number's quality rating is restricting what it can send. See [Messaging limits and number quality](https://docs.soosh.io/concepts/messaging-limits-and-number-quality/). |
| A business number can't send messages to itself. | The recipient is one of your own WhatsApp numbers. |
| WhatsApp doesn't support this type of message. | The message type isn't available to this number. |
| WhatsApp couldn't download the customer's file. | The file the customer sent can't be fetched. |
| WhatsApp couldn't process this file. Check that its type and size are supported. | The file you sent is an unsupported type or too large. |
| This business isn't allowed to message people in that country. | WhatsApp blocks business messages to that country for this account. |
| Marketing messages aren't turned on for this account on the Cloud API. | The WhatsApp account can't send marketing messages yet. |

### Template messages

| What the app says | What it means |
|---|---|
| The number of variables doesn't match the template. Fill in every variable. | The values sent are fewer or more than the template has. |
| A template variable isn't in the format the template expects. | A value doesn't match the type the template expects. |
| A template variable is set up incorrectly. Check the variables and try again. | A variable in the template is misconfigured. |
| The filled-in template is too long. Shorten the variable values. | The message is over WhatsApp's length limit once the variables are filled in. |
| This template doesn't exist in that language or isn't approved yet. | The template isn't **Approved** in that language. See [Template statuses](https://docs.soosh.io/reference/template-statuses/). |
| This template's content breaks WhatsApp's policies. | WhatsApp refused the template's content. A rejected template shows the reason on its page. |
| WhatsApp paused this template because of low quality. Edit it and submit it again. | The template is **Paused**. Once you edit it, it becomes a **Draft** and offers **Republish**. See [Template statuses](https://docs.soosh.io/reference/template-statuses/). |
| WhatsApp permanently disabled this template. Create a new one. | The template is **Disabled**. |

### Account and connection

| What the app says | What it means |
|---|---|
| WhatsApp no longer accepts this number's access token. Reconnect it under Settings → WhatsApp numbers. | The connection to Meta has expired or been revoked. |
| This WhatsApp connection is missing a permission it needs. Reconnect the number and approve every permission Facebook asks for. | The connection was set up without a required permission. |
| Meta has locked this WhatsApp account. Check its status in WhatsApp Manager. | Meta locked the account. |
| Meta has temporarily restricted this WhatsApp account for a policy violation. Check Account quality in WhatsApp Manager. | A temporary restriction after a policy violation. |
| There's a problem with this WhatsApp account's payment method. Check billing in WhatsApp Manager. | Meta can't charge the account's payment method. |
| This number isn't registered with the WhatsApp Cloud API. Register it and try again. | The number's registration with WhatsApp is incomplete. |
| This number's display name hasn't been approved yet. Check it in WhatsApp Manager. | Meta hasn't approved the number's display name. |

### Temporary problems

| What the app says | What it means |
|---|---|
| WhatsApp didn't respond in time. Try again in a moment. | WhatsApp took too long to answer. |
| Couldn't reach WhatsApp right now. Try again in a moment. | Soosh couldn't connect to WhatsApp. |
| WhatsApp is having trouble right now. Try again in a few minutes. | WhatsApp returned a server error. |
| WhatsApp is getting too many requests from this account. Wait a few minutes and try again. | WhatsApp is limiting how fast this account can make requests. |
| WhatsApp is under maintenance. Try again in a few minutes. | WhatsApp is in planned maintenance. |

### Messages Soosh gave up on

A message that is still **Pending** 15 minutes after you sent it is failed by
Soosh. These come from Soosh, not WhatsApp. They also appear on messages sent
with an API key and on campaign messages.

| What the app says | What it means |
|---|---|
| Not sent in time | Soosh never handed the message to WhatsApp, so it wasn't sent. |
| WhatsApp didn't confirm this message in time | Soosh handed the message to WhatsApp but never heard what became of it. The customer may have got it, so a campaign's **Retry failed** leaves it out. |

### Campaign-only reasons

These come from Soosh, not WhatsApp, and appear in a campaign's recipient list.

| What the app says | What it means |
|---|---|
| Contact opted out of marketing messages | The contact opted out of marketing and the template is **Marketing**. Soosh skipped them. |
| WhatsApp account not found | The number the campaign sends from was removed. |
| Failed to create contact | Soosh couldn't create a contact for the recipient's number. |

## Related

- [Reply to a customer](https://docs.soosh.io/guides/inbox/reply-to-a-customer/)
- [Reply after the 24-hour window](https://docs.soosh.io/guides/inbox/reply-after-the-24-hour-window/)
- [Retry failed messages](https://docs.soosh.io/guides/campaigns/retry-failed-messages/)
- [The 24-hour window](https://docs.soosh.io/concepts/the-24-hour-window/)
- [Marketing opt-out](https://docs.soosh.io/concepts/marketing-opt-out/)
- [Messaging limits and number quality](https://docs.soosh.io/concepts/messaging-limits-and-number-quality/)
- [Template statuses](https://docs.soosh.io/reference/template-statuses/)
- [Campaign statuses](https://docs.soosh.io/reference/campaign-statuses/)