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

317
README.md
View File

@@ -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
**Repository:** https://git.sensetostyle.com/JoeBot/SupportBot.git