Limitations & known behaviors

Things that look like bugs to pedantic QA but are by design or known product limits. Share this with integrators before stand testing.

Realtime

Expectation	Reality
WebSocket / live push into the SDK	HTTP polling only (default 4s; comments thread ~5s while open)
Instant operator reply	Appears within ~one poll interval after webhook + cache invalidate
Real “operator typing…”	Not available from Intercom. Mock mode fakes it; live mode may show a short local cue after creating a request — not presence
Real read receipts	Inferred: double-check when an operator message follows yours

See Behavior.

Product placeholders

UI	Status
Hub Archive	Coming soon screen — not implemented
Full offline mode (RN)	Optional @react-native-community/netinfo; without it the SDK backs off polls

Storage split (common confusion)

• Support messages → Intercom (not Postgres message rows).
• Channel comments → Postgres only.
• Closing the app clears SDK memory; history is reloaded from the server next open.

Full matrix: Data model.

Scale & ops

• Single API instance: rate limit, admin lockout, Intercom cache, and schedulers are in-memory. Multi-replica needs Redis + a single publisher for scheduled posts — Deployment.
• Intercom workspace rate limits (~10k API calls/min) are the real capacity ceiling for chat polling.
• Circuit breaker: after repeated Intercom failures the API fails fast (502) briefly, then probes again.

Client / host footguns

Issue	Fix
RN attach does nothing	Pass onPickFiles — without it the attach control is hidden
Files vanish after redeploy	Set S3 (REQUIRE_S3=1 in production); don’t rely on container disk
401 / empty chat after login	Mint JWT with shared JWT_SECRET; handle onSessionExpired
Wrong user’s channel/comments after account switch	Remount <AWChat /> (or change userId/sessionToken so the store re-inits)
CORS errors in browser	Set CORS_ORIGINS to the host app (+ admin) origins

Security / staging

• Leave ENABLE_DEVTOOLS / ENABLE_DEVTOOLS_RESET_ALL empty in any shared or production environment.
• Demo JWTs in examples/ are throwaway stand identities — never real customer tokens.
• Signed file URLs (/files/:id?t=…) are bearer-like until expiry; don’t paste sensitive attachments into public channels.

What we do support

• Adaptive poll back-off, localized error panels (never a blank screen).
• Magic-byte upload allow-list; comment DLP / link blocking.
• Admin permissions, audit log, comment moderation.
• FCM + Telegram push when configured.

For threat-oriented detail see Security.