FAQ & troubleshooting

Where are messages stored? Where are comments stored?

• Support chat messages and tickets → Intercom (via your AW Chat backend). Postgres only keeps reads, durations, and CSAT overlays.
• Channel comments → PostgreSQL only (channel_comments).

Full matrix: Data model.

The chat is blank / nothing loads

1. serverUrl reachable; CORS_ORIGINS includes your app origin.
2. sessionToken valid JWT signed with the same JWT_SECRET as the backend (401 → onSessionExpired).
3. Parent has a height (<AWChat /> fills it).

"Network request failed" in the browser

Usually CORS or wrong serverUrl. Allow your origin + Authorization. No trailing path; correct https.

React Native: attach / upload does nothing

Pass onPickFiles. Without it the attach control is hidden. See React Native.

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

No real Intercom signals; no WebSocket. seen is inferred after an operator reply. Behavior · Limitations.

Why polling and not WebSocket?

Deliberate constraint — simpler ops. Latency ≈ poll interval (default 4s).

How many concurrent users can one backend handle?

Roughly ~660 before Intercom rate limits dominate (with caching). Scale with Redis-backed cache + rate limits. Deployment.

Why topic buttons instead of a text box?

No open request → user picks a reason first; leaf selection starts the request. Topics are admin-managed (reasons table).

Operator closed the chat but the app still shows it open

Updates on the next poll (~4s). If never: check Webhooks HMAC / URL.

User rated a ticket twice

CSAT is idempotent per (user, ticket); second submit may return { duplicate: true }.

File uploads aren't downloadable after redeploy

Without S3, files sit on container disk (UPLOAD_DIR) and vanish on replace. Set S3_* and REQUIRE_S3=1 in production.

Push isn't arriving

• Device registered (fcmToken / telegramChatId props).
• Notification prefs on.
• FCM_SERVICE_ACCOUNT / TELEGRAM_BOT_TOKEN configured.

React Native: "Unable to resolve react-native-svg" / "react-native-fast-image"

Install the peers: pnpm add react-native-svg react-native-fast-image (Expo usually has svg). react-native-fast-image renders all SDK images and plays the animated-WebP channel emoji — the SDK uses no expo-image.

React Native: channel emoji show but don't animate

react-native-fast-image must be in the host binary (it can't be added over the air). On iOS the SDK feeds it a resolved asset URI so its WebP coder animates the bundled emoji; if animation still doesn't play, serve the WebP files from your CDN and the SDK will fetch them as remote images.

Account switch shows another user's channel data

Remount <AWChat /> when userId / sessionToken change.

How do I test without a backend?

demo prop, or the examples/ apps' Mock/Live toggle against your staging API — see Try it — example apps.

Archive in the hub does nothing useful

Coming soon by design — Limitations.