Support documentation and system guides
Conveaux is a multi-tenant AI chatbot platform that enables businesses to deploy customizable chatbots on their websites. The system provides a comprehensive suite of tools for managing chatbot behavior, integrations, and analytics.
Services:
- nginx:80,443 # Web server & SSL termination
- app:3000 # Node.js application
- mariadb:3306 # Database
- redis:6379 # Cache & sessions
- qdrant:6333 # Vector database
- minio:9000 # Object storage
- n8n:5678 # Workflow automation/srv/chatbot/
├── app/
│ ├── server.js # Main application
│ ├── n8n-service.js # N8N integration
│ ├── rate-limit-middleware.js
│ ├── public/
│ │ ├── admin-dashboard.html
│ │ ├── tenants.html
│ │ ├── template-admin.html
│ │ ├── admin-sidebar-universal.js
│ │ └── portal/
│ │ ├── widget.js # Chatbot widget
│ │ ├── dashboard.html # Customer portal
│ │ └── integrations.html
│ └── package.json
├── docker-compose.yml
└── nginx/
└── nginx.confThe embeddable chatbot widget that appears on client websites.
<script src="https://conveaux.io/widget.js"
data-tenant-id="2"
data-api-key="pk_xxxxx">
</script>Controls chatbot behavior and appearance per tenant.
Automated integrations triggered by chat events.
tenant_workflows:
- tenant_id
- workflow_type (slack/email/sheets/webhook)
- n8n_workflow_id
- webhook_url
- workflow_status (active/inactive)
- config (JSON)The chatbot widget is a JavaScript component that can be embedded on any website to provide AI-powered customer support.
<script src="https://conveaux.io/widget.js"
data-tenant-id="YOUR_TENANT_ID"
data-api-key="YOUR_PUBLIC_KEY">
</script><script src="https://conveaux.io/embed.js"
data-tenant-id="YOUR_TENANT_ID"
data-api-key="YOUR_PUBLIC_KEY">
</script>All customization is done through the Template Management page:
Quick action buttons that appear in the chat interface. Users can click these to send pre-defined messages.
Example hot links:
- "What services do you offer?"
- "What are your hours?"
- "How can I contact you?"Automatically open the chat widget after a specified delay (e.g., 3 seconds).
Templates control how the chatbot behaves and appears for each tenant. Every tenant has one template that defines their chatbot's personality, appearance, and behavior.
The most important part of the template. This instructs the AI on how to respond.
You are a friendly, conversational virtual assistant.
TONE & STYLE:
- Conversational and warm
- Use emojis naturally: 📌 👥 ⚙️ 💻
- Keep responses concise and scannable
- Break up text with line breaks
FORMATTING RULES:
- Start with friendly greeting
- Use emoji bullets instead of plain bullets
- Keep paragraphs short (1-2 sentences)
- End with clear next step
EXAMPLE RESPONSE:
"Hey there 👋
Of course — happy to help with that.
📌 Main point here
👥 Another key point
⚙️ Final point
What would you like to know more about?"The first message users see when opening the chat.
Example: "Welcome to SudoTechnical! How can I help you today?"Appears in the widget header.
Example: "SudoTechnical Support"Array of quick action buttons:
[
"What services do you offer?",
"What are your hours?",
"How can I contact you?",
"Tell me about your business"
]PUT /api/template?pk=PUBLIC_KEY
Content-Type: application/json
{
"system_prompt": "...",
"welcome_message": "...",
"chat_title": "...",
"color_scheme": {
"primaryColor": "#4f46e5",
"botMessageColor": "#f3f4f6",
"userMessageColor": "#4f46e5"
},
"hot_links": [...],
"auto_open_enabled": true,
"auto_open_delay": 3000
}templates table:
- id
- tenant_id (FK)
- system_prompt (TEXT)
- welcome_message (VARCHAR)
- chat_title (VARCHAR)
- color_scheme (JSON)
- hot_links (JSON)
- auto_open_enabled (BOOLEAN)
- auto_open_delay (INT)
- created_at
- updated_atN8N workflows enable automated integrations that trigger when chat events occur. Each tenant can have multiple workflows for different integration types.
Send chat messages to a Slack channel.
🤖 New Chat Message
Tenant: SudoTechnical Consulting
User: How can I get started?
Bot: I'd be happy to help you get started...
Time: 2025-01-07 10:30 AMSend email notifications for chat messages.
Log all conversations to a Google Sheet.
POST chat data to any HTTP endpoint.
tenant_workflows table:
- id
- tenant_id (FK)
- workflow_type (slack/email/sheets/webhook)
- n8n_workflow_id (VARCHAR)
- webhook_url (VARCHAR)
- workflow_status (active/inactive)
- config (JSON)
- created_at
- updated_atGoogle Sheets integration allows you to automatically log chat conversations to a Google Spreadsheet. This requires authentication with your Google account.
Best for automated, server-to-server access. No user interaction needed after setup.
Uses your personal Google account. Requires periodic re-authentication.
"client_email" fieldconveaux-sheets-logger@project-id.iam.gserviceaccount.com)Once implemented, you'll be able to:
http://localhost:5678 (via SSH tunnel)Timestamp | Tenant | User Message | Bot Reply | Session ID | RAG Used2025-01-07 10:30:45 | SudoTechnical | What are your hours? | We're open Mon-Fri 9am-5pm | sess_123 | YesIf Google Sheets authentication is too complex, consider using:
Planned features for easier setup:
The integrations page allows tenants to configure their workflow integrations. It automatically detects the logged-in tenant and shows their available integrations.
Customers access integrations through their portal:
The page automatically detects the tenant by:
?tenant=XcurrentTenantId/api/customer/tenantGET /api/tenants/:id/workflows
POST /api/tenants/:id/workflows/:type/activate
PUT /api/tenants/:id/workflows/:type/configRAG (Retrieval-Augmented Generation) allows tenants to upload documents that enhance the AI's knowledge. The system processes documents, creates embeddings, and stores them in Qdrant vector database.
POST /api/tenants/:id/knowledge/upload
GET /api/tenants/:id/knowledge/files
DELETE /api/tenants/:id/knowledge/files/:fileId
POST /api/tenants/:id/knowledge/initTenants are independent clients using the Conveaux platform. Each tenant has isolated data, configurations, and customizations.
Each tenant has:
tenants table:
- id (PK)
- name (VARCHAR)
- email (VARCHAR)
- public_key (VARCHAR, unique)
- created_at
- updated_atFull system access. Can manage all tenants, users, and system settings.
Tenant-specific access. Can only manage their own tenant's settings.
admin_users table:
- id (PK)
- username (VARCHAR, unique)
- password_hash (VARCHAR)
- email (VARCHAR)
- is_active (BOOLEAN)
- created_at
- updated_at
- last_login
customers table:
- id (PK)
- tenant_id (FK)
- email (VARCHAR, unique)
- password_hash (VARCHAR)
- name (VARCHAR)
- created_at
- updated_atThe System Monitor page provides real-time health checks and metrics for all system components.
The monitor page auto-refreshes every 30 seconds to show current status.
GET /api/admin/system/docker-status
GET /api/admin/system/app-logs
GET /api/admin/system/n8n-status
GET /api/admin/system/db-stats
GET /api/admin/system/resourcesPOST /api/login
Content-Type: application/json
{
"username": "admin",
"password": "password"
}
Response: { "ok": true, "user": {...} }POST /api/customer/login
Content-Type: application/json
{
"email": "user@example.com",
"password": "password"
}
Response: { "success": true, "token": "jwt_token" }GET /api/tenants # List all tenants
GET /api/tenants/:id # Get tenant details
POST /api/tenants # Create tenant
PUT /api/tenants/:id # Update tenant
DELETE /api/tenants/:id # Delete tenantGET /api/template?pk=PUBLIC_KEY # Get template
PUT /api/template?pk=PUBLIC_KEY # Update template
Body:
{
"system_prompt": "...",
"welcome_message": "...",
"chat_title": "...",
"color_scheme": {...},
"hot_links": [...],
"auto_open_enabled": true,
"auto_open_delay": 3000
}GET /api/tenants/:id/workflows
POST /api/tenants/:id/workflows/:type/activate
PUT /api/tenants/:id/workflows/:type/config
Activate body:
{
"config": {
"webhook_url": "https://hooks.slack.com/..."
}
}POST /api/tenants/:id/knowledge/upload
GET /api/tenants/:id/knowledge/files
DELETE /api/tenants/:id/knowledge/files/:fileId
POST /api/tenants/:id/knowledge/initPOST /api/chat
Content-Type: application/json
{
"message": "User message",
"tenantId": 2,
"sessionId": "optional_session_id"
}
Response:
{
"reply": "AI response",
"sessionId": "session_id"
}CREATE TABLE tenants (
id INT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(255) NOT NULL,
email VARCHAR(255),
public_key VARCHAR(50) UNIQUE NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);CREATE TABLE templates (
id INT PRIMARY KEY AUTO_INCREMENT,
tenant_id INT NOT NULL,
system_prompt TEXT,
welcome_message VARCHAR(500),
chat_title VARCHAR(100),
color_scheme JSON,
hot_links JSON,
auto_open_enabled BOOLEAN DEFAULT FALSE,
auto_open_delay INT DEFAULT 3000,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);CREATE TABLE tenant_workflows (
id INT PRIMARY KEY AUTO_INCREMENT,
tenant_id INT NOT NULL,
workflow_type VARCHAR(50) NOT NULL,
n8n_workflow_id VARCHAR(100),
webhook_url VARCHAR(500),
workflow_status VARCHAR(20) DEFAULT 'inactive',
config JSON,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);CREATE TABLE admin_users (
id INT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(100) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
email VARCHAR(255),
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
last_login TIMESTAMP NULL
);CREATE TABLE customers (
id INT PRIMARY KEY AUTO_INCREMENT,
tenant_id INT NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
name VARCHAR(255),
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);Host: mariadb (Docker network)
Port: 3306
Database: chatbot
User: root
Password: [stored in docker-compose.yml]/srv/chatbot/ # Main application directory
├── app/ # Node.js application
│ ├── server.js
│ ├── public/ # Static files
│ └── node_modules/
├── docker-compose.yml # Container orchestration
├── nginx/ # Nginx configuration
└── data/ # Persistent data volumes
/var/www/public/ # Nginx web root
├── static/ # Admin pages
└── portal/ # Customer portal# Edit files in /srv/chatbot/app/
# Then copy to web root
sudo cp /srv/chatbot/app/public/*.html /var/www/public/static/# Restart Node.js app
sudo docker restart app
# Restart all services
cd /srv/chatbot
sudo docker-compose restart
# Rebuild and restart
sudo docker-compose up -d --build# Application logs
sudo docker logs app -f
# All service logs
sudo docker-compose logs -f
# Specific service
sudo docker logs mariadb -fStored in docker-compose.yml:
# Certbot auto-renews via cron
# Manual renewal:
sudo certbot renew
sudo docker restart nginxsudo docker exec mariadb mysqldump -u root -p chatbot > backup.sqltar -czf chatbot-backup.tar.gz /srv/chatbot/apptar -czf full-backup.tar.gz /srv/chatbot /var/www/publicThe chat logging system automatically records all conversations between users and the AI chatbot. This provides valuable insights, enables customer support, and helps monitor chatbot performance.
Customers can view their own chat logs through their portal dashboard.
TenantName_chat_logs_TIMESTAMP.csvCREATE TABLE chat_sessions (
id INT AUTO_INCREMENT PRIMARY KEY,
session_id VARCHAR(255) UNIQUE NOT NULL,
tenant_id INT NOT NULL,
user_identifier VARCHAR(255),
user_agent TEXT,
ip_address VARCHAR(45),
referrer_url TEXT,
message_count INT DEFAULT 0,
total_tokens_used INT DEFAULT 0,
started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
last_activity_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);CREATE TABLE chat_messages (
id INT AUTO_INCREMENT PRIMARY KEY,
session_id VARCHAR(255) NOT NULL,
tenant_id INT NOT NULL,
role VARCHAR(20) NOT NULL,
content TEXT NOT NULL,
metadata JSON,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);GET /api/admin/chat-logs/:tenantId/sessions
GET /api/admin/chat-logs/:tenantId/sessions/:sessionId/messages
GET /api/admin/chat-logs/:tenantId/export/csv
GET /api/admin/chat-logs/:tenantId/export/jsonsudo docker exec mariadb mariadb -u root -p chatbot -e "SELECT tenant_id, COUNT(*) FROM chat_sessions GROUP BY tenant_id;"Chat logs feed into the analytics dashboard to provide:
This guide covers how to change passwords for admin users and customer accounts.
PUT /api/admin-users/:id/password
Content-Type: application/json
{
"password": "new_password_here"
}# Generate password hash first (use bcrypt)
# Then update database:
sudo docker exec mariadb mariadb -u root -p chatbot -e "UPDATE admin_users SET password_hash='HASH_HERE' WHERE username='admin';"POST /api/admin/customers/:customerId/reset-password
Content-Type: application/json
{
"password": "new_password_here"
}Customers can reset their own passwords via:
admin_users table:
- id
- username
- password_hash (VARCHAR 255)
- email
- is_active
- last_login
- created_at
- updated_atcustomers table:
- id
- tenant_id
- email
- password_hash (VARCHAR 255)
- name
- created_at
- updated_atis_active = TRUE# Set password to "admin123" for testing
sudo docker exec mariadb mariadb -u root -p chatbot -e "UPDATE admin_users SET password_hash='admin123' WHERE username='admin';"This guide covers how to update email addresses for admin users, customers, and tenants.
PUT /api/admin-users/:id
Content-Type: application/json
{
"username": "admin",
"email": "new.email@example.com",
"is_active": true
}sudo docker exec mariadb mariadb -u root -p chatbot -e "UPDATE admin_users SET email='new@example.com' WHERE username='admin';"PUT /api/customers/:id
Content-Type: application/json
{
"email": "customer@example.com",
"name": "Customer Name"
}PUT /api/tenants/:id
Content-Type: application/json
{
"name": "Company Name",
"email": "contact@company.com"
}Email verification is not currently enforced. Users can set any email address.
Emails can be sent via N8N workflows when chat events occur. See N8N Workflows documentation.
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=noreply@conveaux.ioEmail templates can be customized per tenant for:
SELECT * FROM customers WHERE email='email@example.com';# Admin users
sudo docker exec mariadb mariadb -u root -p chatbot -e "SELECT * FROM admin_users WHERE email='email@example.com';"
# Customers
sudo docker exec mariadb mariadb -u root -p chatbot -e "SELECT * FROM customers WHERE email='email@example.com';"
# Tenants
sudo docker exec mariadb mariadb -u root -p chatbot -e "SELECT * FROM tenants WHERE email='email@example.com';"Widget doesn't show on client website
curl https://conveaux.io/widget.jsChanges don't persist after clicking Save
curl -X PUT "https://conveaux.io/api/template?pk=PUBLIC_KEY"Slack/Email/Sheets not receiving messages
sudo docker ps | grep n8n"Too many requests" error
sudo docker restart appCannot connect to database
sudo docker ps | grep mariadbsudo docker restart mariadbsudo docker logs mariadbWorkflows show as "mock_" IDs
curl http://localhost:5678/healthz# Restart single service
sudo docker restart app
sudo docker restart nginx
sudo docker restart mariadb
# Restart all services
cd /srv/chatbot
sudo docker-compose restart
# Stop and start
sudo docker-compose down
sudo docker-compose up -d# Docker logs
sudo docker logs app
sudo docker logs nginx
sudo docker logs mariadb
# System logs
/var/log/nginx/access.log
/var/log/nginx/error.log
# Application logs
sudo docker logs app --tail 100 -f# Application health
curl https://conveaux.io/healthz
# N8N health
curl http://localhost:5678/healthz
# Database health
sudo docker exec mariadb mysqladmin ping -p
# Redis health
sudo docker exec redis redis-cli ping