Sanctum Web Chat

Web Interface Bridge for AI Agent Communication

Sanctum Web Chat is a secure, API-first web chat bridge that enables web-based communication with AI agents without exposing your Sanctum server to the public internet. It provides a complete solution for integrating AI agents into web applications and websites.

🎯 What is this for?

Sanctum Web Chat serves as a bridge between web chat widgets and Broca-2 agents, providing:

Web chat widgets that can be embedded in websites
Secure API for web application integration
Real-time communication with AI agents
Admin interface for monitoring and management
Rate limiting and security to prevent abuse

🚀 Quick Installation

Prerequisites

PHP 7.4+ or Python 3.8+
SQLite support
Web server (Apache/Nginx) or PHP built-in server
Broca-2 with web chat plugin

PHP Implementation (Recommended)

# Clone and setup
git clone https://github.com/sanctumos/broca-web-client.git
cd broca-web-client

# Set permissions
chmod 755 php/db/
chmod 644 php/db/web_chat.db

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
cd php
php -S localhost:8080

Clone and setup

git clone https://github.com/sanctumos/broca-web-client.git cd broca-web-client

Set permissions

chmod 755 php/db/ chmod 644 php/db/web_chat.db

Configure environment

export WEB_CHAT_API_KEY="your-secure-api-key" export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

Start server

cd php php -S localhost:8080


### Python Flask Implementation
bash
# Setup Python environment
cd python
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
python app.py


Python Flask Implementation
# Clone and setup
git clone https://github.com/sanctumos/broca-web-client.git
cd broca-web-client

# Set permissions
chmod 755 php/db/
chmod 644 php/db/web_chat.db

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
cd php
php -S localhost:8080
Setup Python environment
cd python python -m venv venv source venv/bin/activate  # Windows: venv\Scripts\activate pip install -r requirements.txt
Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key" export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"
Start server
python app.py


### Python Flask Implementation
bash
# Setup Python environment
cd python
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
python app.py

Verify Installation

# Clone and setup
git clone https://github.com/sanctumos/broca-web-client.git
cd broca-web-client

# Set permissions
chmod 755 php/db/
chmod 644 php/db/web_chat.db

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
cd php
php -S localhost:8080

Test API endpoint

curl http://localhost:8080/api/health

Should return: {"status": "healthy", "version": "1.0.0"}


### Python Flask Implementation
bash
# Setup Python environment
cd python
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
python app.py


⚙️ Basic Configuration
Environment Variables
# Clone and setup
git clone https://github.com/sanctumos/broca-web-client.git
cd broca-web-client

# Set permissions
chmod 755 php/db/
chmod 644 php/db/web_chat.db

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
cd php
php -S localhost:8080
API Configuration
WEB_CHAT_API_KEY=your-secure-api-key WEB_CHAT_ADMIN_KEY=your-secure-admin-key WEB_CHAT_DEBUG=false
Broca-2 Integration
BROCA_ENDPOINT=http://localhost:8000 BROCA_AGENT_ID=your-agent-id BROCA_AGENT_TOKEN=your-agent-token
Rate Limiting
RATE_LIMIT_REQUESTS=100 RATE_LIMIT_WINDOW=3600


### Python Flask Implementation
bash
# Setup Python environment
cd python
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
python app.py

Database Setup

# Clone and setup
git clone https://github.com/sanctumos/broca-web-client.git
cd broca-web-client

# Set permissions
chmod 755 php/db/
chmod 644 php/db/web_chat.db

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
cd php
php -S localhost:8080

PHP: Database is auto-created

Python: Run migration

python manage.py migrate


### Python Flask Implementation
bash
# Setup Python environment
cd python
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
python app.py


🔌 Broca-2 Integration
Plugin Installation
# Clone and setup
git clone https://github.com/sanctumos/broca-web-client.git
cd broca-web-client

# Set permissions
chmod 755 php/db/
chmod 644 php/db/web_chat.db

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
cd php
php -S localhost:8080
In your Broca-2 installation
cd plugins git clone https://github.com/sanctumos/broca-web-chat-plugin.git web_chat
Enable plugin
python cli/plugins.py --enable web_chat


### Python Flask Implementation
bash
# Setup Python environment
cd python
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
python app.py

Plugin Configuration

# Clone and setup
git clone https://github.com/sanctumos/broca-web-client.git
cd broca-web-client

# Set permissions
chmod 755 php/db/
chmod 644 php/db/web_chat.db

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
cd php
php -S localhost:8080

Add to your Broca-2 .env

WEB_CHAT_ENABLED=true WEB_CHAT_API_KEY=your-secure-api-key WEB_CHAT_WEBHOOK_URL=http://localhost:8080/api/webhook


### Python Flask Implementation
bash
# Setup Python environment
cd python
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
python app.py


🛠️ API Usage
Basic Chat API
# Clone and setup
git clone https://github.com/sanctumos/broca-web-client.git
cd broca-web-client

# Set permissions
chmod 755 php/db/
chmod 644 php/db/web_chat.db

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
cd php
php -S localhost:8080
Start a chat session
curl -X POST http://localhost:8080/api/chat/start \ -H "Authorization: Bearer your-api-key" \ -H "Content-Type: application/json" \ -d '{"user_id": "user123"}'
Send a message
curl -X POST http://localhost:8080/api/chat/message \ -H "Authorization: Bearer your-api-key" \ -H "Content-Type: application/json" \ -d '{"session_id": "session123", "message": "Hello!"}'
Get responses
curl -X GET http://localhost:8080/api/chat/responses/session123 \ -H "Authorization: Bearer your-api-key"


### Python Flask Implementation
bash
# Setup Python environment
cd python
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
python app.py

Admin API

# Clone and setup
git clone https://github.com/sanctumos/broca-web-client.git
cd broca-web-client

# Set permissions
chmod 755 php/db/
chmod 644 php/db/web_chat.db

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
cd php
php -S localhost:8080

Get session statistics

curl -X GET http://localhost:8080/api/admin/stats \ -H "Authorization: Bearer your-admin-key"

List active sessions

curl -X GET http://localhost:8080/api/admin/sessions \ -H "Authorization: Bearer your-admin-key"


### Python Flask Implementation
bash
# Setup Python environment
cd python
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure environment
export WEB_CHAT_API_KEY="your-secure-api-key"
export WEB_CHAT_ADMIN_KEY="your-secure-admin-key"

# Start server
python app.py


📚 Documentation Links
Core Documentation
Installation Instructions - Detailed installation from the repository
Configuration Reference - Complete configuration options
API Documentation - Complete API reference
Security Guide - Security best practices
Integration
Web Widget Integration - Embedding chat widgets
Broca-2 Integration - Plugin setup and configuration
Custom UI Development - Building custom interfaces
Troubleshooting - Common issues and solutions
Development
Plugin Development - Creating custom plugins
API Development - Extending the API
UI Customization - Customizing the interface
🔧 Common Tasks
Embedding a Chat Widget
Include the widget script in your HTML
Configure the API endpoint
Set up authentication
Customize the UI as needed
Setting Up a New Agent
Configure Broca-2 with web chat plugin
Set up environment variables
Test the connection
Deploy to production
Monitoring Usage

Admin Interface: Access at /admin with admin key
API Statistics: Use /api/admin/stats endpoint
Session Management: Use /api/admin/sessions` endpoint
Logs: Check server logs for debugging

🆘 Getting Help

GitHub Issues: Report bugs and request features
Documentation: Complete Web Chat documentation
Community: Join our Discord

📄 License

Code: AGPLv3 - GNU Affero General Public License v3.0
Documentation: CC-BY-SA 4.0 - Creative Commons Attribution-ShareAlike 4.0

Sanctum Web Chat - Secure web interface for AI agent communication.