181 lines
4.5 KiB
Markdown
181 lines
4.5 KiB
Markdown
# 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
|