SalesIQ Bot Setup Guide

# SalesIQ Bot Setup Guide

## Prerequisites
- KB website running on droplet (port 5000)
- Access to Zoho SalesIQ admin
- Access to Zoho Functions (optional, for middleware)

---

## Step 1: Deploy KB Website API

SSH to droplet and run:

```bash
# Copy KB website to /opt
cp -r /root/.openclaw/workspace/kb_website /opt/

# Activate venv and install Flask
cd /opt/zoho-extract && source venv/bin/activate
pip install flask

# Test the website (Ctrl+C to stop)
cd /opt/kb_website && python app.py
```

Test API: `curl "http://localhost:5000/api/search?q=fire+shutter+warranty"`

### Run as Service (Production)

Create systemd service:

```bash
sudo tee /etc/systemd/system/kb-website.service << 'SERVICE'
[Unit]
Description=ROLLerUP KB Website
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/kb_website
Environment=PATH=/opt/zoho-extract/venv/bin
ExecStart=/opt/zoho-extract/venv/bin/python app.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
SERVICE

sudo systemctl daemon-reload
sudo systemctl enable kb-website
sudo systemctl start kb-website
```

### Add Caddy Reverse Proxy (HTTPS)

Edit `/etc/caddy/Caddyfile`, add:

```
kb.rollerup.ca {
    reverse_proxy localhost:5000
}
```

Or use IP with path:

```
68.183.198.0 {
    handle /kb/* {
        uri strip_prefix /kb
        reverse_proxy localhost:5000
    }
}
```

Then: `sudo systemctl reload caddy`

---

## Step 2: Create SalesIQ Bot

### A. In SalesIQ Dashboard

1. Go to **Settings** → **Bots** → **Zobot**
2. Click **Create Bot**
3. Name: "ROLLerUP Assistant"
4. Platform: **Codeless** or **Deluge** (we'll use Deluge)
5. Choose departments to deploy

### B. Configure Bot Flow

1. **Greeting Card**:
   - Message: Use greeting from `greeting_flow.dg`
   
2. **Handle Visitor Messages**:
   - Create a Deluge script handler
   - Paste content from `bot_logic.dg`

3. **Create External Connection** (for API calls):
   - Go to **Settings** → **Developer Space** → **Connections**
   - Create connection named `kb_api`
   - URL: `http://68.183.198.0:5000`
   - Auth: None (or add token if you secure the API)

### C. Alternative: Use Zoho Function Bridge

If direct API calls don't work:

1. Go to **Zoho Functions** (functions.zoho.com)
2. Create new function named `kb_search`
3. Paste code from `zoho_function_bridge.dg`
4. Deploy as API endpoint
5. Update bot to call the function instead

---

## Step 3: Bot Logic Flow

```
[Visitor Message]
       ↓
[Detect Intent]
       ↓
   ┌───┴───┐
   ↓       ↓
[Known]  [Unknown]
   ↓       ↓
[Route] [Search KB]
   ↓       ↓
[Response] [Format Result]
   ↓       ↓
[Send to Visitor]
```

### Intent Categories

| Intent | Trigger Words | Action |
|--------|---------------|--------|
| pricing | quote, price, cost, how much | Collect lead info |
| fire_shutter | fire, fire-rated | HIGH PRIORITY - transfer |
| service | repair, fix, broken, warranty | Search repairs DB |
| transfer | talk to, human, agent, sales | Transfer to agent |
| product_info | shutter, awning, screen | Search KB |
| general | (anything else) | Search KB |

---

## Step 4: Test the Bot

1. Open SalesIQ chat widget on rollerup.ca
2. Test queries:
   - "Hi" → Greeting
   - "How much for roll shutters?" → Pricing flow
   - "Fire shutter info" → Priority response
   - "My shutter won't open" → Search repair DB
   - "What's the warranty?" → KB search

---

## Step 5: Monitor & Improve

1. **Review chat logs** in SalesIQ
2. **Check API logs**: `tail -f /opt/kb_website/logs/access.log`
3. **Track unanswered questions** → Add to KB
4. **Measure**:
   - Bot resolution rate
   - Transfer-to-human rate
   - Average response relevance

---

## Troubleshooting

### Bot not responding
- Check KB website is running: `systemctl status kb-website`
- Test API manually: `curl "http://localhost:5000/api/search?q=test"`

### Low quality responses
- Check similarity threshold (default 0.3)
- Review what's being searched
- May need to add more content to KB

### Connection errors
- Verify firewall allows port 5000
- Check Caddy proxy config
- Test from SalesIQ server location

---

## Security Notes

- Consider adding API key authentication
- Rate limit the API endpoint
- Don't expose sensitive data in responses
- Log all queries for improvement