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](#-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

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

### 2. Clone the Repository

```bash
# 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

```bash
# 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

```bash
# Create .env file
nano .env
```

Paste this content (update with YOUR values):

```bash
# 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.

```bash
# 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:**

```bash
sudo apt update && sudo apt install nginx -y
```

**Create nginx config:**

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

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

```nginx
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:**

```bash
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

```bash
# 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?
```bash
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