> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpressbot.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Messages Not Received

> Customers message you on WhatsApp but nothing shows up in the inbox.

## What is this?

The most common WhatsApp problem: customers say they sent a message, but it never appears in your inbox, and automations or AI agents don't react to it. Almost always the cause is one of two things, depending on **how your number was connected**:

| How you connected | What must be true |
| - | - |
| **Tech Provider / Partner** or **Solution Partner** (the platform's app) | Your WhatsApp account must be **subscribed to the platform's app** |
| **Direct Cloud API** (your own Meta app) | The **App Secret** of your app must be **saved** on the channel, and the webhook must point at the platform |

If you don't remember how it was connected, open **Channels → WhatsApp** and check the steps below — the first one tells you.

## What can I do here?

* Check whether your number is subscribed to the platform's app, and fix it
* Add your own app's App Secret so messages are accepted
* Rule out the other usual causes

## How to use it

### Step 1 — Check message receiving

1. Go to **Channels → WhatsApp**.
2. Look at **WhatsApp Health** on the number's card. If it shows **Messages may not reach you**, read the line under it:
   * *This account is not subscribed to \[app name] (app ID …), so incoming messages may not arrive.* → go to **Case A**.
   * Nothing about subscription, but you use your own Meta app → go to **Case B**.
3. You can also open **More actions (⋯) → Apps**. **Subscribed Apps** lists every app receiving this account's WhatsApp events. *No apps subscribed* means nothing is receiving them.

### Case A — Using the platform's app: subscribe the number

Your number's WhatsApp account has to be subscribed to the platform's app, because that app is what delivers customers' messages to the platform. If it isn't, messages never arrive.

1. Open **More actions (⋯) → Apps**.
2. If the dialog shows **Messages may not reach you**, it names the app your account should be subscribed to and lists what it is subscribed to now (*Currently subscribed: …*).
3. Click **Reconnect**. This runs the connect flow again and subscribes the account to the platform's app. Approve every permission Meta asks for.
4. Re-open **Apps** — the platform's app should now be in the list, and the warning gone.
5. Ask the customer to send a new message to test.

If it still isn't subscribed after reconnecting, click **Create support ticket** in the same dialog. Include the number, how it was connected, and a screenshot of **Apps**.

> [!NOTE]
>
> This usually happens after the number or account was connected somewhere else, reconnected through another provider, or access was removed in Meta. It can also affect a number that was connected before the platform's app was set up.

### Case B — Using your own Meta app: add the App Secret

When you connect with **Direct Cloud API**, Meta sends customer messages through **your own app**. To be sure each request really came from Meta, the platform checks its signature with your app's **App Secret**. **If the secret isn't saved, the platform rejects every incoming message** (the request is turned away as an *invalid webhook signature*), so nothing arrives.

1. In **Meta for Developers**, open your app → **App settings → Basic** and copy the **App secret**.
2. In the platform, go to **Channels → WhatsApp** and scroll to **Webhook Configuration** under the number's card.
3. Paste the secret into **App Secret** and save. You'll see *App Secret saved successfully.*
4. Check Meta is pointing at the platform: in your Meta app open **WhatsApp → Configuration**, and set **Callback URL** to the **Webhook URL** shown in **Webhook Configuration**, and **Verify token** to the **Verify Token** shown there. Subscribe to the **messages** field (and any others you use).
5. Send a test message to the number. In **Webhook Configuration** the webhook should show **Active** with a **Last event**.

Saving the App Secret also tells the platform that this number uses **your** app — so it stops expecting the platform's app, and the *not subscribed* warning goes away.

> [!WARNING]
>
> Use the App Secret of the **same** Meta app that your number's webhook is set up on. A secret from a different app makes every request fail the signature check, exactly as if none were saved.

### Step 2 — Rule out the other usual causes

| Check | What to do |
| - | - |
| The channel is **Connected** and is the **active** channel | On **Channels** the card says **Connected**. Use **Switch Channel** if you are looking at the wrong channel's inbox |
| Your inbox filters | In the [Inbox](https://docs.xpressbot.org/workspace/inbox/conversations-list.md), clear filters and check **Resolved**, **Archived**, **Blocked** and **Unsubscribed** tabs. Team members limited to **See Assigned Only** only see chats assigned to them |
| The access token expired | **WhatsApp Health** shows a problem, or the failed-send reason mentions the token. Use **Settings** on the card to paste a new token, or **Reconnect** for Embedded Signup numbers |
| The phone isn't registered | Use **Register Phone** on the card (6-digit PIN). See [Number and account problems](https://docs.xpressbot.org/troubleshoot/whatsapp/number-and-account.md) |
| The webhook verification fails in Meta | The **Verify token** in Meta must match the one shown in **Webhook Configuration** exactly |
| The number was moved | If the number now belongs to another account or provider, the old connection stops receiving — **Reconnect** to attach it again |

## Troubleshooting / Technical Notes

* **Meta says the webhook can't be verified.** The Verify token or Callback URL doesn't match what's shown in **Webhook Configuration** (own app) or in the platform's setup (platform's app). Copy them again.
* **The warning is still there after I saved the App Secret.** Refresh the page and open **Apps** again. If it persists, confirm you saved the secret on the right number (each number has its own).
* **Only some customers' messages are missing.** Check those contacts aren't **Blocked** or **Unsubscribed**, and check the inbox filters.
* **Sending works but receiving doesn't.** That is exactly the subscription / App Secret problem above — sending uses your access token and works independently.
* **Still stuck.** [Create a support ticket](https://docs.xpressbot.org/workspace/support.md) with the number, how it was connected, and screenshots of **WhatsApp Health** and **Apps**.

## Related docs

* [Troubleshoot overview](https://docs.xpressbot.org/troubleshoot/overview.md)
* [WhatsApp channel](https://docs.xpressbot.org/workspace/channels/whatsapp.md)
* [Number and account problems](https://docs.xpressbot.org/troubleshoot/whatsapp/number-and-account.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.