# AI Chatbot Integration — Answers & Open Questions (app ↔ backend) **Date:** 2026-07-01 · **Audience:** backend team (Neel) + app team **Source of truth so far:** `docs/INTEGRATION.md` (backend) + code verification in this repo. Purpose: capture what's already settled (so we don't re-ask it), the app-side conclusions we bring, and the **still-valid open questions**. Every question below was checked against `INTEGRATION.md` — items their doc already answers are in §1, not repeated as questions. --- ## 1. Already settled (from `INTEGRATION.md` — do NOT re-ask) - **Endpoint:** single stateless `POST /chat`; backend owns retrieval, answer, escalation decision, safety, logging. - **Response fields (baseline):** `{ answer, escalate, escalate_reason, coach_summary }`. - **Escalation triggers:** medical, crisis, account-specific billing (paid-no-access, refund status), explicit "talk to a human", frustration, or no approved answer. - **Off-topic:** AI politely declines without involving a human. - **Freshchat role:** stays as the human layer / escalation destination; reused, not replaced. AI knowledge is restricted to approved content; Freshchat transcripts are **not** fed back into the AI. - **Frontend responsibilities:** call `/chat` with recent `history` + `program` + `platform`; render `answer`; on `escalate` route to Freshchat with `coach_summary` (+ transcript); optional thumbs up/down → `POST /feedback`. - **Surface approach:** both sides lean **Option A — app-owned chat surface, bridge to Freshchat on escalate** (not the Freshchat-widget-injection Option B). ## 2. App-side conclusions we bring (our answers) - **Native chat UI**, not a WebView (the AI is a headless API; the coach handoff is native Freshchat — a native screen is cleaner and lower-latency). ✅ matches their Option A. - **Handoff context via `Freshchat.setUserProperties(...)`** — verified in-use path ([freshchatUtils.js:162](../../../src/utils/freshchatUtils.js)). We attach `coach_summary` + a transcript link as user properties, then open the Coaching conversation. - **Full transcript** (if wanted in-thread) can be posted as a message via `Freshchat.sendMessage(...)` — verified in-use ([notification.js:501](../../../src/services/notification.js#L501)). `setUserProperties` values are short strings and **cannot** hold a full transcript. - **Canonical user id = `iUserId`**, env-prefixed (`test_` in non-prod) — the Freshchat `externalId` scheme ([freshchatUtils.js:36](../../../src/utils/freshchatUtils.js)). - **Program gating:** LeanSure (`P11`) users are restricted away from the Coaching channel in the app (`Constant.P11_VISIBLE_CHAT_TAGS`). - We can supply `program` + `platform` on every call from the logged-in user (already known to the app). --- ## 3. Open questions — 🔴 BLOCKERS (needed before client work) 1. **`API.md`** — can you share it? We need the exact field names, full request/response schema, and a curl example. (Referenced in your doc but not delivered.) 2. **Auth** — how is `/chat` authenticated? Can it validate the **QuitSure `accessToken`** the app already holds, or does it need its own key/header? We'd prefer it not be an open, unauthenticated endpoint (abuse + cost). 3. **Hosting** — you'll deploy; what's the **base URL**, and are there network constraints (IP allowlist, region)? Separate **staging vs prod** URLs? 4. **Transport confirmation** — we read `/chat` as a **single, non-streaming JSON response**. Correct? If long coach-style answers are expected, is response **streaming** (SSE/chunked) on the roadmap? (Affects how we render.) 5. **Timeout/latency** — expected p50/p95 latency and a recommended client timeout per call? ## 4. Open questions — 🟡 contract details 6. **`history` format** — what shape do you expect (role/message pairs)? How many recent turns should we send, and is there a **size/token cap**? 7. **`escalate_reason` values** — what's the exact enumerated set you return? We need it to map each reason to the correct Freshchat channel. 8. **Channel routing** — does the response tell us **which channel** to route to (Coaching vs Technical Issue), or do we derive it from `escalate_reason`? 9. **`coach_summary`** — expected max length and format? (We put it in a Freshchat user property, which is a short string.) 10. **`POST /feedback`** — request contract: what do we send (message id, up/down, optional reason)? Is a message/response id returned on `/chat` so we can reference it? ## 5. Open questions — 🟡 context & language 11. **Program codes** — please confirm the full mapping. Your doc lists `P3` / `P9`; the app also has `P11` = LeanSure. Which code = which program (Original / Relaxed / LeanSure / …)? 12. **Richer context** — you consume `program` + `platform` today. Would **active program-day**, **NF stage**, or **subscription status** improve stage-specific answers (the KB answers are tagged by day/stage)? If yes, we can send them. 13. **Language** — the app supports 7 languages (note: German uses resource key `ge`). Does the AI answer in the user's language, and should we pass a **locale**? ## 6. Open questions — 🟡 handoff, privacy & content 14. **Transcript in Freshchat** — you want `coach_summary` + transcript passed. Confirm our approach: `coach_summary` (+ link) via `setUserProperties`, and the **transcript posted as a message** via `Freshchat.sendMessage`. Acceptable? Any preferred format? 15. **Program gating (confirm)** — escalations for LeanSure (`P11`) must **not** land in the Coaching channel. Does your escalation output respect program gating, or should the app enforce channel selection? 16. **PII in `history`** — any constraints on what we may send (user messages can contain personal info)? Retention/logging policy on your side? 17. **Knowledge-base updates** — how/when is the KB (the Chat Shortcuts sheets) updated, who owns it, and is it versioned? (So answers stay current.) 18. **Seamless thread** — your open item: how do we make the AI→human handoff feel like one continuous conversation? Any expectation on your side (e.g., you post the AI answer into Freshchat on escalate), or is it entirely app-side? --- ## 7. Next steps - Send §3 blockers to backend first; the rest can be answered in parallel. - Once `API.md` + auth + transport are confirmed, reconcile [ai-chatbot-integration-design.md](ai-chatbot-integration-design.md) (§7 backend contract) and scope the app-side implementation.