Troubleshooting

First of all: follow the message's path

A conversation always follows the same path. Finding out where it breaks resolves most cases:

Channel → Hub → Webhook → Queue → Agent

1. Channel — is the connection active? The channel card shows the last event received.
2. Hub — did the hub receive the event? Compare the time of the last event with the time of the test.
3. Webhook — did the endpoint respond 2xx? Rejected deliveries appear in the webhook log.
4. Queue — did the conversation enter Awaiting response in the right queue?
5. Agent — is the status online and the capacity not full?

Frequent symptoms

I can't send text

Cause	Solution
24-hour window closed (WhatsApp/Meta)	Send an approved template
Chosen template is not approved	Wait for approval at the provider
Channel disconnected	Reconnect the channel on the channels card
Role without send permission	Ask the administrator to review the role

Messages arrive but don't show up in the Inbox

1. Check the channel's default queue — it may have been changed.
2. Confirm the Inbox filters (it's easy to get stuck in a tag or "unread" filter).
3. Check whether the conversation was archived by mistake.
4. If none of that, use search everything by the customer's phone number: the conversation may be linked to another contact.

An agent doesn't receive conversations

1. Presence status: away doesn't receive distribution.
2. Capacity per member reached.
3. The agent is not a member of the channel's default queue.
4. The queue's distribution mode is manual — in that case, someone has to take it.

Expired session on the channel card (WhatsApp coexistence)

Coexistence mode keeps the phone active and the session can drop. Reconnect the channel from the card: the webhooks are recreated and messages start coming in again. The previous history is not lost.

MFA blocking access

An administrator without MFA configured is blocked at login, by a server decision. Complete the TOTP setup with the authenticator app. If you lost your phone and the backup codes, you need to contact platform support.

Login rejected even with the correct password

1. IP restrictions — are you outside the allowed range?
2. Attempt limit — wait for the release window (the response is 429).
3. Deactivated user — ask the administrator to reactivate it.

Campaign errors

Code	What to do
mapping_incomplete	Complete the field map: cover all the template parameters and use existing columns
audience_invalid_csv	The CSV needs a header and at least one data row, in UTF-8
template_not_approved	Choose a template approved on the channel
schedule_in_past	Choose a future date
report_not_eligible	The chosen report cannot be a campaign audience

AI assistant doesn't respond

1. Does the conversation have an AI session in the hub? Without a session there is no summary or suggestion.
2. Does the channel have an AI agent configured?
3. Does the company have the required features enabled (for example, CX Score)?

The MCP assistant doesn't connect

Symptom	Probable cause
401 with WWW-Authenticate	The client has no token — redo the authorization
403 forbidden_origin	The client sends Origin and it isn't the agents2.me app
429	Exceeded 120 calls/minute on the connection
Tool doesn't appear	Your role doesn't have permission for it
Stopped working after 30 days	The refresh token expired: authorize again

See OAuth and security.

What to send to support

To speed up the diagnosis, gather:

1. When it happened (time with time zone).
2. Which conversation/contact/campaign (id or link).
3. Which user and which role was acting.
4. What was expected and what happened.
5. The complete error message, including the code.

Without items 1 and 2 the diagnosis starts from scratch — with them, it almost always ends on the first reply.