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

cd /Users/claw/.openclaw/workspace/chatwoot-agent-bot
cp .env.example .env
nano .env  # or your preferred editor

Fill in:

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

# 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

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

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

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

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