# End-to-end flow and integration runbook

This document explains how the CS Agent works from customer message to staff action, including LiveChat, AI routing, Telegram alerts, CS handoff, and BO usage.

---

## 1. Current production rule

CS remains the bridge between the customer and internal teams.

Payment and tech teams can receive alerts or provide internal feedback, but the customer reply is handled in LiveChat by CS unless the client changes SOP later.

Telegram sends internal alerts. Customer replies still happen in LiveChat by default.

Controlled two-way Telegram replies are available for authorised internal use through explicit commands such as `/reply <case_id> <customer-facing message>`. Normal Telegram discussion is not forwarded to customers.

## 2. Main customer path

```
Customer
  -> Portal (portal.ikon168.com) or LiveChat direct link
  -> LiveChat widget popup opened from floating widget, Chat Support, or Open LiveChat
  -> LiveChat conversation
  -> CS Agent connector polls message
  -> If there are multiple questions, split and answer each topic briefly
  -> Orchestrator classifies intent
  -> Domain agent answers or escalates
  -> Customer sees AI reply in LiveChat
```

If the case is routine, the AI answers directly using the approved knowledge base.

If the case requires human support, the system sends an internal Telegram alert and the CS team continues with the customer in LiveChat.

## 3. Demo and UAT path

```
Tester
  -> CS Agent web demo
  -> POST /chat
  -> Orchestrator
  -> Domain agent
  -> Web demo response
```

Use the web demo for internal UAT and staff training. Use LiveChat for final production validation.

## 4. Internal escalation path

```
Customer issue detected
  -> AI marks escalation team
  -> SQLite stores escalation
  -> Telegram bot posts alert to configured group
  -> Staff read summary and conversation context
  -> CS opens LiveChat conversation or uses controlled Telegram /reply command
  -> Customer receives the reply in LiveChat
  -> Payment/tech/admin continue internal resolution as needed
```

The Telegram alert helps staff see what happened quickly. Random Telegram messages are not customer replies; only explicit `/reply` commands are forwarded.

## 5. Routing map

| Customer issue | AI route | Telegram alert group | Customer reply owner |
|----------------|----------|----------------------|----------------------|
| Deposit not reflected | Payment | Payment group | CS in LiveChat |
| Scam deposit / fraud wording | Payment or admin urgent path | Payment or admin group | CS in LiveChat |
| Deposit to wrong bank | Payment | Payment group | CS in LiveChat |
| Withdrawal pending | Payment | Payment group if unresolved/escalated | CS in LiveChat |
| Login/access issue | Tech | Tech/CS group after retries | CS in LiveChat |
| App/platform error | Tech | Tech/CS group after retries | CS in LiveChat |
| Promo question | Promo | Usually none unless unknown/unclear | AI or CS if escalated |
| Unknown promo / unsupported claim | Promo/Admin | Admin group if escalated | CS in LiveChat |
| Account closure | Account/Admin | Admin group | CS in LiveChat |
| Police/scam/lawyer/sue/chargeback keywords | Urgent/admin | Admin group | CS in LiveChat |

## 6. AI response rules for go-live

| Rule | Expected behavior |
|------|-------------------|
| Greeting | Use one short greeting at the start only. |
| Follow-up messages | Do not repeat greeting. Acknowledge issue and ask the next needed detail. |
| Tone | Short, direct, professional. |
| Detail collection | Ask one missing detail at a time where practical. |
| Payment issues | Ask for username first, then receipt/transaction details as needed. |
| Deposit receipt | If receipt/proof is sent, acknowledge it and ask username if missing; do not end the conversation. |
| Withdrawal status | Ask for username first. Do not ask transaction ID by default unless payment team specifically needs it later. |
| Turnover/account data | Do not invent account-specific turnover or account status. Ask username, attempt controlled BO lookup when enabled, and escalate for CS verification. |
| BO/live data | Use controlled read-only BO lookup only when configured; otherwise ask username and route to CS/payment for manual checking. |
| Multiple questions | Answer each topic briefly in the same reply. |
| Tech issues | Ask for username or error message first, then device/screenshot as needed. |
| Unknown information | Do not invent. Ask for clarification or escalate. |
| Handoff wording | Say the support team will follow up in this chat; do not say Telegram replies reach the customer. |

## 7. Example scenario: deposit not reflected

1. Customer says: "My deposit is not reflected."
2. AI acknowledges the issue and asks for the username first.
3. Customer provides username.
4. AI attempts a controlled BO deposit lookup if `BO_LOOKUP_MODE=rpa` is enabled; otherwise it routes for manual checking.
5. Payment Telegram group receives an alert.
6. CS opens the LiveChat conversation.
7. Payment team verifies the BO result or checks manually.
8. CS replies to the customer in LiveChat with the approved update.

## 8. Example scenario: login issue

1. Customer says: "I cannot login."
2. AI asks for username or the error message.
3. AI gives short troubleshooting steps if appropriate.
4. If issue continues after configured retries, tech/CS Telegram group receives an alert.
5. CS coordinates with tech internally.
6. CS replies to the customer in LiveChat.

## 9. Example scenario: urgent complaint

1. Customer mentions scam, police, lawyer, chargeback, fraud, or similar urgent wording.
2. AI immediately routes to human handoff.
3. Admin Telegram group receives urgent alert.
4. CS takes over in LiveChat.
5. Admin/compliance decides next internal action.

## 10. LiveChat integration steps

| Step | Action | Pass condition |
|------|--------|----------------|
| 1 | Confirm IKON168 Customer Portal (portal.ikon168.com) or LiveChat direct link. | Testers can open the LiveChat popup from the floating widget or page buttons. |
| 2 | Confirm production LiveChat account ID and PAT in server `config/.env`. | Connector starts without auth error. |
| 3 | Send normal question through LiveChat. | AI reply appears in same conversation. |
| 4 | Send payment escalation through LiveChat. | Telegram alert appears; CS can reply in LiveChat. |
| 5 | Send tech issue through LiveChat and continue after retries. | Tech/CS alert appears. |
| 6 | Activate kill switch. | New messages receive handoff behavior. |
| 7 | Resume AI. | AI responds again. |

## 11. Telegram integration steps

| Step | Action | Pass condition |
|------|--------|----------------|
| 1 | Add bot to payment, tech/CS, and admin groups. | Bot is visible in each group. |
| 2 | Configure group IDs in `config/.env`. | Routing map works. |
| 3 | Trigger payment escalation. | Payment group receives alert. |
| 4 | Trigger tech escalation. | Tech/CS group receives alert. |
| 5 | Trigger urgent/admin escalation. | Admin group receives alert. |
| 6 | Reply to a Telegram escalation with `/reply <case_id> <message>`. | Customer receives that message in LiveChat. |
| 7 | Run `/resolve <case_id>`. | Escalation is marked resolved. |
| 8 | Run `/status`. | Bot returns system stats. |
| 9 | Run `/killswitch` and `/resume` with approved operator. | AI pause/resume works. |

## 12. BO / RPA integration status

The BO lookup layer exists and is intentionally read-only. It can run through RPA when `BO_LOOKUP_MODE=rpa` is enabled and BO credentials/IP/device approval are valid.

If BO/RPA is not enabled:

- AI remains RAG-first.
- Payment/tech checks are done by staff in BO.
- CS replies to customers in LiveChat.

If BO/RPA is enabled:

- Verify BO login, IP/device restrictions, and access rights.
- Test lookup flows using non-sensitive test accounts.
- Confirm the AI does not expose internal BO data that should remain private.
- Confirm customer replies stay controlled: the AI may say records were found or not clear, but CS still verifies the final status.

BO API status:

- No official BO API credential/base URL is configured in this repo.
- The BO frontend exposes internal browser endpoints, but those need client/vendor approval before they are used as an API integration.
- The code is structured so an official API adapter can replace RPA later without changing the customer flow.

## 13. Operational controls

| Control | Path | Purpose |
|---------|------|---------|
| Health check | `GET /health` | Uptime monitoring. |
| Stats | `GET /stats` | Conversation and RAG status; protect with Basic Auth. |
| Kill switch | Telegram `/killswitch` or `POST /killswitch` | Pause AI for incidents or manual takeover. |
| Resume | Telegram `/resume` or `POST /resume` | Resume AI after incident. |
| Logs | Docker logs / `logs/` | Troubleshooting. |

## 14. Go-live validation sequence

1. Confirm docs and credentials handover are complete.
2. Confirm production DNS and HTTPS.
3. Confirm dashboard auth.
4. Confirm knowledge base is final and indexed.
5. Run web demo UAT.
6. Run LiveChat UAT.
7. Trigger payment, tech, and admin Telegram alerts.
8. Confirm CS can reply to customer in LiveChat for each escalated case.
9. Test kill switch and resume.
10. Get RR/Kate sign-off.
11. Enable production widget/direct link for users.