Talk to Human Flow Plan

Talk to Human Flow Plan

This document is divided into two releases:

1. MVP: shopper asks for human support and AI provides best contact channel (WhatsApp first, then support email, then admin email).
2. Version 2: full human handover/takeover system with support inbox, agent assignment, and live human messaging.

The plan is aligned with AppiFire’s current chat stack (ChatSession, ChatMessage, /api/chat, widget settings, and chat logs).

---

1) MVP — Talk to Human Contact Flow

1.1 Goal

• If shopper asks to talk to a human, do not attempt full live handover in MVP.
• AI should immediately give contact instructions using configured support channels.
• Contact priority in MVP:
  1. WhatsApp number (from settings)
  2. Support email (from settings)
  3. Admin email fallback (from shop/admin data)

1.2 Shopper behavior (MVP)

Trigger examples:

• “I want to talk to a human”
• “connect me to support”
• “human agent please”
• “chat with real person”

Flow:

1. Shopper asks for human support.
2. AI detects human-intent.
3. AI responds with contact details based on fallback hierarchy.

Response logic:

• If WhatsApp exists:
  • “For human support, please contact us on WhatsApp: .”
• Else if support email exists:
  • “For human support, please email us at .”
• Else:
  • “For human support, please contact us at .”

Optional additional line:

• “Please include your order number for faster help.”

1.3 Settings changes required (MVP)

Add support contact fields in Settings screen:

• supportWhatsappNumber (String, optional)
• supportEmail (String, optional)

Admin email fallback source:

• use existing shop/admin identity available in DB (example: shop.shopEmail).
• if multiple candidates exist, define deterministic fallback in code and document it.

Validation:

• WhatsApp: allow +, digits, spaces, -, parentheses.
• Support email: standard email format validation.
• If both are empty, show warning in settings:
  • “No support contact configured. AI will fallback to admin email.”

1.4 Backend and prompt behavior (MVP)

• Include support contact config in chat runtime context (or inject via prompt builder/server context).
• Update support-agent prompt instruction:
  • when human intent is detected, return contact channel by configured fallback.
• No new support queue, no claim/assign, no live takeover in MVP.

1.5 MVP screens

1. Settings page update (app.settings.jsx)

   • Add “Talk to Human (MVP)” section.
   • Fields:
     • WhatsApp number
     • Support email
   • Save and validation UI.

2. No new inbox screen in MVP

   • Chat remains AI-driven.
   • Human support happens outside widget (WhatsApp/email).

1.6 MVP data model

Add fields on Shop:

• supportWhatsappNumber String? @map("support_whatsapp_number")
• supportEmail String? @map("support_email")

No new chat/handover tables required for MVP.

1.7 MVP rollout checklist

• Add settings fields to DB + migration.
• Expose fields via settings loader/action.
• Add validation + helper copy in settings UI.
• Update prompt/runtime so AI follows fallback order:
  • WhatsApp -> support email -> admin email.
• Test all fallback combinations:
  • both present
  • only WhatsApp
  • only support email
  • none present (admin email fallback).

---

2) Version 2 — Full Human Handover and Takeover

This section is the complete live-support version (all advanced features from the original plan).

2.1 Goals

• Let shoppers request a human anytime from chat.
• Create an internal support queue for waiting conversations.
• Let human agents open a conversation and take over from AI.
• Enable live two-way messaging between shopper and human agent.
• Preserve full audit trail for compliance, analytics, and quality checks.

---

2.2 Conversation mode model

Use explicit modes:

• ai (default)
• waiting_for_human
• human (takeover active)
• resolved (closed)

Rules:

• In human mode, AI auto-replies are paused.
• Agent replies are sent from support workspace to widget.
• Agent can hand conversation back to AI manually.
• All mode changes are logged.

---

2.3 Data model (Version 2)

Extend chat models for handover operations.

A) Extend ChatSession

Add fields:

• conversationMode (ai | waiting_for_human | human | resolved)
• supportRequestedAt (DateTime?)
• humanTakenOverAt (DateTime?)
• resolvedAt (DateTime?)
• assignedAgentId (String?; app user/staff reference)
• assignedAgentName (String?)
• priority (low | normal | high | urgent)
• lastCustomerMessageAt (DateTime?)
• lastAgentMessageAt (DateTime?)

B) Extend ChatMessage

Add fields:

• senderType (customer | ai | human_agent | system)
• agentId (nullable)
• agentName (nullable)
• isPrivateNote (Boolean; agent-only internal note, not shown to shopper)

C) Add SupportHandoffEvent table (recommended)

Tracks timeline events:

• request created
• assigned/reassigned
• agent joined
• returned to AI
• resolved
• SLA breached

Fields:

• id, chatSessionId, eventType, eventBy, eventByName, meta, createdAt

---

2.4 Admin screens (Version 2)

Screen 1: Support Inbox (new)

Route example: /app/support-inbox

Purpose:

• Queue of conversations needing human attention.

Sections:

• Waiting for human
• In progress (human takeover)
• Resolved (recent)

Columns:

• Customer (name/email or guest)
• Last message preview
• Waiting time / SLA timer
• Priority
• Assigned agent
• Actions: Claim, Open, Reassign, Resolve

Core actions:

• Claim conversation
• Assign to teammate
• Mark priority
• Mark resolved

Screen 2: Live Conversation View (new or extend chat logs)

Route example: /app/support-inbox/:sessionId

Purpose:

• Full timeline + realtime messaging with shopper.

Panels:

• Left: queue list
• Center: conversation timeline
• Right: customer context (identity, order snapshot, prior conversations, tags)

Controls:

• “Take over” (switch mode to human)
• “Return to AI”
• “Resolve”
• “Internal note”
• “Send canned response”

Message composer:

• sends human_agent message to widget in near realtime.

Screen 3: Support Settings (new section in Settings)

Configure:

• Enable/disable human handoff feature
• Auto-detect human intent (on/off)
• Offline behavior (collect email / fallback copy)
• SLA targets (first response time)
• Notification channels (email/Slack/webhook)
• Business hours and auto-reply outside hours

---

2.5 Widget changes (Version 2)

• Add “Talk to human” CTA in chat UI.
• Show status badges:
  • “AI assistant”
  • “Waiting for human”
  • “Human agent connected”
• Show system events in timeline:
  • “Support request sent”
  • “Agent joined”
  • “Conversation handed back to AI”
• Support receiving human messages from backend channel.
• Prevent duplicate support requests in same session.

---

2.6 API and backend flow (Version 2)

A) New/updated endpoints

1. POST /api/chat/request-human

   • Sets session to waiting_for_human
   • Creates handoff event
   • Triggers notifications

2. GET /api/support/inbox

   • Returns queue by status/priority/assignment

3. POST /api/support/takeover

   • Sets session mode to human
   • Sets assigned agent
   • Logs takeover event

4. POST /api/support/message

   • Sends human reply to chat session
   • Creates ChatMessage with senderType = human_agent

5. POST /api/support/return-to-ai

   • Sets mode back to ai
   • Logs event

6. POST /api/support/resolve

   • Marks session resolved
   • Logs event

B) Existing /api/chat behavior change

When session mode is:

• ai: current behavior unchanged
• waiting_for_human: return waiting message (no LLM reply)
• human: do not generate AI response; return “agent will reply” ack (or no-op)

---

2.7 Realtime delivery strategy

Two options:

1. Polling (fast to ship)

   • Widget polls for new messages every 2-3 seconds while open.
   • Admin conversation view also polls.

2. WebSocket/SSE (best UX)

   • Push new human/AI/system messages instantly.
   • Better typing indicators and agent presence.

Recommended rollout:

• Phase 1 with polling.
• Phase 2 upgrade to SSE/WebSocket.

---

2.8 Notification strategy

On waiting_for_human:

• In-app inbox badge/count.
• Email notification to support mailbox (optional).
• Slack webhook notification (optional).

Notification payload:

• shop
• customer identity
• session id
• last customer message
• link to open conversation in Support Inbox

Dedupe:

• Do not send repeated alerts for same session within cooldown window.

---

2.9 Permissions and roles

Add access control:

• support_admin: can configure settings, assign/reassign, resolve.
• support_agent: can claim and reply, add notes, resolve assigned chats.
• viewer: read-only access to logs.

Guard all support endpoints with server-side auth checks.

---

2.10 Metrics and reporting

Track:

• number of human handoff requests
• first response time
• time to resolution
• takeover rate by shop
• unresolved backlog
• AI-to-human escalation reasons

Use SupportHandoffEvent + ChatSession timestamps for analytics.

---

2.11 Edge cases and rules

• Duplicate request: keep single open request per session.
• No agent online: show offline message + collect contact details.
• Agent closes browser mid-chat: session remains human but unassigned after timeout.
• Shopper leaves and returns: keep mode state; show latest messages.
• Abuse/spam: allow “block conversation” and moderation notes.

---

2.12 Version 2 rollout phases

Phase 1 — Core handoff

• Session mode fields
• request-human endpoint
• support inbox list
• manual takeover + manual reply
• polling-based updates

Phase 2 — Full operator workflow

• assignment/reassignment
• internal notes
• resolve/reopen
• SLA timers and priority
• notifications (email/slack)

Phase 3 — Advanced operations

• canned responses
• macros/playbooks
• business hours/offline automation
• SSE/WebSocket realtime
• analytics dashboard

---

2.13 File-level implementation map (Version 2)

• prisma/schema.prisma
  • add support fields on ChatSession and ChatMessage
  • add SupportHandoffEvent model
• app/routes/api.chat.jsx
  • mode-aware reply behavior
• app/routes/api.support.*.jsx
  • inbox/takeover/message/resolve endpoints
• app/routes/app.support-inbox.jsx
  • support queue screen
• app/routes/app.support-session.$sessionId.jsx
  • live takeover conversation screen
• app/routes/app.settings.jsx
  • support handoff settings card/section
• extensions/appifire-chat/assets/chat-widget.js
  • talk-to-human button, waiting state, human/system message rendering

---

3) Final implementation sequence

1. Build and release MVP first:
   • Settings fields (supportWhatsappNumber, supportEmail)
   • AI fallback contact logic (WhatsApp -> support email -> admin email)
2. Validate support conversion and usage.
3. Build Version 2 live handover/takeover system after MVP is stable.

---

4) Success criteria

MVP success

• Shopper asking for human always gets a valid contact path.
• Contact fallback always works in configured priority.
• No dead-end response when WhatsApp/support email are missing.

Version 2 success

• Shopper can request handoff inside widget.
• Agents can take over and reply live.
• AI pauses during human takeover.
• Conversation can be resolved or returned to AI.
• Full event and message audit is preserved.