SupportBot/README.md

Chatwoot Agent Bot for HOA Ledger IQ

Automated first-line support bot that triages customer conversations and escalates to Chris when needed.

🚀 Quick Start

Already configured? Jump to Production Deployment

What This Bot Does

1. Greets customers automatically when they start a conversation
2. Detects intent (billing, technical issues, feature questions, account help)
3. Searches FAQ knowledge base for answers
4. Escalates to Chris when it can't help, with optional Telegram notifications
5. Grows smarter as you add more FAQ entries over time

---

🏗️ Production Deployment

Follow these steps to deploy the bot to your production server.

Prerequisites

• Node.js installed on server (v14+)
• SSH access to production server
• Chatwoot instance running
• PM2 for process management (installed during deployment)

Step-by-Step Deployment

1. SSH into Your Production Server

ssh your-username@your-server-ip
# Example: ssh root@192.168.1.100
# Or: ssh ubuntu@support.hoaledgeriq.com

2. Clone the Repository

# Navigate to where you want the bot (e.g., /opt or ~/apps)
cd /opt

# Clone the repo
git clone https://git.sensetostyle.com/JoeBot/SupportBot.git
cd SupportBot

3. Install Dependencies

# Install Node.js dependencies
npm install --production

4. Configure Chatwoot Bot (If Not Already Done)

In your Chatwoot instance:

1. Go to Settings → Bots
2. Click Add Bot
3. Fill in:
   • Name: HOA Ledger IQ Bot
   • Avatar: (optional - upload logo)
   • Webhook URL: Leave blank for now (we'll add it after deployment)
4. Click Create
5. Copy the Bot Token shown

Connect bot to your inbox:

1. Go to Settings → Inboxes
2. Click your website widget inbox
3. Find Bot Configuration or Agent Bots
4. Select HOA Ledger IQ Bot from dropdown
5. Click Save

Get your Chatwoot API token:

1. Click your profile avatar (top right)
2. Go to Profile Settings
3. Scroll to API Token section
4. Click Generate Token (or copy existing)
5. Copy the API token

5. Create the .env Configuration File

# Create .env file
nano .env

Paste this content (update with YOUR values):

# Chatwoot Configuration
CHATWOOT_URL=https://chat.hoaledgeriq.com
CHATWOOT_API_TOKEN=your_api_token_here
CHATWOOT_ACCOUNT_ID=1
BOT_WEBHOOK_TOKEN=your_bot_token_here

# Telegram Notifications (optional - leave empty for now)
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

# Server port
PORT=3001

Save: Ctrl+O, then Enter, then exit with Ctrl+X

6. Install PM2 (Process Manager)

PM2 keeps your bot running 24/7 and restarts it if it crashes.

# Install PM2 globally
npm install -g pm2

# Start the bot with PM2
pm2 start index.js --name chatwoot-bot

# Make it start on server reboot
pm2 save
pm2 startup

The pm2 startup command will show you a sudo command - copy and paste that command to complete the setup.

7. Set Up Reverse Proxy (Nginx)

Your bot is running on port 3001, but needs to be publicly accessible.

Install nginx:

sudo apt update && sudo apt install nginx -y

Create nginx config:

sudo nano /etc/nginx/sites-available/chatwoot-bot

Paste this (replace your-domain.com with your actual domain):

server {
    listen 80;
    server_name your-domain.com;

    location /webhook {
        proxy_pass http://localhost:3001/webhook;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/chatwoot-bot /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

8. Update Chatwoot Webhook URL

Now that your bot is publicly accessible:

1. Go to Settings → Bots in Chatwoot
2. Click on HOA Ledger IQ Bot
3. Update Webhook URL to:

   https://your-domain.com/webhook
   

4. Click Save

9. Test It!

1. Go to your website widget
2. Start a new conversation
3. Say "Hello" or "I need help with billing"
4. The bot should respond!

---

🔧 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)

Knowledge Base

• Located at: ../FAQ-KB.md (in the main workspace)
• Bot searches this doc for answers
• Organized by categories: Getting Started, Billing, Features, Technical, Account, 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

---

📝 Useful PM2 Commands

# Check bot status
pm2 status

# View logs
pm2 logs chatwoot-bot

# Restart the bot
pm2 restart chatwoot-bot

# Stop the bot
pm2 stop chatwoot-bot

# View memory/CPU usage
pm2 monit

---

🐛 Troubleshooting

Bot not responding?

• Check logs: pm2 logs chatwoot-bot
• Verify webhook URL is publicly accessible
• Check firewall allows port 80/443
• Test health endpoint: curl https://your-domain.com/webhook

Can't connect to Chatwoot?

• Verify CHATWOOT_URL in .env is correct
• Check API token is valid
• Ensure server can reach your Chatwoot instance (no firewall blocking)

Escalations not working?

• Verify API token has correct permissions
• Check account ID is correct
• Review Chatwoot conversation status flow

Need to update code?

cd /opt/SupportBot
git pull
pm2 restart chatwoot-bot

---

📈 Next Steps / Enhancements

• Add Telegram notifications for escalation alerts
• 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

---

Maintained by: Forge (Chris's SaaS Operations Bot)
Version: 1.0.0
Last Updated: 2026-04-01
Repository: https://git.sensetostyle.com/JoeBot/SupportBot.git