GeneralBots/botbook
2
2
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Add LLM-assisted attendant documentation

Browse source 
New Documentation:
- chapter-11-features/attendant-llm-assist.md - Full guide for AI copilot features
- chapter-11-features/transfer-to-human.md - Human handoff and needs_human flag

Updated Documentation:
- executive-vision.md - Added investor highlights, competitive advantages, LLM assist overview
- SUMMARY.md - Added new chapters
- appendix-external-services/README.md - Added CRM/attendant config options
- appendix-external-services/llm-providers.md - Updated model names to current/generic
- chapter-02/gbai.md - Updated model name examples

Features Documented:
- needs_human flag and how it routes messages
- WhatsApp attendant commands (/queue, /tips, /polish, etc.)
- All 5 LLM assist features with config.csv options
- Analytics and insights APIs
- Troubleshooting guide
This commit is contained in:
Rodrigo Rodriguez (Pragmatismo) 2025-12-05 13:50:28 -03:00
parent c4d209352d
commit 80f1041263
7 changed files with 1243 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
src/SUMMARY.md
View file

@ -300,6 +300,8 @@
- [Multi-Agent Orchestration](./chapter-11-features/multi-agent-orchestration.md) - [Multi-Agent Orchestration](./chapter-11-features/multi-agent-orchestration.md)
- [Memory Management](./chapter-11-features/memory-management.md) - [Memory Management](./chapter-11-features/memory-management.md)
- [Hybrid RAG Search](./chapter-11-features/hybrid-search.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 # Part XI - Security

9
src/appendix-external-services/README.md
View file

@ -54,12 +54,21 @@ llm-model,gpt-4o
weather-api-key,YOUR_OPENWEATHERMAP_KEY weather-api-key,YOUR_OPENWEATHERMAP_KEY
whatsapp-api-key,YOUR_WHATSAPP_KEY whatsapp-api-key,YOUR_WHATSAPP_KEY
whatsapp-phone-number-id,YOUR_PHONE_ID whatsapp-phone-number-id,YOUR_PHONE_ID
whatsapp-verify-token,YOUR_WEBHOOK_VERIFY_TOKEN
teams-app-id,YOUR_TEAMS_APP_ID teams-app-id,YOUR_TEAMS_APP_ID
teams-app-password,YOUR_TEAMS_PASSWORD teams-app-password,YOUR_TEAMS_PASSWORD
instagram-access-token,YOUR_INSTAGRAM_TOKEN instagram-access-token,YOUR_INSTAGRAM_TOKEN
instagram-page-id,YOUR_PAGE_ID instagram-page-id,YOUR_PAGE_ID
botmodels-enabled,true botmodels-enabled,true
botmodels-url,http://localhost:5000 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 ## Auto-Managed Services

33
src/appendix-external-services/llm-providers.md
View file

@ -47,15 +47,15 @@ Known for safety, helpfulness, and extended thinking capabilities.
| Model | Context | Best For | Speed | | Model | Context | Best For | Speed |
|-------|---------|----------|-------| |-------|---------|----------|-------|
| Claude Opus 4.5 | 200K | Most capable, complex reasoning | Slow | | Claude Opus | 200K | Most capable, complex reasoning | Slow |
| Claude Sonnet 4.5 | 200K | Best balance of capability/speed | Fast | | Claude Sonnet | 200K | Best balance of capability/speed | Fast |
**Configuration (config.csv):** **Configuration (config.csv):**
```csv ```csv
name,value name,value
llm-provider,anthropic llm-provider,anthropic
llm-model,claude-sonnet-4.5 llm-model,claude-sonnet
``` ```
**Strengths:** **Strengths:**
@ -74,16 +74,15 @@ Google's multimodal AI models with strong reasoning capabilities.
| Model | Context | Best For | Speed | | Model | Context | Best For | Speed |
|-------|---------|----------|-------| |-------|---------|----------|-------|
| Gemini 3 Pro | 2M | Complex reasoning, benchmarks | Medium | | Gemini Pro | 2M | Complex reasoning, benchmarks | Medium |
| Gemini 2.5 Pro | 2M | Extremely long documents | Medium | | Gemini Flash | 1M | Fast multimodal tasks | Fast |
| Gemini 2.5 Flash | 1M | Fast multimodal | Fast |
**Configuration (config.csv):** **Configuration (config.csv):**
```csv ```csv
name,value name,value
llm-provider,google llm-provider,google
llm-model,gemini-3-pro llm-model,gemini-pro
``` ```
**Strengths:** **Strengths:**
@ -291,9 +290,9 @@ Use different models for different tasks:
```csv ```csv
name,value name,value
llm-provider,anthropic llm-provider,anthropic
llm-model,claude-sonnet-4.5 llm-model,claude-sonnet
llm-fast-provider,groq llm-fast-provider,groq
llm-fast-model,llama-4-scout llm-fast-model,llama-3.3-70b
llm-fallback-provider,local llm-fallback-provider,local
llm-fallback-model,DeepSeek-R1-Distill-Qwen-1.5B llm-fallback-model,DeepSeek-R1-Distill-Qwen-1.5B
embedding-provider,local embedding-provider,local
@ -306,15 +305,15 @@ embedding-model,bge-small-en-v1.5
| Use Case | Recommended | Why | | Use Case | Recommended | Why |
|----------|-------------|-----| |----------|-------------|-----|
| Customer support | Claude Sonnet 4.5 | Best at following guidelines | | Customer support | Claude Sonnet | Best at following guidelines |
| Code generation | DeepSeek-R1, GPT-5 | Specialized for code | | Code generation | DeepSeek-R1, GPT-4o | Specialized for code |
| Document analysis | Gemini 3 Pro | 2M context window | | Document analysis | Gemini Pro | 2M context window |
| Real-time chat | Groq Llama 4 Scout | Fastest responses | | Real-time chat | Groq Llama 3.3 | Fastest responses |
| Privacy-sensitive | Local DeepSeek-R1 | No external data transfer | | Privacy-sensitive | Local DeepSeek-R1 | No external data transfer |
| Cost-sensitive | DeepSeek-V3.1, Local | Lowest cost per token | | Cost-sensitive | DeepSeek, Local models | Lowest cost per token |
| Complex reasoning | Claude Opus 4.5, Gemini 3 Pro | Best reasoning ability | | Complex reasoning | Claude Opus, Gemini Pro | Best reasoning ability |
| Real-time research | Grok 4 | Live data access | | Real-time research | Grok | Live data access |
| Long context (10M) | Llama 4 Scout | Largest context window | | Long context | Gemini Pro, Claude | Largest context windows |
### By Budget ### By Budget

4
src/chapter-02/gbai.md
View file

@ -82,7 +82,7 @@ Each folder becomes a searchable collection. Drop files in, bot learns automatic
Single `config.csv` file with key-value pairs: Single `config.csv` file with key-value pairs:
```csv ```csv
llm-model,gpt-3.5-turbo llm-model,your-preferred-model
temperature,0.7 temperature,0.7
max-tokens,2000 max-tokens,2000
welcome-message,Hello! How can I help? welcome-message,Hello! How can I help?
@ -147,7 +147,7 @@ TALK "Ticket #" + ticket_id + " created"
`config.csv`: `config.csv`:
```csv ```csv
llm-model,gpt-3.5-turbo llm-model,your-preferred-model
bot-name,TechSupport bot-name,TechSupport
greeting,Welcome to support! greeting,Welcome to support!
``` ```

497
src/chapter-11-features/attendant-llm-assist.md Normal file
View file

@ -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 <message>` 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

634
src/chapter-11-features/transfer-to-human.md Normal file
View file

@ -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 <msg>` 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

85
src/executive-vision.md
View file

@ -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. 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 ## FEATURE OVERVIEW
| **CAPABILITY** | **WHAT IT DOES** | **BUSINESS IMPACT** | **TIME TO VALUE** | | **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 | | **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 | | **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 | | **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 | | **API GATEWAY** | REST, GraphQL, Webhooks, WebSocket support | Integration ready | Ready |
| **USER DIRECTORY** | LDAP/AD replacement, SSO, group management | Central authentication | 15 minutes | | **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 | | **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 ## DEPLOYMENT OPTIONS
@ -52,6 +95,18 @@ General Bots 6.1 delivers enterprise-grade AI capabilities with full data sovere
- Move between hosting options freely - Move between hosting options freely
- No vendor lock-in - 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 ## TECHNICAL ARCHITECTURE
| **COMPONENT** | **TECHNOLOGY** | **PERFORMANCE** | | **COMPONENT** | **TECHNOLOGY** | **PERFORMANCE** |
@ -92,12 +147,38 @@ General Bots 6.1 delivers enterprise-grade AI capabilities with full data sovere
### Enterprise Edition ### Enterprise Edition
- All Standard features plus: - All Standard features plus:
- Compliance monitoring (LGPD/GDPR/HIPAA) - Compliance monitoring (LGPD/GDPR/HIPAA)
- Attendance tracking - Attendance tracking with LLM assist
- Vector database (Qdrant) - Vector database (Qdrant)
- NVIDIA GPU acceleration - NVIDIA GPU acceleration
- Advanced monitoring - Advanced monitoring
- gRPC support - gRPC support
- Multi-channel messaging (WhatsApp, Teams, Instagram) - 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 ### Full Edition
- All features enabled - All features enabled