JoeBot/SupportBot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add complete production deployment guide with step-by-step instructions

Browse Source
This commit is contained in:
olsch01
2026-04-01 17:57:47 -04:00
parent f464f290fd
commit 5695557c36
1 changed files with 224 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

323
README.md
View File

@@ -2,86 +2,197 @@
Automated first-line support bot that triages customer conversations and escalates to Chris when needed. 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 ### What This Bot Does
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**
### 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) Follow these steps to deploy the bot to your production server.
2. Scroll to **API Token** section
3. Copy your token
### 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 ```bash
cd chatwoot-agent-bot ssh your-username@your-server-ip
cp .env.example .env # 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 CHATWOOT_ACCOUNT_ID=1
TELEGRAM_BOT_TOKEN=optional_for_notifications BOT_WEBHOOK_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=optional_for_notifications
# Telegram Notifications (optional - leave empty for now)
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=
# Server port
PORT=3001 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 ```bash
# Install dependencies (already done) # Install PM2 globally
# npm install express body-parser axios dotenv npm install -g pm2
# Start the bot # Start the bot with PM2
node index.js 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 ```bash
# Check health sudo apt update && sudo apt install nginx -y
curl http://localhost:3001/health ```
# Test webhook (simulate conversation) **Create nginx config:**
curl -X POST http://localhost:3001/webhook \
-H "Content-Type: application/json" \ ```bash
-d '{ sudo nano /etc/nginx/sites-available/chatwoot-bot
"event": "message_created", ```
"data": {
"conversation": { Paste this (replace `your-domain.com` with your actual domain):
"id": 123,
"meta": { ```nginx
"sender": { server {
"name": "Test User" listen 80;
} server_name your-domain.com;
}
}, location /webhook {
"message": { proxy_pass http://localhost:3001/webhook;
"content": "Hello, I need help with billing", proxy_http_version 1.1;
"message_type": "incoming" 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 ## 🔧 How It Works
### Conversation Flow ### Conversation Flow
@@ -100,30 +211,16 @@ curl -X POST http://localhost:3001/webhook \
When bot can't help: When bot can't help:
- Changes conversation status from `pending` to `open` - Changes conversation status from `pending` to `open`
- Assigns to human agent queue - Assigns to human agent queue
- Sends Telegram notification (if configured): - Sends Telegram notification (if configured)
```
🔔 Support Escalation
Customer: John Doe
Reason: technical_issue
Conversation: 123
Jump in: [link to conversation]
```
### Knowledge Base ### Knowledge Base
- Located at: `../FAQ-KB.md` - Located at: `../FAQ-KB.md` (in the main workspace)
- Bot searches this doc for answers - Bot searches this doc for answers
- Organized by categories: - Organized by categories: Getting Started, Billing, Features, Technical, Account, Troubleshooting
- Getting Started - **To add new entries:** Edit `FAQ-KB.md` following the template format
- Billing & Pricing
- Features & Usage
- Technical & Integration
- Account Management
- Troubleshooting
**To add new entries:** Edit `FAQ-KB.md` following the template format. ---
## 🎯 Intent Detection ## 🎯 Intent Detection
@@ -138,8 +235,59 @@ Current intents (easily expandable):
| `account` | account, login, password | Search KB or escalate | | `account` | account, login, password | Search KB or escalate |
| `unknown` | anything else | Ask clarifying questions | | `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 ## 📈 Next Steps / Enhancements
- [ ] Add Telegram notifications for escalation alerts
- [ ] Add conversation memory (context across messages) - [ ] Add conversation memory (context across messages)
- [ ] Integrate with actual FAQ database (not just markdown) - [ ] Integrate with actual FAQ database (not just markdown)
- [ ] Add confidence scoring for intent detection - [ ] Add confidence scoring for intent detection
@@ -149,32 +297,9 @@ Current intents (easily expandable):
- [ ] Rich interactive messages (buttons, cards) - [ ] Rich interactive messages (buttons, cards)
- [ ] Integration with HOA Ledger IQ API for account lookups - [ ] 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) **Maintained by:** Forge (Chris's SaaS Operations Bot)
**Version:** 1.0.0 **Version:** 1.0.0
**Last Updated:** 2026-04-01 **Last Updated:** 2026-04-01
**Repository:** https://git.sensetostyle.com/JoeBot/SupportBot.git