diff --git a/src/SUMMARY.md b/src/SUMMARY.md index ded9c726..682f62fa 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -300,6 +300,8 @@ - [Multi-Agent Orchestration](./chapter-11-features/multi-agent-orchestration.md) - [Memory Management](./chapter-11-features/memory-management.md) - [Hybrid RAG Search](./chapter-11-features/hybrid-search.md) + - [Transfer to Human](./chapter-11-features/transfer-to-human.md) + - [LLM-Assisted Attendant](./chapter-11-features/attendant-llm-assist.md) # Part XI - Security diff --git a/src/appendix-external-services/README.md b/src/appendix-external-services/README.md index 4dc0e657..cb404d3f 100644 --- a/src/appendix-external-services/README.md +++ b/src/appendix-external-services/README.md @@ -54,12 +54,21 @@ llm-model,gpt-4o weather-api-key,YOUR_OPENWEATHERMAP_KEY whatsapp-api-key,YOUR_WHATSAPP_KEY whatsapp-phone-number-id,YOUR_PHONE_ID +whatsapp-verify-token,YOUR_WEBHOOK_VERIFY_TOKEN teams-app-id,YOUR_TEAMS_APP_ID teams-app-password,YOUR_TEAMS_PASSWORD instagram-access-token,YOUR_INSTAGRAM_TOKEN instagram-page-id,YOUR_PAGE_ID botmodels-enabled,true botmodels-url,http://localhost:5000 + +# Human Handoff / CRM Features +crm-enabled,true +attendant-llm-tips,true +attendant-polish-message,true +attendant-smart-replies,true +attendant-auto-summary,true +attendant-sentiment-analysis,true ``` ## Auto-Managed Services diff --git a/src/appendix-external-services/llm-providers.md b/src/appendix-external-services/llm-providers.md index b48cb8ee..37ebdc4b 100644 --- a/src/appendix-external-services/llm-providers.md +++ b/src/appendix-external-services/llm-providers.md @@ -47,15 +47,15 @@ Known for safety, helpfulness, and extended thinking capabilities. | Model | Context | Best For | Speed | |-------|---------|----------|-------| -| Claude Opus 4.5 | 200K | Most capable, complex reasoning | Slow | -| Claude Sonnet 4.5 | 200K | Best balance of capability/speed | Fast | +| Claude Opus | 200K | Most capable, complex reasoning | Slow | +| Claude Sonnet | 200K | Best balance of capability/speed | Fast | **Configuration (config.csv):** ```csv name,value llm-provider,anthropic -llm-model,claude-sonnet-4.5 +llm-model,claude-sonnet ``` **Strengths:** @@ -74,16 +74,15 @@ Google's multimodal AI models with strong reasoning capabilities. | Model | Context | Best For | Speed | |-------|---------|----------|-------| -| Gemini 3 Pro | 2M | Complex reasoning, benchmarks | Medium | -| Gemini 2.5 Pro | 2M | Extremely long documents | Medium | -| Gemini 2.5 Flash | 1M | Fast multimodal | Fast | +| Gemini Pro | 2M | Complex reasoning, benchmarks | Medium | +| Gemini Flash | 1M | Fast multimodal tasks | Fast | **Configuration (config.csv):** ```csv name,value llm-provider,google -llm-model,gemini-3-pro +llm-model,gemini-pro ``` **Strengths:** @@ -291,9 +290,9 @@ Use different models for different tasks: ```csv name,value llm-provider,anthropic -llm-model,claude-sonnet-4.5 +llm-model,claude-sonnet llm-fast-provider,groq -llm-fast-model,llama-4-scout +llm-fast-model,llama-3.3-70b llm-fallback-provider,local llm-fallback-model,DeepSeek-R1-Distill-Qwen-1.5B embedding-provider,local @@ -306,15 +305,15 @@ embedding-model,bge-small-en-v1.5 | Use Case | Recommended | Why | |----------|-------------|-----| -| Customer support | Claude Sonnet 4.5 | Best at following guidelines | -| Code generation | DeepSeek-R1, GPT-5 | Specialized for code | -| Document analysis | Gemini 3 Pro | 2M context window | -| Real-time chat | Groq Llama 4 Scout | Fastest responses | +| Customer support | Claude Sonnet | Best at following guidelines | +| Code generation | DeepSeek-R1, GPT-4o | Specialized for code | +| Document analysis | Gemini Pro | 2M context window | +| Real-time chat | Groq Llama 3.3 | Fastest responses | | Privacy-sensitive | Local DeepSeek-R1 | No external data transfer | -| Cost-sensitive | DeepSeek-V3.1, Local | Lowest cost per token | -| Complex reasoning | Claude Opus 4.5, Gemini 3 Pro | Best reasoning ability | -| Real-time research | Grok 4 | Live data access | -| Long context (10M) | Llama 4 Scout | Largest context window | +| Cost-sensitive | DeepSeek, Local models | Lowest cost per token | +| Complex reasoning | Claude Opus, Gemini Pro | Best reasoning ability | +| Real-time research | Grok | Live data access | +| Long context | Gemini Pro, Claude | Largest context windows | ### By Budget diff --git a/src/chapter-02/gbai.md b/src/chapter-02/gbai.md index a8950c2b..b41b3c4a 100644 --- a/src/chapter-02/gbai.md +++ b/src/chapter-02/gbai.md @@ -82,7 +82,7 @@ Each folder becomes a searchable collection. Drop files in, bot learns automatic Single `config.csv` file with key-value pairs: ```csv -llm-model,gpt-3.5-turbo +llm-model,your-preferred-model temperature,0.7 max-tokens,2000 welcome-message,Hello! How can I help? @@ -147,7 +147,7 @@ TALK "Ticket #" + ticket_id + " created" `config.csv`: ```csv -llm-model,gpt-3.5-turbo +llm-model,your-preferred-model bot-name,TechSupport greeting,Welcome to support! ``` diff --git a/src/chapter-11-features/attendant-llm-assist.md b/src/chapter-11-features/attendant-llm-assist.md new file mode 100644 index 00000000..ef8d094a --- /dev/null +++ b/src/chapter-11-features/attendant-llm-assist.md @@ -0,0 +1,497 @@ +# LLM-Assisted Attendant Features + +General Bots provides AI-powered assistance to human attendants during customer conversations. These features help attendants respond faster, more professionally, and with better context awareness. + +## Overview + +When the bot transfers a conversation to a human attendant (via `TRANSFER TO HUMAN`), the LLM orchestrator continues working in the background to assist the human. This creates a hybrid experience where AI augments human capability rather than replacing it. + +The system uses the same `PROMPT.md` and bot personality configured for the bot, ensuring consistency between bot responses and attendant assistance. + +## Features + +| Feature | Config Key | Description | +|---------|-----------|-------------| +| **Real-time Tips** | `attendant-llm-tips` | Contextual tips when customer messages arrive | +| **Message Polish** | `attendant-polish-message` | Improve grammar and tone before sending | +| **Smart Replies** | `attendant-smart-replies` | Generate 3 contextual reply suggestions | +| **Auto Summary** | `attendant-auto-summary` | Summarize conversation when attendant joins | +| **Sentiment Analysis** | `attendant-sentiment-analysis` | Real-time emotional state tracking | + +## Configuration + +Add these settings to your bot's `config.csv`: + +```csv +name,value + +# Enable all LLM assist features +attendant-llm-tips,true +attendant-polish-message,true +attendant-smart-replies,true +attendant-auto-summary,true +attendant-sentiment-analysis,true + +# Optional: Set bot personality for context +bot-system-prompt,You are a friendly customer service assistant for Acme Corp +bot-description,Premium support for enterprise customers +``` + +### Selective Enablement + +Enable only the features you need: + +```csv +name,value +attendant-smart-replies,true +attendant-sentiment-analysis,true +``` + +--- + +## Feature Details + +### 1. Real-time Tips (`attendant-llm-tips`) + +When a customer sends a message, the LLM analyzes it and provides actionable tips to the attendant. + +#### Tip Types + +| Type | Icon | Description | +|------|------|-------------| +| `intent` | 🎯 | What the customer wants | +| `action` | βœ… | Suggested action to take | +| `warning` | ⚠️ | Sentiment or escalation concern | +| `knowledge` | πŸ“š | Relevant info to share | +| `history` | πŸ“œ | Insight from conversation history | +| `general` | πŸ’‘ | General helpful advice | + +#### Example Tips + +Customer says: *"This is ridiculous! I've been waiting 3 days for a response!"* + +Tips generated: +- ⚠️ Customer is frustrated - use empathetic language and apologize +- 🎯 Customer has been waiting for support response +- βœ… Acknowledge the delay and provide immediate assistance + +#### API Usage + +```basic +' Internal API - automatically called by UI +POST /api/attendance/llm/tips +{ + "session_id": "uuid", + "customer_message": "message text", + "history": [{"role": "customer", "content": "..."}] +} +``` + +--- + +### 2. Message Polish (`attendant-polish-message`) + +Before sending, attendants can polish their message with one click. The LLM improves grammar, clarity, and tone while preserving the original meaning. + +#### Supported Tones + +- `professional` (default) +- `friendly` +- `empathetic` +- `formal` + +#### Example + +**Original:** *"ya we can do that but u need to wait til tmrw"* + +**Polished:** *"Yes, we can certainly help with that! Please allow until tomorrow for us to process your request."* + +**Changes:** Fixed grammar, improved clarity, added professional tone + +#### API Usage + +```basic +POST /api/attendance/llm/polish +{ + "session_id": "uuid", + "message": "original message", + "tone": "professional" +} +``` + +**Response:** +```json +{ + "success": true, + "original": "ya we can do that...", + "polished": "Yes, we can certainly...", + "changes": ["Fixed grammar", "Improved tone"] +} +``` + +--- + +### 3. Smart Replies (`attendant-smart-replies`) + +Generate three contextually appropriate reply suggestions based on the conversation history and bot personality. + +#### Reply Categories + +- `greeting` - Opening responses +- `answer` - Direct answers to questions +- `acknowledgment` - Empathetic acknowledgments +- `solution` - Problem-solving responses +- `follow_up` - Continuation questions +- `closing` - Conversation wrap-up + +#### Example + +Customer: *"How do I reset my password?"* + +**Suggested Replies:** + +1. **Empathetic:** "I understand how frustrating it can be when you can't access your account. I'll help you reset your password right away." + +2. **Solution-focused:** "To reset your password, please go to the login page and click 'Forgot Password'. You'll receive an email with reset instructions." + +3. **Follow-up:** "I can help you with that! Are you trying to reset the password for your main account or a sub-account?" + +#### API Usage + +```basic +POST /api/attendance/llm/smart-replies +{ + "session_id": "uuid", + "history": [ + {"role": "customer", "content": "How do I reset my password?"}, + {"role": "attendant", "content": "Hi! Let me help you with that."} + ] +} +``` + +--- + +### 4. Auto Summary (`attendant-auto-summary`) + +When an attendant takes a conversation, they receive an instant summary of what's happened so far. This is especially useful for: + +- Long conversations +- Transfers between attendants +- Complex multi-issue discussions + +#### Summary Contents + +| Field | Description | +|-------|-------------| +| `brief` | One-sentence overview | +| `key_points` | Main discussion points | +| `customer_needs` | What the customer wants | +| `unresolved_issues` | Open items | +| `sentiment_trend` | Improving/stable/declining | +| `recommended_action` | What to do next | +| `message_count` | Number of messages | +| `duration_minutes` | Conversation length | + +#### Example Summary + +```json +{ + "brief": "Customer requesting refund for damaged product received yesterday", + "key_points": [ + "Order #12345 arrived damaged", + "Customer sent photos as proof", + "Previous agent offered replacement" + ], + "customer_needs": [ + "Full refund instead of replacement", + "Confirmation email" + ], + "unresolved_issues": [ + "Refund approval pending" + ], + "sentiment_trend": "stable", + "recommended_action": "Escalate to supervisor for refund approval" +} +``` + +#### API Usage + +```basic +GET /api/attendance/llm/summary/{session_id} +``` + +--- + +### 5. Sentiment Analysis (`attendant-sentiment-analysis`) + +Real-time analysis of customer emotional state to help attendants respond appropriately. + +#### Analysis Components + +| Component | Values | Description | +|-----------|--------|-------------| +| `overall` | positive, neutral, negative | General sentiment | +| `score` | -1.0 to 1.0 | Numeric sentiment score | +| `emotions` | List | Detected emotions with intensity | +| `escalation_risk` | low, medium, high | Risk of escalation | +| `urgency` | low, normal, high, urgent | Message urgency | +| `emoji` | 😊😐😟 | Visual indicator | + +#### Example Analysis + +**Customer message:** *"I've been trying to get help for TWO WEEKS! This is absolutely unacceptable!"* + +```json +{ + "overall": "negative", + "score": -0.8, + "emotions": [ + {"name": "frustration", "intensity": 0.9}, + {"name": "anger", "intensity": 0.7} + ], + "escalation_risk": "high", + "urgency": "high", + "emoji": "😟" +} +``` + +The UI shows a warning: ⚠️ High escalation risk detected + +#### API Usage + +```basic +POST /api/attendance/llm/sentiment +{ + "session_id": "uuid", + "message": "customer message", + "history": [] +} +``` + +--- + +## WhatsApp Attendant Commands + +Attendants using WhatsApp can access LLM assist features via commands: + +### Queue Management + +| Command | Description | +|---------|-------------| +| `/queue` or `/fila` | View waiting conversations | +| `/take` or `/pegar` | Take next conversation | +| `/status [online\|busy\|away\|offline]` | Set your status | +| `/transfer @name` or `/transferir` | Transfer conversation | +| `/resolve` or `/resolver` | Mark as resolved | + +### AI Assistance + +| Command | Description | +|---------|-------------| +| `/tips` or `/dicas` | Get tips for current conversation | +| `/polish ` or `/polir` | Polish a message before sending | +| `/replies` or `/respostas` | Get smart reply suggestions | +| `/summary` or `/resumo` | Get conversation summary | +| `/help` or `/ajuda` | Show all commands | + +### Example Usage + +``` +Attendant: /queue +Bot: πŸ“‹ Queue (3 waiting) + 1. John Smith (whatsapp) + Status: waiting | ID: abc123 + 2. Maria Santos (web) + Status: waiting | ID: def456 + ... + +Attendant: /take +Bot: βœ… Conversation assigned + Customer: John Smith + Session: abc123 + +Attendant: /tips +Bot: πŸ’‘ Tips for this conversation + + 🎯 Customer is asking about billing + βœ… Check their account status before responding + ⚠️ Previous conversation ended unresolved + +Attendant: /polish thank u for waiting ill check ur account now +Bot: ✨ Polished message + + "Thank you for your patience! I'll check your account right now." + + Changes: + β€’ Fixed grammar + β€’ Improved professionalism + +Attendant: /resolve +Bot: βœ… Conversation resolved + Session abc123 marked as resolved. +``` + +--- + +## Web Attendant Console + +The web attendant console (`/suite/attendant/`) integrates LLM assist features directly: + +### Insights Panel + +The right sidebar shows: +- **Customer Sentiment** - Real-time with emoji indicator +- **Detected Intent** - What the customer wants +- **Conversation Summary** - Auto-generated when you select a conversation + +### Suggested Replies + +Below the insights, three AI-generated reply suggestions appear. Click any suggestion to insert it into the message input. + +### Polish Button + +The ✨ button next to the message input polishes your text before sending. + +### Tips Notifications + +When a customer sends a message: +1. Tips appear in the insights panel +2. High-priority tips show as toast notifications +3. Warning tips (escalation risk) are highlighted + +--- + +## Bot Personality Integration + +LLM assist uses your bot's personality when generating suggestions. Set this in `config.csv`: + +```csv +name,value +bot-system-prompt,You are a friendly tech support agent for CloudSoft Inc. Be helpful and patient. +bot-description,Enterprise software support +``` + +Or in your `start.bas` header: + +```basic +REM CloudSoft Support Bot +REM Friendly, patient, and technically knowledgeable +REM Always offer to escalate complex issues + +TALK "Welcome to CloudSoft Support!" +``` + +The LLM reads these comments to understand the bot's personality and applies the same tone to: +- Smart reply suggestions +- Message polishing +- Tips generation + +--- + +## API Reference + +### Endpoints + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/attendance/llm/tips` | Generate tips | +| POST | `/api/attendance/llm/polish` | Polish message | +| POST | `/api/attendance/llm/smart-replies` | Generate replies | +| GET | `/api/attendance/llm/summary/{session_id}` | Get summary | +| POST | `/api/attendance/llm/sentiment` | Analyze sentiment | +| GET | `/api/attendance/llm/config/{bot_id}` | Get config | + +### Check Configuration + +```basic +GET /api/attendance/llm/config/{bot_id} + +Response: +{ + "tips_enabled": true, + "polish_enabled": true, + "smart_replies_enabled": true, + "auto_summary_enabled": true, + "sentiment_enabled": true, + "any_enabled": true +} +``` + +--- + +## Fallback Behavior + +When LLM is unavailable, the system provides fallback functionality: + +| Feature | Fallback | +|---------|----------| +| Tips | Keyword-based analysis (urgent, problem, question) | +| Polish | Returns original message | +| Smart Replies | Generic template replies | +| Summary | Basic message count and duration | +| Sentiment | Keyword-based positive/negative detection | + +--- + +## Best Practices + +### 1. Start with Smart Replies + +If you're unsure which features to enable, start with `attendant-smart-replies`. It provides immediate value with low overhead. + +### 2. Enable Sentiment for High-Volume Support + +For teams handling many conversations, `attendant-sentiment-analysis` helps prioritize frustrated customers. + +### 3. Use Polish for Quality Consistency + +Enable `attendant-polish-message` to ensure consistent, professional communication regardless of individual writing skills. + +### 4. Tips for Complex Products + +For products with many features or complex workflows, `attendant-llm-tips` helps attendants quickly understand context. + +### 5. Summary for Shift Changes + +Enable `attendant-auto-summary` if your team has shift changes or frequent transfers between attendants. + +--- + +## Troubleshooting + +### "Feature is disabled" Message + +Add the feature to your `config.csv`: + +```csv +attendant-smart-replies,true +``` + +### Slow Response Times + +LLM calls add latency. If responses are slow: +- Use a faster LLM model +- Enable only essential features +- Check your `llm-url` configuration + +### Generic Suggestions + +If suggestions seem generic: +- Set `bot-system-prompt` in config.csv +- Add personality comments to `start.bas` +- Ensure conversation history is being passed + +### WhatsApp Commands Not Working + +1. Verify the attendant is registered in `attendant.csv` +2. Check that the phone number matches exactly +3. Ensure `crm-enabled,true` is set + +--- + +## See Also + +- [Transfer to Human](./transfer-to-human.md) - Bot-to-human handoff +- [Attendance Queue](../appendix-external-services/attendance-queue.md) - Queue configuration +- [LLM Configuration](../chapter-08-config/llm-config.md) - LLM setup +- [config.csv Format](../chapter-08-config/config-csv.md) - Configuration reference \ No newline at end of file diff --git a/src/chapter-11-features/transfer-to-human.md b/src/chapter-11-features/transfer-to-human.md new file mode 100644 index 00000000..1b542a72 --- /dev/null +++ b/src/chapter-11-features/transfer-to-human.md @@ -0,0 +1,634 @@ +# Transfer to Human + +The `TRANSFER TO HUMAN` keyword enables seamless handoff from bot conversations to human attendants. This is a critical feature for hybrid support workflows where complex issues require human intervention. + +## Overview + +When a conversation requires human attentionβ€”whether due to customer request, issue complexity, or emotional escalationβ€”the bot can transfer the conversation to a human attendant using the `TRANSFER TO HUMAN` keyword. + +The system sets `needs_human = true` in the session context, which routes all subsequent messages from that customer to human attendants instead of the bot. + +## How It Works + +``` +Customer Message β†’ Check needs_human + ↓ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + ↓ ↓ + needs_human=false needs_human=true + ↓ ↓ + Bot Processing Human Attendant + ↓ ↓ + TRANSFER TO HUMAN? Respond via + ↓ Console/WhatsApp + Set needs_human=true ↓ + ↓ /resolve command + Notify Attendants ↓ + needs_human=false + ↓ + Back to Bot +``` + +## Configuration + +### Enable CRM Features + +Add the following to your bot's `config.csv`: + +```csv +name,value + +# Required: Enable CRM/Transfer functionality +crm-enabled,true + +# Optional: Enable LLM-assisted attendant features +attendant-llm-tips,true +attendant-polish-message,true +attendant-smart-replies,true +attendant-auto-summary,true +attendant-sentiment-analysis,true +``` + +The `crm-enabled` setting activates: +- Transfer to human functionality +- Attendant queue management +- WebSocket notifications +- LLM assist features (if configured) + +### Configure Attendants + +Create `attendant.csv` in your bot's `.gbai` folder: + +```csv +id,name,channel,preferences,department,aliases +att-001,John Smith,all,sales,commercial,john;johnny;js +att-002,Jane Doe,web,support,customer-service,jane +att-003,Bob Wilson,whatsapp,technical,engineering,bob;bobby +att-004,Maria Santos,all,collections,finance,maria +``` + +| Column | Description | +|--------|-------------| +| `id` | Unique identifier for the attendant | +| `name` | Display name shown to customers | +| `channel` | Channel they handle: `all`, `web`, `whatsapp`, `teams`, etc. | +| `preferences` | Type of work they prefer | +| `department` | Department for routing | +| `aliases` | Semicolon-separated nicknames for name matching | + +--- + +## The `needs_human` Flag + +When `TRANSFER TO HUMAN` is called, the system sets `needs_human = true` in the session's context data. This flag controls message routing: + +| `needs_human` Value | Behavior | +|---------------------|----------| +| `false` (default) | Messages go to bot for processing | +| `true` | Messages go to human attendant | + +### Checking the Flag in BASIC + +```basic +' Check if conversation needs human +IF session.needs_human THEN + TALK "You're connected to our support team." +ELSE + TALK "I'm your AI assistant. How can I help?" +END IF +``` + +### Manual Flag Control (Advanced) + +```basic +' Force transfer without using keyword +SET SESSION "needs_human", true +SET SESSION "transfer_reason", "Customer requested human" + +' Return to bot mode (usually done by attendant via /resolve) +SET SESSION "needs_human", false +``` + +--- + +## Basic Usage + +### Transfer to Any Available Attendant + +```basic +' Simple transfer to next available human +TRANSFER TO HUMAN + +TALK result.message +``` + +### Transfer to Specific Person + +```basic +' Transfer to a specific attendant by name +TRANSFER TO HUMAN "John Smith" + +' Also works with aliases +TRANSFER TO HUMAN "johnny" + +' Or by ID +TRANSFER TO HUMAN "att-001" +``` + +### Transfer to Department + +```basic +' Transfer to sales department +TRANSFER TO HUMAN "sales" + +' Transfer with priority +result = TRANSFER TO HUMAN "support", "high" + +IF result.success THEN + TALK "You are now connected to " + result.assigned_to_name +ELSE + TALK result.message +END IF +``` + +### Transfer with Context + +```basic +' Transfer with department, priority, and context +TRANSFER TO HUMAN "technical", "urgent", "Customer needs help with API integration" +``` + +--- + +## Advanced Usage + +### Extended Transfer with Named Parameters + +```basic +' Using transfer_to_human_ex for full control +params = #{ + name: "John", + department: "support", + priority: "high", + reason: "Complex billing issue", + context: "Customer has been a member since 2020, premium tier" +} + +result = transfer_to_human_ex(params) + +IF result.success THEN + TALK "Transferring you to " + result.assigned_to_name + TALK "Estimated wait time: " + result.estimated_wait_seconds + " seconds" +ELSE + TALK "Sorry, " + result.message +END IF +``` + +### Conditional Transfer + +```basic +' Transfer based on conversation context +sentiment = ANALYZE SENTIMENT conversation + +IF sentiment.score < -0.5 THEN + ' Frustrated customer - high priority + TRANSFER TO HUMAN "support", "urgent", "Customer appears frustrated" +ELSE IF topic = "billing" THEN + TRANSFER TO HUMAN "billing" +ELSE IF topic = "technical" THEN + TRANSFER TO HUMAN "technical" +ELSE + TRANSFER TO HUMAN +END IF +``` + +### Check Availability Before Transfer + +```basic +' Check if any attendants are available +attendants = GET "/api/attendance/attendants" + +available = 0 +FOR EACH att IN attendants + IF att.status = "online" THEN + available = available + 1 + END IF +NEXT + +IF available > 0 THEN + TRANSFER TO HUMAN +ELSE + TALK "Our team is currently unavailable. Would you like to:" + TALK "1. Leave a message" + TALK "2. Schedule a callback" + TALK "3. Continue with our AI assistant" + HEAR choice +END IF +``` + +--- + +## Transfer Result + +The `TRANSFER TO HUMAN` keyword returns a result object: + +| Property | Type | Description | +|----------|------|-------------| +| `success` | Boolean | Whether the transfer was successful | +| `status` | String | Status: `queued`, `assigned`, `connected`, `no_attendants`, `crm_disabled`, `attendant_not_found`, `error` | +| `queue_position` | Integer | Position in queue (if queued) | +| `assigned_to` | String | Attendant ID (if assigned) | +| `assigned_to_name` | String | Attendant name (if assigned) | +| `estimated_wait_seconds` | Integer | Estimated wait time | +| `message` | String | Human-readable message | + +### Handling Different Statuses + +```basic +result = TRANSFER TO HUMAN "sales" + +SELECT CASE result.status + CASE "assigned" + TALK "Great news! " + result.assigned_to_name + " will be with you shortly." + + CASE "queued" + TALK "You are #" + result.queue_position + " in line." + TALK "Estimated wait: " + (result.estimated_wait_seconds / 60) + " minutes." + + CASE "connected" + TALK "You are now connected with " + result.assigned_to_name + + CASE "no_attendants" + TALK "No attendants are currently available." + TALK "Would you like to leave a message?" + + CASE "attendant_not_found" + TALK "That person is not available. Let me find someone else." + TRANSFER TO HUMAN + + CASE "crm_disabled" + TALK "I'm sorry, human support is not configured for this bot." + + CASE ELSE + TALK "Something went wrong. Please try again." +END SELECT +``` + +--- + +## LLM Tool Integration + +The `TRANSFER TO HUMAN` keyword is automatically registered as an LLM tool, allowing the AI to decide when to transfer: + +### Tool Schema + +```json +{ + "name": "transfer_to_human", + "description": "Transfer the conversation to a human attendant. Use when the customer explicitly asks to speak with a person, when the issue is too complex, or when emotional support is needed.", + "parameters": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "If someone wants to talk to somebody specific, provide their name or alias" + }, + "department": { + "type": "string", + "description": "Department to transfer to: sales, support, technical, billing, etc." + }, + "priority": { + "type": "string", + "enum": ["normal", "high", "urgent"], + "default": "normal" + }, + "reason": { + "type": "string", + "description": "Brief reason for the transfer" + } + } + } +} +``` + +### AI-Initiated Transfer Example + +When a customer says "I want to talk to a real person," the LLM can automatically invoke: + +```json +{ + "tool": "transfer_to_human", + "arguments": { + "reason": "Customer requested human assistance" + } +} +``` + +--- + +## Priority Levels + +| Priority | Value | Use Case | +|----------|-------|----------| +| `low` | 0 | Non-urgent inquiries | +| `normal` | 1 | Standard requests (default) | +| `high` | 2 | Important customers, time-sensitive issues | +| `urgent` | 3 | Escalations, complaints, VIP customers | + +Higher priority conversations are served first in the queue. + +--- + +## Attendant Status + +Attendants can have the following statuses: + +| Status | Description | +|--------|-------------| +| `online` | Available and ready for conversations | +| `busy` | Currently handling conversations | +| `away` | Temporarily unavailable | +| `offline` | Not working | + +Only `online` attendants receive new conversation assignments. + +--- + +## Queue Status + +Conversations in the queue have these statuses: + +| Status | Description | +|--------|-------------| +| `waiting` | Waiting for an attendant | +| `assigned` | Assigned but not yet active | +| `active` | Conversation in progress | +| `resolved` | Conversation completed | +| `abandoned` | Customer left before assignment | + +--- + +## REST API Endpoints + +### Queue Management + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/api/attendance/queue` | GET | List conversations in queue | +| `/api/attendance/attendants` | GET | List all attendants | +| `/api/attendance/assign` | POST | Assign conversation to attendant | +| `/api/attendance/transfer` | POST | Transfer between attendants | +| `/api/attendance/resolve/:session_id` | POST | Mark conversation resolved | +| `/api/attendance/insights` | GET | Get queue insights | + +### Example: Manual Transfer via API + +```basic +' Transfer using direct API call +body = #{ + session_id: session.id, + from_attendant_id: "att-001", + to_attendant_id: "att-002", + reason: "Specialist needed for technical issue" +} + +result = POST "/api/attendance/transfer", body +``` + +--- + +## Attendant Console + +When CRM is enabled, the **Attendant Console** becomes available at `/suite/attendant/`. This provides a full-featured interface for human agents: + +### Features + +- **Queue Management**: View and filter waiting conversations +- **Real-time Updates**: WebSocket-powered live updates +- **AI Insights**: Sentiment analysis, intent detection, suggested replies +- **Transfer**: Transfer conversations between attendants +- **Customer Details**: View customer history and information +- **Quick Responses**: Pre-configured response templates + +### Accessing the Console + +1. Enable `crm-enabled,true` in config.csv +2. Create `attendant.csv` with your team +3. Navigate to `/suite/attendant/` or click "Attendant" in the Suite menu + +--- + +## WhatsApp Attendant Mode + +Attendants can manage conversations directly from WhatsApp using commands: + +### Queue Commands + +| Command | Description | +|---------|-------------| +| `/queue` or `/fila` | View waiting conversations | +| `/take` or `/pegar` | Take next conversation | +| `/status [online\|busy\|away\|offline]` | Set availability | +| `/transfer @name` or `/transferir` | Transfer to another attendant | +| `/resolve` or `/resolver` | Mark complete, set `needs_human=false` | + +### AI Assist Commands + +| Command | Description | +|---------|-------------| +| `/tips` or `/dicas` | Get AI tips for current conversation | +| `/polish ` or `/polir` | Polish message before sending | +| `/replies` or `/respostas` | Get 3 smart reply suggestions | +| `/summary` or `/resumo` | Get conversation summary | +| `/help` or `/ajuda` | Show all commands | + +### Example WhatsApp Session + +``` +Attendant: /queue +Bot: πŸ“‹ Queue (2 waiting) + 1. JoΓ£o Silva (whatsapp) - Status: waiting + 2. Maria Santos (web) - Status: waiting + +Attendant: /take +Bot: βœ… Conversation assigned + Customer: JoΓ£o Silva + Session: abc12345 + +[Customer message arrives] +Customer: Preciso de ajuda com meu pedido + +Attendant: /tips +Bot: πŸ’‘ Tips: + 🎯 Customer needs help with order + βœ… Ask for order number + πŸ“š Check order status in system + +Attendant: /polish oi joao, vou verificar seu pedido agora +Bot: ✨ Polished: + "OlΓ‘ JoΓ£o! Vou verificar seu pedido agora mesmo." + +Attendant: OlΓ‘ JoΓ£o! Vou verificar seu pedido agora mesmo. +[Message sent to customer] + +Attendant: /resolve +Bot: βœ… Conversation resolved + Customer returned to bot mode. +``` + +--- + +## Best Practices + +### 1. Set Clear Expectations + +```basic +result = TRANSFER TO HUMAN + +IF result.success AND result.status = "queued" THEN + TALK "You're now in line to speak with a team member." + TALK "Your position: #" + result.queue_position + TALK "While you wait, I can still help with simple questions." +END IF +``` + +### 2. Provide Context to Attendants + +```basic +' Build context from conversation +context = "Customer inquiry about: " + detected_topic + ". " +context = context + "Sentiment: " + sentiment + ". " +context = context + "Key entities: " + entities.join(", ") + +TRANSFER TO HUMAN "support", "normal", context +``` + +### 3. Handle Off-Hours + +```basic +' Check business hours +hour = HOUR(NOW()) +day = WEEKDAY(NOW()) + +IF day >= 1 AND day <= 5 AND hour >= 9 AND hour < 18 THEN + TRANSFER TO HUMAN +ELSE + TALK "Our team is available Monday-Friday, 9 AM - 6 PM." + TALK "Would you like to leave a message or schedule a callback?" +END IF +``` + +### 4. VIP Routing + +```basic +' Check if customer is VIP +customer = FIND "customers", "email='" + user.email + "'" + +IF customer.tier = "premium" OR customer.tier = "enterprise" THEN + TRANSFER TO HUMAN "vip-support", "high", "Premium customer" +ELSE + TRANSFER TO HUMAN +END IF +``` + +--- + +## Troubleshooting + +### "CRM not enabled" Error + +Add `crm-enabled,true` to your config.csv file. + +### "No attendants configured" Error + +Create `attendant.csv` in your bot's `.gbai` folder with at least one attendant. + +### Transfer Not Finding Attendant by Name + +- Check that the name or alias is spelled correctly +- Verify the attendant exists in `attendant.csv` +- Aliases are case-insensitive and separated by semicolons + +### Queue Not Updating + +- Ensure WebSocket connection is active +- Check that the attendant status is `online` +- Verify the bot has proper database permissions + +--- + +## Analytics & Insights + +The attendance system provides analytics through the API: + +### Queue Insights + +```basic +GET /api/attendance/insights/{session_id} + +Response: +{ + "session_id": "uuid", + "sentiment": "neutral", + "message_count": 15, + "suggested_reply": "How can I help?", + "key_topics": ["billing", "refund"], + "priority": "normal", + "language": "pt" +} +``` + +### LLM-Powered Analytics + +When `attendant-sentiment-analysis` is enabled: + +```basic +POST /api/attendance/llm/sentiment + +Response: +{ + "overall": "negative", + "score": -0.6, + "emotions": [{"name": "frustration", "intensity": 0.8}], + "escalation_risk": "high", + "urgency": "high", + "emoji": "😟" +} +``` + +--- + +## Troubleshooting + +### Customer Stuck in Human Mode + +If a customer is stuck with `needs_human=true` after the issue is resolved: + +1. Attendant uses `/resolve` command +2. Or manually via API: +```basic +POST /api/attendance/resolve/{session_id} +``` + +### Messages Not Reaching Attendant + +1. Check `crm-enabled,true` in config.csv +2. Verify attendant.csv exists with valid entries +3. Ensure attendant status is `online` +4. Check WebSocket connection in browser console + +### Attendant Commands Not Working on WhatsApp + +1. Verify phone number is in attendant.csv +2. Phone must match exactly (with country code) +3. Check that bot is receiving webhooks + +--- + +## See Also + +- [LLM-Assisted Attendant](./attendant-llm-assist.md) - AI copilot features +- [Attendance Queue Module](../appendix-external-services/attendance-queue.md) - Full queue configuration +- [Human Approval](../chapter-06-gbdialog/keyword-human-approval.md) - Approval workflows +- [CRM Automations](../appendix-external-services/attendance-queue.md#crm-automations) - Sales, collections, scheduling +- [WhatsApp Setup](../chapter-04-gbui/how-to/connect-whatsapp.md) - Channel configuration \ No newline at end of file diff --git a/src/executive-vision.md b/src/executive-vision.md index 12a9b252..c8f14860 100644 --- a/src/executive-vision.md +++ b/src/executive-vision.md @@ -4,11 +4,28 @@ General Bots 6.1 delivers enterprise-grade AI capabilities with full data sovereignty. Own your infrastructure, control your data, deploy anywhere. +--- + +## INVESTOR HIGHLIGHTS + +| **Differentiator** | **What Sets Us Apart** | +|-------------------|------------------------| +| **LLM Orchestrator** | Single PROMPT.md per project defines bot personality across all channels and features | +| **Hybrid AI+Human** | Seamless bot-to-human handoff with AI-assisted attendants | +| **True Omnichannel** | WhatsApp, Teams, Instagram, Telegram, Web - ONE codebase, ONE personality | +| **No Vendor Lock-in** | Self-hosted, export anytime, migrate freely | +| **Industry-Standard CRM** | Built-in collections, scheduling, follow-ups, sales automation | + +--- + ## FEATURE OVERVIEW | **CAPABILITY** | **WHAT IT DOES** | **BUSINESS IMPACT** | **TIME TO VALUE** | |----------------|------------------|---------------------|-------------------| -| **AI-POWERED CONVERSATIONS** | Multi-channel bot orchestration with LLM integration (GPT-4, Claude, Llama, DeepSeek) | Significant reduction in customer service costs | < 1 hour | +| **AI-POWERED CONVERSATIONS** | Multi-channel bot orchestration with any LLM (OpenAI, Anthropic, Groq, local models) | Significant reduction in customer service costs | < 1 hour | +| **LLM-ASSISTED ATTENDANTS** | Real-time tips, smart replies, message polish, sentiment analysis for human agents | 50% faster response times | Immediate | +| **TRANSFER TO HUMAN** | Seamless bot-to-human handoff with full context | Hybrid support workflows | 5 minutes | +| **WHATSAPP ATTENDANT** | Human agents respond via WhatsApp with /commands | Mobile workforce support | Immediate | | **KNOWLEDGE BASES** | Vector-indexed document collections with semantic search (Qdrant/FAISS) | Faster information retrieval | 15 minutes | | **EMAIL AUTOMATION** | Full IMAP/SMTP integration with intelligent routing | Automated inbox management | 5 minutes | | **LLM-ASSISTED BASIC** | Plain English programming with LLM code generation | No programming skills needed | Immediate | @@ -31,6 +48,32 @@ General Bots 6.1 delivers enterprise-grade AI capabilities with full data sovere | **API GATEWAY** | REST, GraphQL, Webhooks, WebSocket support | Integration ready | Ready | | **USER DIRECTORY** | LDAP/AD replacement, SSO, group management | Central authentication | 15 minutes | | **VOICE PROCESSING** | Speech-to-text, text-to-speech, voice commands | Voice interfaces | 5 minutes | +| **CRM AUTOMATIONS** | Follow-ups, collections, scheduling, sales pipelines | Revenue operations | 10 minutes | + +--- + +## LLM-ASSISTED ATTENDANT FEATURES + +When conversations transfer from bot to human, the LLM continues working as a copilot: + +| **Feature** | **Description** | **Investor Appeal** | +|-------------|-----------------|---------------------| +| **Real-time Tips** | AI analyzes customer message and provides actionable tips | "AI copilot for support" | +| **Message Polish** | One-click grammar and tone improvement | Reduces training costs | +| **Smart Replies** | 3 contextual reply suggestions | 50% faster responses | +| **Auto Summary** | Instant conversation summary on handoff | Faster transfers | +| **Sentiment Analysis** | Real-time emotional state + escalation warnings | Prevent churn | + +**WhatsApp Commands for Attendants:** +``` +/queue - View waiting customers +/take - Take next conversation +/tips - Get AI tips +/polish - Improve message +/replies - Get suggestions +/summary - Conversation summary +/resolve - Mark complete +``` ## DEPLOYMENT OPTIONS @@ -52,6 +95,18 @@ General Bots 6.1 delivers enterprise-grade AI capabilities with full data sovere - Move between hosting options freely - No vendor lock-in +--- + +## COMPETITIVE ADVANTAGE + +| **vs Competitors** | **General Bots Advantage** | +|--------------------|---------------------------| +| **Zendesk/Intercom** | Self-hosted, AI-first, no per-seat pricing | +| **Dialogflow** | Native WhatsApp, human handoff, CRM built-in | +| **Botpress** | LLM orchestration, multi-channel, enterprise features | +| **n8n/Zapier** | Conversational AI, not just workflows | +| **Custom Development** | 90% faster deployment, proven architecture | + ## TECHNICAL ARCHITECTURE | **COMPONENT** | **TECHNOLOGY** | **PERFORMANCE** | @@ -92,12 +147,38 @@ General Bots 6.1 delivers enterprise-grade AI capabilities with full data sovere ### Enterprise Edition - All Standard features plus: - Compliance monitoring (LGPD/GDPR/HIPAA) -- Attendance tracking +- Attendance tracking with LLM assist - Vector database (Qdrant) - NVIDIA GPU acceleration - Advanced monitoring - gRPC support - Multi-channel messaging (WhatsApp, Teams, Instagram) +- Human handoff with AI copilot +- CRM automations (collections, scheduling, sales) + +--- + +## QUICK START + +```csv +# config.csv - Enable all features +name,value +crm-enabled,true +attendant-llm-tips,true +attendant-polish-message,true +attendant-smart-replies,true +attendant-auto-summary,true +attendant-sentiment-analysis,true +``` + +```csv +# attendant.csv - Configure your team +id,name,channel,preferences,department,aliases +att-001,John Smith,all,sales,commercial,john;johnny +att-002,Maria Santos,whatsapp,support,customer-service,maria +``` + +**Result:** Full hybrid AI+Human support system in minutes. ### Full Edition - All features enabled