feat: Add Chatwoot Agent Bot prototype and FAQ knowledge base
- Created chatwoot-agent-bot/ with Node.js webhook server - Bot detects intent (greeting, billing, technical, features, account) - Auto-responds from FAQ knowledge base or escalates to human - FAQ-KB.md: Living knowledge base that grows with customer questions - CHATWOOT-SETUP.md: Complete deployment and configuration guide - Supports Telegram notifications on escalation - Bot runs on port 3001, ready for Chatwoot webhook integration
This commit is contained in:
196
CHATWOOT-SETUP.md
Normal file
196
CHATWOOT-SETUP.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# Chatwoot Agent Bot - Quick Start Guide
|
||||
|
||||
## ✅ What's Been Built
|
||||
|
||||
I've created a complete Chatwoot Agent Bot prototype for HOA Ledger IQ that:
|
||||
|
||||
1. **Automatically greets customers** when they start a conversation
|
||||
2. **Detects intent** (billing, technical issues, features, account questions)
|
||||
3. **Searches the FAQ/Knowledge Base** for answers
|
||||
4. **Escalates to you** when it can't help, with Telegram notifications
|
||||
5. **Grows smarter** as you add more FAQ entries
|
||||
|
||||
## 📁 Files Created
|
||||
|
||||
```
|
||||
chatwoot-agent-bot/
|
||||
├── index.js # Main bot logic
|
||||
├── package.json # Dependencies
|
||||
├── .env.example # Config template
|
||||
├── README.md # Detailed documentation
|
||||
└── ../FAQ-KB.md # Knowledge base (living document)
|
||||
```
|
||||
|
||||
## 🚀 Next Steps to Deploy
|
||||
|
||||
### Step 1: Configure Your Chatwoot Instance
|
||||
|
||||
1. **Create the Bot:**
|
||||
- Go to `Settings → Bots` in Chatwoot
|
||||
- Click "Add Bot"
|
||||
- Name: `HOA Ledger IQ Bot`
|
||||
- Webhook URL: `http://YOUR_SERVER_IP:3001/webhook` (or use ngrok for testing)
|
||||
- Save and copy the bot token
|
||||
|
||||
2. **Connect Bot to Inbox:**
|
||||
- Open the inbox you want (e.g., website widget)
|
||||
- Click "Bot Configuration"
|
||||
- Select your new bot
|
||||
- Click "Save"
|
||||
|
||||
3. **Get Your API Token:**
|
||||
- Go to Profile Settings → API Token
|
||||
- Copy the token
|
||||
|
||||
### Step 2: Configure the Bot
|
||||
|
||||
```bash
|
||||
cd /Users/claw/.openclaw/workspace/chatwoot-agent-bot
|
||||
cp .env.example .env
|
||||
nano .env # or your preferred editor
|
||||
```
|
||||
|
||||
Fill in:
|
||||
```bash
|
||||
CHATWOOT_URL=https://your-chatwoot-instance.com
|
||||
CHATWOOT_API_TOKEN=your_actual_api_token
|
||||
CHATWOOT_ACCOUNT_ID=1 # Usually 1, check your Chatwoot
|
||||
TELEGRAM_BOT_TOKEN=optional # For escalation notifications
|
||||
TELEGRAM_CHAT_ID=optional # Your Telegram chat ID
|
||||
PORT=3001
|
||||
```
|
||||
|
||||
### Step 3: Expose the Bot (Choose One)
|
||||
|
||||
**Option A: Local Testing with ngrok**
|
||||
```bash
|
||||
# Install ngrok if needed
|
||||
npm install -g ngrok
|
||||
|
||||
# Expose local server
|
||||
ngrok http 3001
|
||||
|
||||
# Use the ngrok URL as webhook: https://abc123.ngrok.io/webhook
|
||||
```
|
||||
|
||||
**Option B: Deploy to Server**
|
||||
```bash
|
||||
# Copy to your server
|
||||
scp -r chatwoot-agent-bot user@your-server:~/
|
||||
|
||||
# Install PM2 for process management
|
||||
npm install -g pm2
|
||||
|
||||
# Start with PM2
|
||||
cd chatwoot-agent-bot
|
||||
pm2 start index.js --name chatwoot-bot
|
||||
|
||||
# Make it start on boot
|
||||
pm2 save
|
||||
pm2 startup
|
||||
```
|
||||
|
||||
### Step 4: Test It!
|
||||
|
||||
1. Send a test message through your website widget
|
||||
2. Bot should respond with greeting
|
||||
3. Try "I have a billing question" - should search FAQ
|
||||
4. Try "There's a bug on the site" - should escalate
|
||||
|
||||
## 🔧 How to Use the FAQ/Knowledge Base
|
||||
|
||||
The file `FAQ-KB.md` is your living knowledge base. It starts empty but grows as customers ask questions.
|
||||
|
||||
**When you answer a customer question manually:**
|
||||
1. Open `FAQ-KB.md`
|
||||
2. Find the relevant section
|
||||
3. Add the Q&A in this format:
|
||||
|
||||
```markdown
|
||||
### How do I change my billing email?
|
||||
|
||||
**Q:** How do I update the email address for invoices?
|
||||
|
||||
**A:** Go to Account Settings → Billing → Update Email. Changes take effect immediately.
|
||||
|
||||
**Related:** [[Account Management]], [[Billing]]
|
||||
|
||||
**Added:** 2026-04-01 | **Source:** Conversation #123
|
||||
```
|
||||
|
||||
**The bot will automatically search this file** when customers ask questions!
|
||||
|
||||
## 🎯 Bot Behavior
|
||||
|
||||
| Customer Says | Bot Action |
|
||||
|--------------|------------|
|
||||
| "Hi", "Hello", "Help" | Friendly greeting, asks how to help |
|
||||
| "How much?", "Pricing", "Billing" | Searches FAQ, escalates if no answer |
|
||||
| "Bug", "Error", "Not working" | Collects info, escalates to Chris |
|
||||
| "How do I...", "Feature" | Searches FAQ for answer |
|
||||
| "Login", "Account", "Password" | Searches FAQ or escalates |
|
||||
| Anything unclear | Asks clarifying questions |
|
||||
|
||||
## 📊 Escalation Flow
|
||||
|
||||
When bot can't help:
|
||||
1. Sends message: "Let me get Chris to help with this!"
|
||||
2. Changes conversation status to `open` (assigns to you)
|
||||
3. Sends you Telegram notification (if configured)
|
||||
4. You jump in with full context
|
||||
|
||||
## 🔍 Testing the Prototype
|
||||
|
||||
The bot is currently running on your machine at `http://localhost:3001`
|
||||
|
||||
Test it:
|
||||
```bash
|
||||
# Health check
|
||||
curl http://localhost:3001/health
|
||||
|
||||
# Simulate webhook (replace with actual test)
|
||||
curl -X POST http://localhost:3001/webhook \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"event": "message_created",
|
||||
"data": {
|
||||
"conversation": {"id": 123, "meta": {"sender": {"name": "Test"}}},
|
||||
"message": {"content": "Hello", "message_type": "incoming"}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## 📈 Future Enhancements
|
||||
|
||||
Once the basic flow is working, we can add:
|
||||
|
||||
- [ ] **Account lookup** - Pull customer data from HOA Ledger IQ
|
||||
- [ ] **Conversation memory** - Remember context across messages
|
||||
- [ ] **Better intent detection** - Use embeddings/AI classification
|
||||
- [ ] **Rich messages** - Buttons, cards, interactive elements
|
||||
- [ ] **Analytics dashboard** - Response times, common issues
|
||||
- [ ] **Auto-tagging** - Tag conversations by topic automatically
|
||||
- [ ] **Multi-language** - Support for other languages
|
||||
|
||||
## 🐛 Issues?
|
||||
|
||||
Check the bot logs:
|
||||
```bash
|
||||
# View running process
|
||||
pm2 logs chatwoot-bot
|
||||
|
||||
# Or if running directly
|
||||
# Check console output where you ran `node index.js`
|
||||
```
|
||||
|
||||
Common issues:
|
||||
- **Not responding:** Check webhook URL is publicly accessible
|
||||
- **Can't send messages:** Verify API token is correct
|
||||
- **Not escalating:** Check account ID and permissions
|
||||
|
||||
---
|
||||
|
||||
**Need help?** The bot code is fully documented in `chatwoot-agent-bot/README.md`
|
||||
|
||||
**Status:** ✅ Prototype running and tested
|
||||
**Next:** Configure with your Chatwoot credentials and deploy!
|
||||
Reference in New Issue
Block a user