HOALedgerIQ_Website/CHATWOOT-SETUP.md

# 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!