FAQ & troubleshooting

The chat is blank / nothing loads

Check, in order:

• serverUrl is reachable and CORS allows your origin (the backend allows the Authorization header and reflects the origin).
• sessionToken is a valid JWT signed with the same JWT_SECRET as the backend. A 401 fires onSessionExpired.
• The container has a height — <AWChat /> fills its parent.

"Network request failed" in the browser

Almost always CORS or a wrong serverUrl. The backend must allow your origin and the Authorization header (it does by default). Confirm the URL has no trailing path and uses the right scheme.

Can we show "operator is typing…" or real read receipts?

No. Intercom's API and webhooks expose neither, and the design forbids WebSocket. sent/delivered are real; seen is inferred (an operator replied after the message). See Behavior.

Why polling and not WebSocket?

A deliberate constraint — simpler ops, no persistent connections. Latency is the poll interval (default 4s), with adaptive back-off on failure.

How many concurrent users can one backend handle?

Roughly 660 before Intercom's ~10k/min rate limit bites, thanks to the read cache and decoupled ticket polling. Scale out with Redis-backed cache + rate limiting. See Behavior.

Why does the chat show topic buttons instead of a text box?

When the user has no open request, they pick a topic first (main → sub "reason"). Choosing a leaf topic starts the request immediately — the thread opens with the operator acknowledgement, no typed message needed. Once a request is open, the normal composer is shown. Topics are admin-managed (reasons).

The operator closed the chat but the app still shows it open

It updates on the next poll (~4s) — the message poll also carries live state, so closes/reopens reflect without a reload. If it never updates, the webhook likely isn't firing; check Webhooks.

A user rated a ticket twice — what happens?

CSAT is idempotent per (user, ticket): the second submit returns { duplicate: true } and the SDK won't re-prompt (the ticket comes back rated: true).

File uploads aren't downloadable

GET /api/files/:id needs S3 configured (S3_*). Without it, uploads validate but aren't persisted.

Push isn't arriving

• Confirm the device registered (POST /api/devices/register, done automatically when fcmToken/telegramChatId is passed).
• Confirm the relevant notification preference is on.
• Confirm FCM_SERVICE_ACCOUNT / TELEGRAM_BOT_TOKEN are set — otherwise the senders no-op.

React Native: "Unable to resolve react-native-svg"

It's a peer dependency — install it (pnpm add react-native-svg). It's bundled with Expo.

How do I test without a backend?

Pass demo to <AWChat /> for mock data, or run the examples/ apps with the Mock/Live toggle.