Initial commit: Chatwoot Agent Bot for HOA Ledger IQ
This commit is contained in:
180
README.md
Normal file
180
README.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# Chatwoot Agent Bot for HOA Ledger IQ
|
||||
|
||||
Automated first-line support bot that triages customer conversations and escalates to Chris when needed.
|
||||
|
||||
## 🚀 Setup Instructions
|
||||
|
||||
### 1. Configure Chatwoot Bot
|
||||
|
||||
1. Go to **Settings → Bots** in your Chatwoot account
|
||||
2. Click **Add Bot**
|
||||
3. Fill in:
|
||||
- **Name:** HOA Ledger IQ Bot
|
||||
- **Avatar:** (optional upload logo)
|
||||
- **Webhook URL:** `http://your-server-ip:3001/webhook` (or use ngrok for local testing)
|
||||
4. Save and copy the **Bot Token**
|
||||
|
||||
### 2. Connect Bot to Inbox
|
||||
|
||||
1. Go to the inbox you want to use (e.g., website widget)
|
||||
2. Click **Bot Configuration**
|
||||
3. Select the bot you just created
|
||||
4. Click **Save**
|
||||
|
||||
### 3. Get Your Chatwoot API Token
|
||||
|
||||
1. Go to your **Profile Settings** (click avatar)
|
||||
2. Scroll to **API Token** section
|
||||
3. Copy your token
|
||||
|
||||
### 4. Configure the Bot
|
||||
|
||||
```bash
|
||||
cd chatwoot-agent-bot
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edit `.env` with your values:
|
||||
```
|
||||
CHATWOOT_URL=https://your-chatwoot-instance.com
|
||||
CHATWOOT_API_TOKEN=your_api_token
|
||||
CHATWOOT_ACCOUNT_ID=1
|
||||
TELEGRAM_BOT_TOKEN=optional_for_notifications
|
||||
TELEGRAM_CHAT_ID=optional_for_notifications
|
||||
PORT=3001
|
||||
```
|
||||
|
||||
### 5. Run the Bot
|
||||
|
||||
```bash
|
||||
# Install dependencies (already done)
|
||||
# npm install express body-parser axios dotenv
|
||||
|
||||
# Start the bot
|
||||
node index.js
|
||||
```
|
||||
|
||||
### 6. Test It
|
||||
|
||||
```bash
|
||||
# Check health
|
||||
curl http://localhost:3001/health
|
||||
|
||||
# Test webhook (simulate conversation)
|
||||
curl -X POST http://localhost:3001/webhook \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"event": "message_created",
|
||||
"data": {
|
||||
"conversation": {
|
||||
"id": 123,
|
||||
"meta": {
|
||||
"sender": {
|
||||
"name": "Test User"
|
||||
}
|
||||
}
|
||||
},
|
||||
"message": {
|
||||
"content": "Hello, I need help with billing",
|
||||
"message_type": "incoming"
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## 🔧 How It Works
|
||||
|
||||
### Conversation Flow
|
||||
|
||||
1. **Customer sends message** → Chatwoot receives it
|
||||
2. **Chatwoot sends webhook** → Bot receives `message_created` event
|
||||
3. **Bot analyzes intent** → Detects: billing, technical, account, features, greeting
|
||||
4. **Bot responds or escalates:**
|
||||
- **Greeting:** Friendly welcome, asks how to help
|
||||
- **Known topic:** Searches FAQ-KB.md, provides answer
|
||||
- **Technical issue:** Collects info, escalates to Chris
|
||||
- **Unknown:** Asks clarifying questions or escalates
|
||||
|
||||
### Escalation to Chris
|
||||
|
||||
When bot can't help:
|
||||
- Changes conversation status from `pending` to `open`
|
||||
- Assigns to human agent queue
|
||||
- Sends Telegram notification (if configured):
|
||||
```
|
||||
🔔 Support Escalation
|
||||
|
||||
Customer: John Doe
|
||||
Reason: technical_issue
|
||||
Conversation: 123
|
||||
|
||||
Jump in: [link to conversation]
|
||||
```
|
||||
|
||||
### Knowledge Base
|
||||
|
||||
- Located at: `../FAQ-KB.md`
|
||||
- Bot searches this doc for answers
|
||||
- Organized by categories:
|
||||
- Getting Started
|
||||
- Billing & Pricing
|
||||
- Features & Usage
|
||||
- Technical & Integration
|
||||
- Account Management
|
||||
- Troubleshooting
|
||||
|
||||
**To add new entries:** Edit `FAQ-KB.md` following the template format.
|
||||
|
||||
## 🎯 Intent Detection
|
||||
|
||||
Current intents (easily expandable):
|
||||
|
||||
| Intent | Triggers | Action |
|
||||
|--------|----------|--------|
|
||||
| `greeting` | hello, hi, help | Welcome message |
|
||||
| `billing` | price, cost, payment | Search KB or escalate |
|
||||
| `technical_issue` | bug, error, broken | Collect info + escalate |
|
||||
| `feature_request` | how to, feature, can I | Search KB |
|
||||
| `account` | account, login, password | Search KB or escalate |
|
||||
| `unknown` | anything else | Ask clarifying questions |
|
||||
|
||||
## 📈 Next Steps / Enhancements
|
||||
|
||||
- [ ] Add conversation memory (context across messages)
|
||||
- [ ] Integrate with actual FAQ database (not just markdown)
|
||||
- [ ] Add confidence scoring for intent detection
|
||||
- [ ] Implement handoff back to bot (status: pending)
|
||||
- [ ] Add analytics (response times, escalation rate)
|
||||
- [ ] Multi-language support
|
||||
- [ ] Rich interactive messages (buttons, cards)
|
||||
- [ ] Integration with HOA Ledger IQ API for account lookups
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
**Bot not responding:**
|
||||
- Check webhook URL is publicly accessible (use ngrok for local dev)
|
||||
- Verify bot is connected to inbox
|
||||
- Check bot logs for errors
|
||||
|
||||
**Escalations not working:**
|
||||
- Verify API token has correct permissions
|
||||
- Check account ID is correct
|
||||
- Review Chatwoot conversation status flow
|
||||
|
||||
**Telegram notifications not sending:**
|
||||
- Ensure bot token is valid
|
||||
- Chat ID must be a number (get from @userinfobot)
|
||||
- Bot must be started in chat first
|
||||
|
||||
## 📝 Logs
|
||||
|
||||
Bot logs to console. For production, consider:
|
||||
- PM2 for process management
|
||||
- Winston/Bunyan for logging
|
||||
- Error tracking (Sentry)
|
||||
|
||||
---
|
||||
|
||||
**Maintained by:** Forge (Chris's SaaS Operations Bot)
|
||||
**Version:** 1.0.0
|
||||
**Last Updated:** 2026-04-01
|
||||
Reference in New Issue
Block a user