diff --git a/README.md b/README.md index ee63ea4..c6da3d2 100644 --- a/README.md +++ b/README.md @@ -2,86 +2,197 @@ Automated first-line support bot that triages customer conversations and escalates to Chris when needed. -## 🚀 Setup Instructions +## 🚀 Quick Start -### 1. Configure Chatwoot Bot +**Already configured?** Jump to [Production Deployment](#-production-deployment) -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** +### What This Bot Does -### 2. Connect Bot to Inbox +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 -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 +# 🏗️ Production Deployment -1. Go to your **Profile Settings** (click avatar) -2. Scroll to **API Token** section -3. Copy your token +Follow these steps to deploy the bot to your production server. -### 4. Configure the Bot +## 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 -cd chatwoot-agent-bot -cp .env.example .env +ssh your-username@your-server-ip +# Example: ssh root@192.168.1.100 +# Or: ssh ubuntu@support.hoaledgeriq.com ``` -Edit `.env` with your values: +### 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 ``` -CHATWOOT_URL=https://your-chatwoot-instance.com -CHATWOOT_API_TOKEN=your_api_token + +### 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 -TELEGRAM_BOT_TOKEN=optional_for_notifications -TELEGRAM_CHAT_ID=optional_for_notifications +BOT_WEBHOOK_TOKEN=your_bot_token_here + +# Telegram Notifications (optional - leave empty for now) +TELEGRAM_BOT_TOKEN= +TELEGRAM_CHAT_ID= + +# Server port PORT=3001 ``` -### 5. Run the Bot +**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 dependencies (already done) -# npm install express body-parser axios dotenv +# Install PM2 globally +npm install -g pm2 -# Start the bot -node index.js +# Start the bot with PM2 +pm2 start index.js --name chatwoot-bot + +# Make it start on server reboot +pm2 save +pm2 startup ``` -### 6. Test It +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 -# Check health -curl http://localhost:3001/health +sudo apt update && sudo apt install nginx -y +``` -# 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" - } +**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 @@ -100,30 +211,16 @@ curl -X POST http://localhost:3001/webhook \ 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] - ``` +- Sends Telegram notification (if configured) ### Knowledge Base -- Located at: `../FAQ-KB.md` +- Located at: `../FAQ-KB.md` (in the main workspace) - Bot searches this doc for answers -- Organized by categories: - - Getting Started - - Billing & Pricing - - Features & Usage - - Technical & Integration - - Account Management - - Troubleshooting +- Organized by categories: Getting Started, Billing, Features, Technical, Account, Troubleshooting +- **To add new entries:** Edit `FAQ-KB.md` following the template format -**To add new entries:** Edit `FAQ-KB.md` following the template format. +--- ## 🎯 Intent Detection @@ -138,8 +235,59 @@ Current intents (easily expandable): | `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 @@ -149,32 +297,9 @@ Current intents (easily expandable): - [ ] 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 +**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