# Docker Deployment Source: https://docs.chattermate.chat/deployment/docker Deploy ChatterMate with Docker in development or production, running the frontend, FastAPI backend, PostgreSQL with pgvector, and Redis through Docker Compose. # Docker Deployment ChatterMate can be deployed using Docker in both development and production environments. ## Development Setup For local development, we use `docker-compose.yml` which sets up: * Frontend (Vue.js) with hot-reloading * Backend (FastAPI) with auto-reload * PostgreSQL with pgvector extension * Redis for caching and rate limiting ### Prerequisites * Docker * Docker Compose * Git ### Quick Start 1. Clone the repository: ```bash theme={null} git clone https://github.com/chattermate/chattermate.chat cd chattermate.chat ``` 2. Create environment files: ```bash theme={null} # Frontend environment cp frontend/.env.example frontend/.env # Backend environment cp backend/.env.example backend/.env ``` 3. Start the development environment: ```bash theme={null} docker-compose up --build ``` Services will be available at: * Frontend: [http://localhost:3000](http://localhost:3000) * Backend API: [http://localhost:8000](http://localhost:8000) * Backend Docs: [http://localhost:8000/docs](http://localhost:8000/docs) * PostgreSQL: localhost:5432 * Redis: localhost:6379 ### Development Features * Hot-reloading for frontend changes * Auto-reload for backend changes * Volume mounts for live code updates * Development-mode Firebase credentials * Automatic database migrations * Health checks for all services ## Production Deployment For production deployment, we use `docker-compose.prod.yml` which provides: * Optimized multi-stage builds * Nginx for frontend serving * Gunicorn for backend serving * Production-grade configurations * Health monitoring * Automatic restarts ### Production Setup 1. Set up environment files: ```bash theme={null} # Frontend production environment cp frontend/.env.prod.example frontend/.env # Backend production environment cp backend/.env.prod.example backend/.env ``` 2. Configure Firebase (Optional): ```bash theme={null} # Place your Firebase credentials in ./config/firebase-credentials.json ``` 3. Start production services: ```bash theme={null} docker-compose -f docker-compose.prod.yml up -d ``` ### Production Features * Multi-stage builds for smaller images * Nginx configuration for frontend * Gunicorn with multiple workers * Redis persistence * Database backups * Automatic health checks * Container restart policies ## Docker Images ### Frontend Images * Development: `Dockerfile.frontend` * Node.js development server * Hot-reloading enabled * Volume mounts for live updates * Production: `Dockerfile.frontend.prod` * Multi-stage build * Nginx for static file serving * Optimized build size * Health monitoring ### Backend Images * Development: `Dockerfile` * Python development server * Auto-reload enabled * Debug mode * Production: `Dockerfile.backend.prod` * Multi-stage build * Gunicorn server * Optimized dependencies * Worker configuration ### Database Image * Custom PostgreSQL image with pgvector * Vector similarity search support * Automatic initialization * Health checks ## Environment Variables ### Frontend Variables ```env theme={null} VITE_API_URL=http://localhost:8000 VITE_WS_URL=ws://localhost:8000 ``` ### Backend Variables ```env theme={null} DATABASE_URL=postgresql://postgres:postgres@db:5432/chattermate CORS_ORIGINS=["http://localhost:3000"] FIREBASE_CREDENTIALS=/app/config/firebase-credentials.json ``` ### Production Additional Variables ```env theme={null} REDIS_ENABLED=true REDIS_URL=redis://redis:6379/0 WORKERS=4 TIMEOUT=120 LOG_LEVEL=info ``` ## Health Checks All services include health checks: * Frontend: Checks HTTP endpoint * Backend: Monitors API health * PostgreSQL: Verifies database connection * Redis: Ensures cache availability ## Volumes Persistent data is managed through Docker volumes: * `postgres_data`: Database files * `redis_data`: Cache data * `backend_data`: Uploaded files * `frontend_node_modules`: NPM packages ## Networks Services communicate through Docker networks: * Development: `app-network` * Production: `chattermate-network` ## Monitoring Monitor your deployment using Docker commands: ```bash theme={null} # View all logs docker-compose logs -f # Service-specific logs docker-compose logs -f frontend docker-compose logs -f backend docker-compose logs -f db docker-compose logs -f redis # Container health docker ps ``` ## Troubleshooting Common issues and solutions: 1. Frontend not starting: ```bash theme={null} # Check frontend logs docker-compose logs frontend # Rebuild frontend docker-compose build --no-cache frontend ``` 2. Backend migrations failing: ```bash theme={null} # Check backend logs docker-compose logs backend # Manual migration docker-compose exec backend alembic upgrade head ``` 3. Database connection issues: ```bash theme={null} # Check database logs docker-compose logs db # Verify database health docker-compose exec db pg_isready -U postgres ``` 4. Redis connection issues: ```bash theme={null} # Check Redis logs docker-compose logs redis # Verify Redis connection docker-compose exec redis redis-cli ping ``` # AI Agent Quickstart Source: https://docs.chattermate.chat/features/agents-quickstart Go from nothing to a live ChatterMate AI agent with a copy-paste CLI path built for AI agents, CI pipelines, and automation, with JSON output on every command. # AI Agent & Automation Quickstart This is the fastest, copy-paste path from **nothing** to a **live ChatterMate agent** — designed to be run by an AI agent, a CI pipeline, or anyone scripting their setup. Every command supports `--json` for machine-readable output. Use the **ChatterMate CLI** (`chattermate`) for account, agent, workflow, and knowledge setup. It is installed from the `chattermate-cli` Python package. This is **not** the self-host Docker tool (`npm install -g chattermate-deploy`) — see [Quickstart → Self-host](/quickstart#option-b-self-host-with-docker) for that. ## TL;DR ```bash theme={null} pip install chattermate-cli # Python # or: npm install -g chattermate-cli # npm wrapper (needs uv or pipx on PATH) # 1. Create an account — a one-time code is emailed to --admin-email. # Pass it with --otp (or enter at the prompt); you're logged in automatically. # Self-hosted single-org instance? Add --community to skip OTP. chattermate signup \ --name "Acme Inc" \ --domain acme.com \ --admin-email admin@acme.com \ --admin-name "Ada Admin" \ --otp 123456 # --admin-password is prompted securely (pass it explicitly for non-interactive use) # 2. Create an agent chattermate agent create \ --name "Support" \ --type customer_support \ -i "Be concise and friendly" \ -i "Escalate billing questions to a human" \ --json # 3. Feed it your knowledge (attach to the agent from step 2) chattermate knowledge add-url \ --website https://docs.acme.com \ --pdf-url https://acme.com/guide.pdf \ --agent-id # 4. (Optional) mint a long-lived token for headless / MCP use chattermate token create ci --expires-in-days 90 ``` ## Prerequisites * Install the CLI with **pip** (`pip install chattermate-cli`, or `pipx`/`uvx`) — needs Python 3.10+. Prefer **npm**? `npm install -g chattermate-cli` installs the identical CLI as a wrapper that runs the Python one via `uv`/`pipx`, so you need `uv` or `pipx` on your PATH. See the [CLI reference](/features/cli#installation) for all install options. * Nothing else — the CLI targets the hosted API (`https://api.chattermate.chat`) by default. Set `CHATTERMATE_API_URL=http://localhost:8000` to target a local/self-hosted backend. ## Step 1 — Authenticate Pick one: ```bash theme={null} chattermate signup --name "Acme Inc" --domain acme.com \ --admin-email admin@acme.com --admin-name "Ada Admin" ``` Creates an organization + admin user and logs you in. Add `--json` to capture the result. Best for AI agents and CI. Create the token once (from an interactive login), then export it: ```bash theme={null} export CHATTERMATE_TOKEN=cmat_xxxxxxxxxxxxxxxxxxxx chattermate whoami --json ``` See [CLI → Personal Access Tokens](/features/cli#personal-access-tokens). ## Step 2 — Create an agent ```bash theme={null} chattermate agent create \ --name "Support" \ --type customer_support \ -i "Answer from the knowledge base; be concise" \ --json ``` `--type` is one of `customer_support`, `sales`, `tech_support`, `general`, `custom`. The `--json` output includes the new `id` — capture it for the next steps. ## Step 3 — Add knowledge From a URL, or upload local PDF file(s): ```bash theme={null} # From a website / PDF URL chattermate knowledge add-url \ --website https://docs.acme.com \ --agent-id \ --json # From local PDF file(s) on disk chattermate knowledge add-file ./guide.pdf ./faq.pdf --agent-id --json # Track ingestion progress chattermate knowledge status ``` ## Step 4 — Go live with the widget Create a widget for the agent from the CLI — it prints the **widget id** and the embed snippet: ```bash theme={null} chattermate widget create --agent-id --name "Website widget" # already have one? list them: chattermate widget list ``` Then drop the snippet on any page: ```html theme={null} ``` For **authenticated** widgets (per-user tokens), create a [Widget App](/features/widget-apps) to get an API key, then mint short-lived tokens server-side: ```bash theme={null} curl -X POST https://api.chattermate.chat/api/v1/generate-token \ -H "Authorization: Bearer $WIDGET_APP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"widget_id":"YOUR_WIDGET_ID","customer_email":"user@customer.com","ttl_seconds":3600}' ``` ## Drive it over MCP instead of the shell Prefer to let your AI agent configure ChatterMate through the Model Context Protocol? The same package ships an MCP server (`chattermate-mcp`). See the [MCP Server guide](/features/mcp-server) for a ready-to-paste client config — it authenticates with the same `cmat_` Personal Access Token. ## Command reference | Step | Command | | --------------------- | --------------------------------------------------------------------------------------------------------------- | | Install | `pip install chattermate-cli` (or `npm install -g chattermate-cli`) | | Sign up | `chattermate signup --name … --domain … --admin-email … --admin-name …` | | AI model | auto-set to the free ChatterMate model at signup; switch with `chattermate ai setup --model-type … --api-key …` | | Log in | `chattermate login --email you@acme.com` | | Token | `chattermate token create [--expires-in-days N]` | | Agent | `chattermate agent create --name … --type … -i "…"` | | Knowledge (URL) | `chattermate knowledge add-url --website … [--agent-id …]` | | Knowledge (local PDF) | `chattermate knowledge add-file ./guide.pdf [--agent-id …]` | | Workflow | `chattermate workflow create --agent-id … --name …` | Every command, flag, and environment variable. Let an AI agent configure ChatterMate over MCP. # Configure AI Provider Source: https://docs.chattermate.chat/features/ai-configuration Configure your AI provider in ChatterMate — OpenAI, Anthropic (Claude), Google Gemini, Mistral, xAI Grok, DeepSeek, or Groq — with your own API key to power 24/7 support. # AI Provider Configuration Configure your preferred AI provider to power ChatterMate's intelligent customer support capabilities. AI Provider Configuration ## Available Providers ChatterMate supports multiple AI providers, giving you the flexibility to choose the one that best fits your needs: GPT-4.1, GPT-4o, and o-series models Claude Opus, Sonnet, and Haiku Gemini 2.5 Pro / Flash Mistral Large, Medium, and Small Grok 4 and Grok 3 DeepSeek Chat and Reasoner Ultra-fast inference (GPT-OSS, Llama) Every provider is **bring-your-own-key** — you supply your own API key, encrypted at rest. When you pick a provider, a **"Get your API key"** link points to that provider's console. ## Configuration Fields ### AI Provider Select your provider from the grid. All listed providers support tool calling and structured output, so any of them works with ChatterMate's agents, knowledge search, and workflows: * **OpenAI** (Recommended): Best-in-class models with consistent performance * **Anthropic (Claude)**: Strong reasoning and analysis * **Google Gemini**: Large context windows, great price/performance * **Mistral / xAI (Grok) / DeepSeek / Groq**: Cost, speed, and self-hosting-friendly options Features that depend on structured output — automatic **lead capture**, **ending a resolved chat**, and **human handoff** — are most consistent on OpenAI and Anthropic models. Smaller open models (e.g. Groq's GPT-OSS, some Grok variants) handle these well most of the time but can occasionally miss a step. If you find a model isn't capturing leads or closing chats reliably, switch to a stronger model like GPT-4.1 or Claude. ### Model Name Pick a suggested model from the dropdown, or choose **"Custom model ID"** to type any model your provider supports (handy when a provider ships a new model before this list updates). Suggested models: ```bash OpenAI (Recommended) theme={null} gpt-4.1 # Strong general default gpt-4o # Fast, capable gpt-4o-mini # Cost-effective o4-mini # Reasoning model ``` ```bash Anthropic (Claude) theme={null} claude-opus-4-8 # Most capable claude-sonnet-5 # Balanced performance claude-haiku-4-5 # Fast and efficient ``` ```bash Google Gemini theme={null} gemini-2.5-pro # Highest quality gemini-2.5-flash # Best price/performance ``` ```bash Mistral theme={null} mistral-large-latest # Flagship mistral-small-latest # Cost-effective ``` ```bash xAI (Grok) theme={null} grok-4 # Flagship reasoning model grok-3 # Previous generation ``` ```bash DeepSeek theme={null} deepseek-chat # General model deepseek-reasoner # Reasoning model ``` ```bash Groq theme={null} openai/gpt-oss-120b # Top quality on Groq llama-3.3-70b-versatile # Fast, reliable ``` Model IDs change over time as providers release and retire models. If a suggested ID stops working, use **Custom model ID** and paste the current identifier from your provider's docs. ### API Key Your provider's API key for authentication. Security measures: * Keys are encrypted before storage * Keys are never logged or exposed in plaintext * Access is restricted to authorized systems only * Regular key rotation is supported * Compliance with SOC 2 standards Never share your API keys or commit them to version control. ChatterMate encrypts and stores them securely. ## Best Practices 1. **Provider Selection** * Start with OpenAI's GPT-4.1 / GPT-4o for best overall performance * Consider Anthropic's Claude for complex reasoning tasks * Use Groq (GPT-OSS / Llama) when you want the fastest, lowest-cost inference 2. **Model Choice** * Balance between capability and cost * Test different models before production * Monitor usage and adjust as needed 3. **Security** * Use environment-specific API keys * Rotate keys periodically * Monitor usage for anomalies ## What's Next? After configuring your AI provider: 1. Test the configuration with sample queries 2. Customize the AI agent's behavior 3. Add domain knowledge to improve responses 4. Set up human handoff rules Next: Learn how to customize your AI agent's behavior # Customize AI Agent Source: https://docs.chattermate.chat/features/ai-customization Customize ChatterMate AI agents with custom instructions, personality, and AI or workflow modes for consistent, on-brand support in your company voice. # AI Agent Customization Customize your AI agents to provide consistent, on-brand customer support that aligns with your organization's voice and requirements. Agent Management Dashboard ## Agent Modes Your AI agent can operate in two different modes: * **AI Mode**: Traditional AI-powered conversations with customizable instructions * **Workflow**: Advanced workflow-based responses with conditional logic and automation Agent Configuration ## Basic Configuration ### Instructions Configure detailed instructions for your AI agent to: * Define how the agent should behave and communicate * Set guidelines for handling customer interactions * Establish response patterns and tone * Use the "Generate with AI" feature for intelligent instruction creation ### Transfer to Human Enable automatic transfer to human agents when: * AI agent can't handle the query * Customer specifically requests human support * Complex issues require human intervention When transfer is enabled, you can select specific user groups that can handle transferred conversations. ### Ask for Rating * Enable/disable automatic rating requests at chat end * Collect customer satisfaction metrics * Track agent performance ### Status Management * Toggle agent between Online/Offline states * Offline agents won't accept new conversations * Status is clearly displayed to customers Chat Customization ## Visual Customization ### Chat Style Choose from different chat interface styles: #### Chatbot Style 💬 * Traditional customer support interface * Features agent branding and formal layout * Best for business customer support scenarios * Standard email collection and greeting flow #### Ask Anything Style 🤖 * Modern AI assistant interface * Larger, more prominent design with welcome message * Perfect for general-purpose AI assistants * Features customizable welcome title and subtitle * Clean, conversation-focused layout The "Ask Anything" style provides additional customization options for welcome messages and uses a wider chat interface optimized for AI conversations. ### Welcome Message (Ask Anything Style) When using the "Ask Anything" chat style, you can customize: #### Welcome Title * Personalized greeting for your AI assistant * Defaults to "Welcome to \[Agent Name]" if left empty * Maximum 100 characters #### Welcome Subtitle * Engaging description of your AI's capabilities * Defaults to "I'm here to help you with anything you need. What can I assist you with today?" * Maximum 250 characters * Supports multiple lines for detailed descriptions ### Colors Customize the appearance of your chat widget: #### Background * Set the background color of the chat interface * Default color palette available for quick selection #### Chat Bubble * Customize the color of chat message bubbles * Maintain brand consistency with your website #### Accent * Configure accent colors for interactive elements * Used for buttons, highlights, and call-to-action elements ### Typography #### Font Family * Choose from system fonts: Inter, system-ui, sans-serif * Ensure readability and brand alignment * Consistent typography across all chat elements All customizations are instantly reflected in the chat preview on the right side of the interface. Test & Preview ## Chat Preview ### Real-time Testing This preview shows exactly how your chat widget will appear to users: * Test all customizations in real-time * Verify agent responses and behavior * Ensure proper styling and branding * Check functionality before deployment ### Interactive Testing * Type messages to test agent responses * Verify knowledge base integration * Test transfer to human functionality * Validate rating system behavior Use this preview to thoroughly test your agent before making it live to ensure the best customer experience. Knowledge Sources ## Knowledge Sources Connect your agent to various knowledge sources to enhance its responses with context-relevant information. ### Adding Knowledge Sources * **+ Add Knowledge**: Upload documents, websites, or other content * **Link Existing**: Connect to previously configured knowledge bases ### Knowledge Management View and manage all connected knowledge sources: * **Source**: Name and origin of the knowledge * **Type**: Document type or source format * **Subpages**: Number of indexed pages or sections * **Created**: When the knowledge source was added * **Actions**: Edit, update, or remove knowledge sources Add knowledge sources to improve the agent's responses and reduce "I don't know" scenarios. Agent Integrations ## Jira Integration ### Create Jira Tickets Enable automatic ticket creation for: * Issues without immediate resolution * No transfer agent available * Transfer requests not attended * Customer follow-ups * Complex issues requiring tracking ### Configuration * Select Jira project for ticket creation * Choose appropriate issue type * Configure when tickets should be created Jira connection must be established in settings before enabling ticket creation. MCP Tools ## MCP Tools Integration Connect external tools and services to your agent using the Model Context Protocol (MCP). These tools extend your agent's capabilities with access to file systems, APIs, databases, and more. ### Adding MCP Tools * **Create Tool**: Configure new MCP servers and tools * **Link Existing**: Connect to previously configured MCP tools from your organization ### Tool Management View and manage all connected MCP tools: * **Tool**: Name and description of the MCP tool * **Type**: Transport protocol (STDIO, SSE, HTTP) * **Configuration**: Connection details and parameters * **Status**: Enabled/disabled state * **Actions**: Edit, unlink, or delete MCP tools ### Popular MCP Tools Choose from pre-configured templates: * **File System**: Access and manage files and directories * **Git Repository**: Interact with Git repositories * **Web Search**: Search the web using Brave Search API * **Weather**: Get weather information MCP tools require proper configuration and may need API keys or specific permissions to function correctly. Widget Integration ## Widget Integration Add the chat widget to your website by copying and pasting the following code: ```html theme={null} ``` Replace `YOUR_WIDGET_ID` and `YOUR_WIDGET_URL` with your actual widget credentials. ### Widget Features * Responsive design that works on all devices * Customizable appearance based on Chat Customization settings * Email collection for visitor identification * Real-time messaging capabilities * "Powered by ChatterMate" branding Advanced Settings ## Rate Limiting ### Enable Rate Limiting Configure rate limiting to protect your agent from abuse and control traffic: ### Daily Limit * Set maximum requests per IP address per day * Range: 10-1000 requests * Prevents abuse from single sources ### Rate Limit * Control requests per second * Range: 1-10 requests per second * Manages traffic flow and server load Rate limiting helps prevent abuse while ensuring legitimate users maintain access to support. ## Workflow Mode When using **Workflow** mode, your agent operates using predefined workflows instead of AI-generated responses. This provides: * **Structured Conversations**: Guide users through specific paths * **Conditional Logic**: Route conversations based on user inputs * **Automation**: Trigger actions based on conversation flow * **Consistency**: Ensure standardized responses for common scenarios Switch between AI Mode and Workflow using the toggle buttons at the top of the agent configuration. Learn how to extend your AI agent with external tools and services Next: Learn how to create advanced conversation workflows Learn how to enhance your AI agent with domain knowledge # Widget Authentication Source: https://docs.chattermate.chat/features/authentication Secure the ChatterMate chat widget with server-generated token authentication so signed-in users are identified and their conversations appear in the agent inbox. # Widget Authentication Secure your embedded chat widget with token-based authentication. ChatterMate supports both public and authenticated access modes to fit your application's needs. ## Authentication Modes ChatterMate offers two authentication modes for your widget: ### Public Access Mode The default mode allows anonymous visitors to start conversations without authentication. **How it works:** * Token is automatically generated when the widget initializes * Visitors can chat immediately without signing in * Email collection is optional (based on chat style settings) * Conversation history is linked to the generated token **Best for:** * Public support websites * Documentation assistants * General Q\&A interfaces * Lead generation chatbots ### Authenticated Access Mode Require a valid token before users can start chatting. Enable this for secure, authenticated applications. **How it works:** * Widget requires a pre-generated token to initialize * Your backend requests the token from ChatterMate with the user's details * Conversations are linked to a stored customer (matched by email) * Previous conversation history loads automatically **Best for:** * Customer portals * SaaS applications * Internal support tools * Apps with user authentication Enable required authentication by setting `require_token_auth: true` on your agent configuration. ## How Token Authentication Works Authenticated mode uses **server-to-server token generation**. Your backend calls ChatterMate's `/generate-token` endpoint with a **Widget App API key** and the user's details. ChatterMate creates (or matches) a customer record, then returns a short-lived JWT that the widget uses to start the chat. You do **not** sign your own JWTs. ChatterMate issues and signs the token — that's how it registers the token for revocation and links the conversation to a stored customer. All you provide is your API key and the user's email/name. (Your `CONVERSATION_SECRET_KEY` is an internal server secret and is never used by integrators.) ### What you need In the ChatterMate dashboard, open **Widget Apps** and create an app. Copy the API key — it is shown only once. Treat it as a server-side secret. Set `require_token_auth: true` on your agent to reject anonymous visitors so a token is always required. ### Token flow When a signed-in user opens a page with the widget, your backend calls `POST /api/v1/generate-token` with your API key and the user's email and name. Return the token to your page and set `window.chattermateToken` before the widget script loads. ChatterMate stores the email and name as a **customer** (matched by email) and links the conversation to it — so the user's email and name appear in the agent inbox, and their history reloads automatically. ## Implementation ### 1. Generate a token on your backend Call `/generate-token` with your Widget App API key in the `Authorization` header. ChatterMate returns a signed token bound to the customer. ```bash cURL theme={null} curl -X POST https://api.chattermate.chat/api/v1/generate-token \ -H "Authorization: Bearer YOUR_WIDGET_APP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "widget_id": "YOUR_WIDGET_ID", "customer_email": "user@example.com", "customer_name": "John Doe", "ttl_seconds": 3600 }' ``` ```javascript Node.js theme={null} async function generateWidgetToken(email, name) { const res = await fetch('https://api.chattermate.chat/api/v1/generate-token', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.CHATTERMATE_WIDGET_APP_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ widget_id: 'YOUR_WIDGET_ID', customer_email: email, // stored as the customer + shown in the inbox customer_name: name, ttl_seconds: 3600, // 60–86400 (default 3600) }), }); const { data } = await res.json(); return data.token; } ``` ```python Python theme={null} import os, requests def generate_widget_token(email: str, name: str) -> str: res = requests.post( "https://api.chattermate.chat/api/v1/generate-token", headers={"Authorization": f"Bearer {os.environ['CHATTERMATE_WIDGET_APP_API_KEY']}"}, json={ "widget_id": "YOUR_WIDGET_ID", "customer_email": email, # stored as the customer + shown in the inbox "customer_name": name, "ttl_seconds": 3600, # 60–86400 (default 3600) }, ) return res.json()["data"]["token"] ``` The response contains the token and its expiry: ```json theme={null} { "success": true, "data": { "token": "eyJhbGci...", "widget_id": "YOUR_WIDGET_ID", "expires_in": 3600, "expires_at": "2026-07-06T18:00:00+00:00", "created_at": "2026-07-06T17:00:00+00:00" }, "message": "Token generated successfully. Expires in 3600 seconds." } ``` `customer_email` is optional — omit it and ChatterMate creates an anonymous customer. Passing it is what links the conversation to a named customer in the inbox, and if the same email returns later the existing customer (and their history) is reused. `customer_name` updates the stored name when it changes. ### Passing extra customer metadata Pass `custom_data` to attach arbitrary fields to the customer — for example a student's name and coaching center for a tutoring app, or an account tier and plan for a SaaS app. ChatterMate stores these on the customer record and shows them to agents in the chat inbox, right alongside the name and email. ```json theme={null} { "widget_id": "YOUR_WIDGET_ID", "customer_email": "parent@example.com", "customer_name": "Priya Krishnan", "custom_data": { "student_name": "Aarav Krishnan", "center_name": "Special Academy U12" }, "ttl_seconds": 3600 } ``` `custom_data` is capped at 20 keys and 4KB serialized. Calling `/generate-token` again for the same customer **merges** new keys into what's already stored — existing keys are overwritten if present in the new call, and any keys you don't send are left untouched. ### 2. Pass the token to the widget Set `window.chattermateToken` **before** the loader script runs: ```html theme={null} ``` The widget reads `window.chattermateToken`, sends it as a `Bearer` token, and ChatterMate resolves it back to the stored customer for the whole conversation. ### What's inside the token You don't build this yourself — ChatterMate signs it — but for reference the issued token carries: | Field | Description | | --------------------- | ---------------------------------------------------------------------- | | `sub` / `customer_id` | ChatterMate customer id (derived from the email) | | `widget_id` | The widget the token is bound to | | `customer_email` | Email you supplied (stored on the customer) | | `customer_name` | Name you supplied | | `custom_data` | Extra fields you supplied (merged into the customer's stored metadata) | | `jti` | Token id, used for revocation | | `exp` | Expiration timestamp | ## Security Features Tokens are scoped to your organization. Cross-organization access is prevented. All tokens are cryptographically signed and verified on each request. Tokens are bound to specific widgets, preventing cross-widget token reuse. Every token has a JTI and a TTL (60s–24h), so it can be revoked and expires quickly. Never expose your **Widget App API key** in client-side code. Call `/generate-token` only from your backend, and hand the browser just the short-lived token it returns. ## Best Practices 1. **Token Expiration** * Keep `ttl_seconds` short (default 1 hour); the range is 60s–24h * Request a fresh token per page load or session rather than reusing long-lived ones * Handle expired-token errors by re-requesting a token 2. **Secure Generation** * Call `/generate-token` server-side only, with the API key in an environment variable * Regenerate the key from **Widget Apps** if it is ever exposed 3. **Customer Identification** * Always pass `customer_email` so conversations are attributed to a named customer in the inbox * Keep the same email for a returning user so their history and customer record are reused * Pass `customer_name` to show a friendly name to your agents * Use `custom_data` for context agents need at a glance (e.g. account tier, plan, or in a tutoring app the student's name and center) — it shows up in the inbox next to the customer's name and email ## Troubleshooting * Confirm the `Authorization: Bearer ` header uses a valid **Widget App** key (not your account password or the widget id) * Make sure the key hasn't been regenerated/deactivated in the dashboard * Check the `widget_id` in the body belongs to the same organization as the API key * The agent has `require_token_auth: true`, so `window.chattermateToken` must be set **before** the loader script runs * Verify the token isn't expired (check `expires_at`) * Check the browser console for JavaScript errors * You must pass `customer_email` (and ideally `customer_name`) to `/generate-token` — a self-signed JWT or a token without an email won't create a named customer * Reuse the same email for the same user so the existing customer is matched instead of a new one being created ## What's Next? After configuring authentication: 1. Set up your widget integration 2. Configure chat customization options 3. Test with authenticated and anonymous users Learn how to integrate the widget into your website # Email Source: https://docs.chattermate.chat/features/channels/email Turn a support@ inbox into an AI-answered channel — point your provider inbound-parse webhook at ChatterMate and optionally send replies from your own SMTP. # Email Connect a shared support inbox (like `support@yourcompany.com`) and your AI agent answers email the same way it answers chat — threaded, in the unified inbox, with human handover. There's no approval process; you just need a way to deliver inbound mail to ChatterMate as a webhook and (optionally) an SMTP path for replies. ## How email flows * **Inbound:** your mail provider forwards each incoming email to a ChatterMate webhook URL (via "inbound parse" or plain forwarding). * **Outbound:** ChatterMate sends replies over SMTP — either your own per-inbox SMTP, or the platform's default mail server. Replies keep the `Message-ID`/`References` headers so they thread correctly in the customer's mailbox. ## Step 1 — Connect the inbox in ChatterMate Do this first — connecting generates the webhook URL you'll paste into your mail provider. Go to **Settings → Integrations** and click **Connect** on the **Email** card. Enter the **support email address** customers write to (e.g. `support@yourcompany.com`). Leave the SMTP fields blank to send replies via the platform mail server, or fill them in to send from your own domain (better deliverability with your SPF/DKIM): | Field | Example | | ------------- | ------------------------------- | | SMTP host | `smtp.yourprovider.com` | | SMTP port | `587` (STARTTLS) or `465` (SSL) | | SMTP username | `apikey` / your login | | SMTP password | your SMTP password or API key | | From address | defaults to the support address | After connecting, ChatterMate shows an inbound webhook URL like: `https:///api/v1/webhooks/email/?token=` Keep it handy for step 2. The token authenticates the inbound mail — don't share it. Pick the AI agent that should answer this inbox and click **Assign agent**. ## Step 2 — Point your mail provider at ChatterMate Pick whichever matches your setup: 1. Point an MX record for a subdomain (e.g. `parse.yourcompany.com`) at SendGrid (`mx.sendgrid.net`). 2. In SendGrid → **Settings → Inbound Parse → Add Host & URL**, set the host to that subdomain and the **Destination URL** to the webhook URL from step 1. 3. Forward `support@yourcompany.com` to an address on the parse subdomain (or receive directly on it). Configure Brevo's inbound email parsing and set the destination URL to the ChatterMate webhook URL from step 1. If your provider can POST inbound mail to a webhook (or forward to a parse service), point it at the ChatterMate URL. A simple mailbox forward into a SendGrid/Brevo parse address works too. ## Step 3 — Deliverability (recommended) If you send replies from your own domain, publish **SPF**, **DKIM**, and **DMARC** DNS records for the sending domain so replies land in the inbox, not spam. **Gmail / Google Workspace SMTP:** use an **App Password**, not your normal account password (which Google blocks for SMTP). Create one at [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords) with 2-Step Verification enabled. ChatterMate shows this hint automatically if SMTP auth fails. ## Test it Send an email to your support address. The AI agent replies, and the thread appears in **Conversations** with an **Email** badge. **Take Over Chat** lets a human reply in the same email thread. # Instagram Source: https://docs.chattermate.chat/features/channels/instagram Connect Instagram DMs to ChatterMate through the Meta Graph API so your AI agent answers direct messages on a professional Instagram account, with human handover. # Instagram **Coming soon in the hosted app.** The Instagram card in **Settings → Integrations** shows **Soon** while ChatterMate finishes Meta app review for the Cloud offering. Self-hosters can connect now with their own Meta app and linked Page token. Connect a **professional Instagram account** and your AI agent answers Instagram direct messages. Instagram DMs run on the same Meta app and webhook as Messenger, so setup is nearly identical — the account just has to be a Business or Creator account linked to a Facebook Page. ## Prerequisites * An Instagram **Business** or **Creator** account (not personal). * The Instagram account **linked to a Facebook Page** (Instagram → Settings → linked accounts, or from the Page's settings). ## Step 1 — Set up a Meta app If you already created a Meta app for WhatsApp or Messenger, skip to step 2. Go to [developers.facebook.com](https://developers.facebook.com) → **My Apps → Create App** → **Business**. Complete Business Verification in [business.facebook.com](https://business.facebook.com) → **Security Center**. Start it first — it gates production access. Add the **Instagram** product and link your professional account (Instagram messaging is configured through the Messenger/Instagram settings). Set the callback URL to `https:///api/v1/webhooks/meta` with your `META_WEBHOOK_VERIFY_TOKEN`, and subscribe to Instagram **messages**. ## Step 2 — Copy your credentials | Credential | Where to find it | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Instagram account ID** | The IG account's numeric ID (e.g. `17841400000000000`), from the Graph API or the linked-account settings. | | **Linked Page access token** | The access token for the Facebook Page the Instagram account is linked to (System User token for a permanent one). | ## Step 3 — App Review (to message real customers) Submit **App Review** for: * `instagram_basic` * `instagram_manage_messages` * (plus `pages_show_list`, `business_management`) Include a narrated **screencast** showing a customer DMing your Instagram account and ChatterMate replying. ## Step 4 — Connect in ChatterMate Go to **Settings → Integrations** and click **Connect** on the **Instagram** card (self-hosted / once available). Paste the **Instagram account ID** and the **linked Page access token**. ChatterMate encrypts them and verifies inbound webhook signatures. Choose the AI agent that answers Instagram and click **Assign agent**. If the account isn't a professional account linked to a Page, connecting fails — ChatterMate surfaces the reason so you can fix the link and retry. ## Test it DM your Instagram account. The AI agent replies, and the conversation appears in **Conversations** with an **Instagram** badge and human handover. # LINE Source: https://docs.chattermate.chat/features/channels/line Connect a LINE Official Account to ChatterMate with a channel secret and access token so your AI agent answers customers on LINE — popular across Japan, Thailand and Taiwan. # LINE Connect a **LINE Official Account** and your AI agent answers customers messaging you on LINE. LINE is one of the biggest messaging apps in Japan, Thailand, and Taiwan — prioritize it if that's where your customers are. Setup takes a channel secret and an access token; ChatterMate registers the webhook for you. ## What you'll need * A [LINE Business ID](https://account.line.biz/) (free). * A **Messaging API channel** in the LINE Developers console. ## Step 1 — Create a Messaging API channel and get your keys Go to the [LINE Developers Console](https://developers.line.biz/) → create a **Provider** (your company) → **Create a Messaging API channel**. Fill in the channel name, description, and category. This also creates a **LINE Official Account** you manage at [manager.line.biz](https://manager.line.biz/). On the channel's **Basic settings** tab, copy the **Channel secret**. ChatterMate uses it to verify incoming webhook signatures. On the **Messaging API** tab, issue a **long-lived Channel access token** and copy it. This lets ChatterMate send replies. In the [Official Account Manager](https://manager.line.biz/) → **Settings → Response settings**, turn **Auto-reply messages** off and enable **Webhooks**, so your AI agent (not LINE's canned replies) answers customers. ## Step 2 — Connect in ChatterMate Go to **Settings → Integrations** and click **Connect** on the **LINE** card. Enter the **Channel secret** and **Channel access token**. ChatterMate stores them encrypted and registers the webhook automatically — you don't need to paste a webhook URL into the LINE console. Choose the AI agent that answers LINE and click **Assign agent**. ## Step 3 — Test it Add your Official Account as a friend (scan its QR code from the Official Account Manager) and send a message. The AI agent replies — with a LINE loading animation while it thinks — and the chat appears in **Conversations** with a **LINE** badge. No heavy approval is needed to send and receive messages — a working Official Account is enough. A **Verified** or **Premium** badge (blue/green) is optional; apply for it in the Official Account Manager if you want the verified checkmark (LINE reviews the business over a few days). # Messenger Source: https://docs.chattermate.chat/features/channels/messenger Connect Facebook Messenger to ChatterMate through the Meta Graph API so your AI agent answers Page direct messages, with human handover into the same conversation. # Messenger **Coming soon in the hosted app.** The Messenger card in **Settings → Integrations** shows **Soon** while ChatterMate finishes Meta app review for the Cloud offering. Self-hosters can connect now with their own Meta app and Page access token. Connect a Facebook **Page** and your AI agent answers direct messages sent to it on Messenger. Messenger uses the same Meta app as WhatsApp and Instagram, so if you've set one up already you only need the Page-specific steps. ## How Messenger messaging works Messages come in as **PSIDs** (Page-scoped user IDs). Messenger has a **24-hour standard messaging window** — you can reply for 24 hours after the customer's last message; outside it, only specific message tags are allowed. ## Step 1 — Set up a Meta app If you already created a Meta app for WhatsApp or Instagram, skip to step 2. Go to [developers.facebook.com](https://developers.facebook.com) → **My Apps → Create App** → **Business**. Complete Business Verification in [business.facebook.com](https://business.facebook.com) → **Security Center** (a few days to \~2 weeks). Start it first. Add the **Messenger** product in the app dashboard and link your Facebook **Page**. Under **Messenger → Settings → Webhooks**, set the callback URL to `https:///api/v1/webhooks/meta` with your `META_WEBHOOK_VERIFY_TOKEN`, and subscribe your Page to the **messages** and **messaging\_postbacks** fields. ## Step 2 — Copy your Page credentials From **Messenger → Settings** in the app dashboard: | Credential | Where to find it | | --------------------- | ----------------------------------------------------------------------------------------------- | | **Facebook Page ID** | Your Page's numeric ID (Page → About, or the Messenger settings panel). | | **Page access token** | Generate a Page access token for the linked Page (use a System User token for a permanent one). | ## Step 3 — App Review (to message real customers) To message people who don't have a role on the app, submit **App Review** for: * `pages_messaging` * `pages_manage_metadata` * `pages_show_list` * `business_management` Include a narrated **screencast** showing a customer messaging your Page and ChatterMate replying. ## Step 4 — Connect in ChatterMate Go to **Settings → Integrations** and click **Connect** on the **Messenger** card (self-hosted / once available). Paste the **Facebook Page ID** and **Page access token**. ChatterMate encrypts them and verifies every inbound webhook signature. Choose the AI agent that answers Messenger and click **Assign agent**. ## Test it Message your Page from a Facebook account with a role on the app (before approval) or any account (after approval). The AI agent replies, and the chat appears in **Conversations** with a **Messenger** badge and full human handover. # Messaging Channels Source: https://docs.chattermate.chat/features/channels/overview Connect ChatterMate to Telegram, WhatsApp, Messenger, Instagram, Slack, Email, SMS and LINE so one AI agent answers every customer message in a single unified inbox. # Messaging Channels ChatterMate is omni-channel. The same AI agent — with your knowledge base, lead capture, and human handover — answers customers wherever they message you, and every conversation lands in one **unified inbox**. ChatterMate Integrations page showing messaging channel cards ## Available channels Paste a bot token from @BotFather. Live in minutes, no approval. One-click OAuth. Answers @mentions and DMs in your workspace. Turn a support@ inbox into an AI-answered channel. Twilio, Vonage, MessageBird, Plivo, Brevo or AWS SNS. Connect a LINE Official Account with a channel access token. Official WhatsApp Cloud API. Coming soon in the hosted app. Facebook Page DMs. Coming soon in the hosted app. Instagram DMs on a professional account. Coming soon. ## How connecting works Every channel follows the same three steps. The credential-gathering (step 1) differs per platform — that's what each channel page walks you through. Create the bot / app / number on the platform (Telegram, Meta, Twilio, LINE…) and copy the keys. Each channel page below has the exact clicks. Open **Settings → Integrations**, find the channel card, and click **Connect**. Paste your credentials (or, for Slack, approve the OAuth popup). ChatterMate encrypts every credential at rest and — where the platform supports it — registers the inbound webhook for you automatically. Right after connecting, ChatterMate asks which AI agent should answer this channel. Pick one and click **Assign agent**. You can change it any time from the card's **Manage** button. Choosing the AI agent that answers a channel ## One inbox for every channel Once connected, messages from all channels flow into **Conversations**. Each chat carries a badge showing where it came from (Slack, Email, LINE…), and your team replies from the same place — whether the customer is on WhatsApp or the website widget. Unified Conversations inbox with per-channel badges ### Human handover reaches every channel When a teammate clicks **Take Over Chat**, their replies go back out on the customer's original channel — the Telegram chat, the Slack thread, the email thread — not just the widget. The AI steps aside until the conversation is handed back. ## Good to know All channel tokens and secrets are Fernet-encrypted at rest, and every inbound webhook is signature-verified before it's processed. Every channel is bring-your-own-credentials. Self-hosters create their own bots/apps; nothing depends on ChatterMate's own platform approvals. ChatterMate never asks customers to rate the conversation on external channels — the rating prompt is exclusive to the website chat widget. Each channel is answered by the AI agent you assign, so different products or brands can have their own agent and knowledge base. Self-hosting? Inbound webhooks need a **public HTTPS** URL. Set `BACKEND_URL` to your public backend domain so ChatterMate can build and register webhook URLs the platforms can reach. # Slack Source: https://docs.chattermate.chat/features/channels/slack Connect a Slack workspace to ChatterMate with one-click OAuth so your AI agent answers @mentions and direct messages, with full human handover into the thread. # Slack Connect a Slack workspace and your AI agent answers **@mentions** in channels and **direct messages** to the bot. Replies stay in-thread, teammates can take over from the ChatterMate inbox, and the agent shows real display names and a typing indicator. ## Two ways to connect * **ChatterMate Cloud** — click **Connect**, approve the OAuth popup, done. No app to create. Skip to [Connect in ChatterMate](#connect-in-chattermate). * **Self-hosted** — create your own Slack app once (below), set three environment variables, then connect via OAuth. ## Step 1 — Create a Slack app (self-hosted only) Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From scratch**. Name it **ChatterMate** and pick your workspace. Under **OAuth & Permissions → Bot Token Scopes**, add: `app_mentions:read`, `chat:write`, `im:history`, `im:read`, `im:write`, `users:read` (`users:read` lets the agent resolve real display names instead of raw user IDs.) Still under **OAuth & Permissions**, add a **Redirect URL**: `https:///api/v1/channels/slack/callback` Under **Event Subscriptions**, turn it on and set the **Request URL** to: `https:///api/v1/webhooks/slack` Then subscribe to bot events **`app_mention`** and **`message.im`**. Slack sends a one-time challenge to verify the URL — ChatterMate answers it automatically. From **Basic Information**, copy the **Client ID**, **Client Secret**, and **Signing Secret**, and set them as environment variables: ```bash theme={null} SLACK_CLIENT_ID=... SLACK_CLIENT_SECRET=... SLACK_SIGNING_SECRET=... ``` No Slack approval is required to install your own app. A **Slack Marketplace** listing (to appear in the public directory) is optional and Cloud-only — it triggers Slack's security review and takes a few weeks. Self-hosters never need it. ## Step 2 — Connect in ChatterMate Go to **Settings → Integrations** and click **Connect** on the **Slack** card. A Slack authorization popup opens. Approve the requested permissions and pick the workspace to install into. ChatterMate stores the bot token encrypted — no manual credential entry. After the popup closes, ChatterMate asks which AI agent answers this workspace. Choose one and click **Assign agent**. You can change it later from the card's **Manage** button. ## Step 3 — Test it Invite the bot to a channel and **@mention** it, or send it a direct message. The AI agent replies in-thread and the conversation appears in **Conversations** with a **Slack** badge. Click **Take Over Chat** to reply as a human — your messages post back into the same Slack thread. Because Slack has no native bot "typing…" indicator, ChatterMate posts a brief placeholder message and edits it into the reply, so customers see immediate feedback while the agent thinks. # SMS Source: https://docs.chattermate.chat/features/channels/sms Connect SMS to ChatterMate through Twilio, Vonage, MessageBird, Plivo, Brevo or AWS SNS — bring your own provider account and let your AI agent answer text messages. # SMS Let customers text your AI agent. SMS is a single ChatterMate channel backed by **six providers** — pick the one you already use (or the one with the best rates in your country), bring your own account, and enter its API credentials. | Provider | Credentials ChatterMate asks for | | ---------------------- | ------------------------------------------------------------------------ | | **Twilio** | Account SID, Auth token | | **Vonage (Nexmo)** | API key, API secret, Signature secret *(optional)* | | **MessageBird (Bird)** | Access key, Signing key *(optional)* | | **Plivo** | Auth ID, Auth token | | **Brevo** | API key | | **AWS SNS** | AWS access key ID, AWS secret access key, Region, Topic ARN *(optional)* | The *(optional)* signing fields enable webhook signature verification — recommended in production so only your provider can post messages to ChatterMate. ## Step 1 — Get your provider credentials 1. Sign in at [console.twilio.com](https://console.twilio.com). 2. From the dashboard, copy your **Account SID** and **Auth Token**. 3. Buy or choose an SMS-capable **phone number** (Phone Numbers → Manage → Active numbers), in E.164 format (e.g. `+14155551234`). 1. Sign in at [dashboard.nexmo.com](https://dashboard.nexmo.com). 2. Copy your **API key** and **API secret** from the dashboard. 3. (Recommended) Under **Settings**, set the signature method to **SHA-256 HMAC** and copy the **Signature secret** so ChatterMate can verify inbound webhooks. 4. Have a Vonage virtual **number** ready. 1. Sign in at [dashboard.messagebird.com](https://dashboard.messagebird.com). 2. Create and copy a live **Access key** (Developers → API access). 3. (Recommended) Copy your **Signing key** for webhook verification. 4. Have a purchased **number** ready. 1. Sign in at [console.plivo.com](https://console.plivo.com). 2. Copy your **Auth ID** and **Auth Token** from the overview page. 3. Buy an SMS-capable **number** (Phone Numbers → Buy Numbers). 1. Sign in at [app.brevo.com](https://app.brevo.com). 2. Create an **API key** (Settings → SMS/API keys). 3. Set up a **sender** / number for transactional SMS. 1. In the [AWS Console](https://console.aws.amazon.com), create an IAM user with SNS publish permissions and copy its **Access key ID** and **Secret access key**. 2. Note your **region** (e.g. `us-east-1`). 3. For inbound (two-way) SMS, create an **SNS topic** for incoming messages and copy its **Topic ARN**. ## Step 2 — Connect in ChatterMate Go to **Settings → Integrations** and click **Connect** on the **SMS** card. Select your **provider** from the dropdown — the credential fields update to match it (see the table above). Enter your sending **phone number** (E.164) and the API credentials. After connecting, ChatterMate shows an inbound webhook URL like: `https:///api/v1/webhooks/sms//` Pick the AI agent that answers SMS and click **Assign agent**. ## Step 3 — Point your number's inbound webhook at ChatterMate Set the URL from step 2 as your number's incoming-message webhook: * **Twilio** — Phone number → Messaging → **"A message comes in"** → Webhook (HTTP POST). * **Vonage** — set the number's **Inbound SMS webhook**. * **MessageBird / Plivo** — attach the number to an application/flow whose inbound URL is the ChatterMate webhook. * **Brevo** — set the inbound SMS webhook URL. * **AWS SNS** — subscribe your inbound SMS topic to the ChatterMate URL as an **HTTPS subscription**. ChatterMate confirms the subscription automatically. ## Carrier registration (important for the US) Carriers filter unregistered traffic. To send reliably in the US: * **A2P 10DLC** — register a **Brand** and **Campaign** with your provider (a Twilio/Plivo/etc. console step). Approval takes days to \~2 weeks. * **Toll-free** — submit toll-free verification instead. This registration is done by the number's owner (you), on the provider side — it isn't a ChatterMate step. Requirements outside the US vary by country (sender IDs, local number rules) — check your provider's country guidelines. ## Test it Text your connected number. The AI agent replies, and the conversation appears in **Conversations** with an **SMS** badge. **Take Over Chat** hands the conversation to a human, whose replies go back out as SMS. # Telegram Source: https://docs.chattermate.chat/features/channels/telegram Connect a Telegram bot to ChatterMate in minutes — create it with BotFather, paste the token, and your AI agent starts answering customers on Telegram. # Telegram Telegram is the fastest channel to go live — no review, no approval. You create a bot with Telegram's **@BotFather**, paste its token into ChatterMate, and your AI agent answers every message the bot receives. ## What you'll need * A Telegram account (to talk to @BotFather). * Two minutes. ## Step 1 — Create a bot and copy the token In any Telegram app, search for **@BotFather** (the one with the blue verified checkmark) and open a chat with it. Send `/newbot`. BotFather asks for: * a **display name** (e.g. "Acme Support") — what customers see. * a **username** ending in `bot` (e.g. `acme_support_bot`) — must be unique. BotFather replies with a token that looks like `123456789:AAF...`. Copy it — this is the only credential ChatterMate needs. Treat the token like a password. Anyone with it can control your bot. If it leaks, send `/revoke` to BotFather and reconnect with the new token. Optional polish, all via BotFather: `/setdescription`, `/setabouttext`, and `/setuserpic` to give the bot a description and avatar. `/setprivacy` → **Disable** lets the bot read all messages in group chats (leave enabled for one-to-one support). ## Step 2 — Connect in ChatterMate Go to **Settings → Integrations** and click **Connect** on the **Telegram** card. Paste the bot token, choose the AI agent that should answer, and confirm. ChatterMate validates the token with Telegram, then registers the webhook automatically — there's nothing to configure on Telegram's side. **Self-hosting:** Telegram delivers messages via webhook, so it needs to reach your backend over **public HTTPS**. Make sure `BACKEND_URL` is your public domain (not `localhost`) before connecting — ChatterMate surfaces Telegram's exact error if the webhook can't be set. ## Step 3 — Test it Open your bot in Telegram (search its username), send a message, and your assigned AI agent replies. The conversation appears in **Conversations** with a **Telegram** badge. To hand off to a human, open the chat and click **Take Over Chat** — your replies go straight back to the customer on Telegram. # WhatsApp Source: https://docs.chattermate.chat/features/channels/whatsapp Connect WhatsApp Business to ChatterMate through the official Meta Cloud API so your AI agent answers customers on WhatsApp, with 24-hour windows and templates handled. # WhatsApp **Coming soon in the hosted app.** The WhatsApp card in **Settings → Integrations** currently shows **Soon** while ChatterMate finishes Meta app review for the Cloud offering. Self-hosters can already connect with their own Meta app and credentials. This page covers how to get those credentials so you're ready. ChatterMate connects to WhatsApp through the **official WhatsApp Cloud API** from Meta — not an unofficial bridge — so your business number stays compliant and never risks a ban. Your AI agent answers customer messages, and human agents can take over from the inbox. ## How WhatsApp messaging works WhatsApp enforces a **24-hour customer service window**: you can reply freely for 24 hours after the customer's last message. Outside that window you can only send **pre-approved message templates**. ChatterMate tracks the window per conversation and tells you when a template is required. ## Step 1 — Set up a Meta app All three Meta channels (WhatsApp, Messenger, Instagram) run on **one Meta app**. Do this once. Go to [developers.facebook.com](https://developers.facebook.com) → **My Apps → Create App** → type **Business**. Name it (e.g. "Acme Support"). In [business.facebook.com](https://business.facebook.com) → **Business Settings → Security Center**, submit your legal business details and a verification document, and verify your domain. This gates production access and takes a few days to \~2 weeks — start it first. In the app dashboard, add the **WhatsApp** product. Meta gives you a test number immediately so you can build before approval. Under **WhatsApp → Configuration**, set the callback URL to `https:///api/v1/webhooks/meta` and the verify token to your `META_WEBHOOK_VERIFY_TOKEN`. Subscribe to the **messages** field. ## Step 2 — Copy your WhatsApp credentials From **WhatsApp → API Setup** in the app dashboard: | Credential | Where to find it | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | **Phone number ID** | Shown next to your WhatsApp number (a numeric ID, not the phone number itself). | | **Access token** | Generate a **permanent** token via a System User in Business Settings (temporary tokens expire in 24h). | | **WhatsApp Business Account ID** *(optional)* | The WABA ID — lets ChatterMate auto-subscribe the webhook. | ## Step 3 — App Review (to message real customers) The test number only messages people with a role on the app. To go live, submit **App Review** for: * `whatsapp_business_messaging` * `whatsapp_business_management` Include a narrated **screencast** showing a customer messaging your number and ChatterMate replying. Also complete, per number: * **Display name review** (Business Manager → WhatsApp Accounts → Phone Numbers). * **Message template approval** for anything sent outside the 24-hour window (each template is reviewed individually). ## Step 4 — Connect in ChatterMate Go to **Settings → Integrations** and click **Connect** on the **WhatsApp** card (self-hosted / once available). Paste the **Phone number ID**, **Access token**, and optionally the **WhatsApp Business Account ID**. ChatterMate stores them encrypted and verifies webhook signatures on every inbound message. Choose the AI agent that answers WhatsApp and click **Assign agent**. **ChatterMate Cloud** will offer **WhatsApp Embedded Signup**, so you can onboard your own number under ChatterMate's approved Meta app with a guided popup — no separate app or verification. A BSP (360dialog, Twilio) is an alternative that shortcuts parts of onboarding at a per-message cost. # Chat Management Source: https://docs.chattermate.chat/features/chat-management Manage customer conversations in ChatterMate with advanced filtering, human takeover from AI, chat reassignment, and full lifecycle control in one inbox. # Chat Management Monitor and manage customer conversations with advanced filtering, seamless human-AI collaboration, and comprehensive chat lifecycle management. Chat Management Dashboard ## Advanced Conversation Filtering ### Filter Options * **Agent Filter**: Filter conversations by specific AI agents * **User Filter**: Filter conversations by human agents/users * **Customer Email**: Search conversations by customer email * **Date Range**: Filter conversations within specific time periods * **Smart UI**: Icon-based filter toggle with active filter count indicator ### Filter Features * Apply-on-demand filtering (click "Apply Filters" to activate) * Auto-close filter panel after applying * Clear all filters with one click * Real-time filter count display ## Chat Information Panel ### Detailed Chat View * **Customer Information**: View customer details and contact information * **Assignment Tracking**: See current assignee and assignment timestamp * **Timeline**: Track chat creation and last update times * **Status Monitoring**: Real-time chat status (Open, Transferred, Closed) * **Toggleable Sidebar**: Discord/Slack-style panel that pushes content ### Panel Features * Responsive design matching conversation list height * Easy toggle on/off functionality * Comprehensive chat metadata display ## Chat Actions & Control Human agents can instantly take control of AI-handled conversations Transfer chats between human agents with notifications Close conversations with reason tracking and descriptions ### Human Takeover * **Smart Permissions**: Only available for open chats handled by AI * **Instant Transfer**: Seamless transition from AI to human agent * **Real-time Updates**: UI refreshes automatically after takeover * **Status Sync**: Chat assignment updated across all interfaces ### Chat Reassignment * **User Selection**: Easy dropdown with agent names and emails * **Validation**: Only open, user-handled chats can be reassigned * **Multi-party Notifications**: Automatic notifications sent to: * Customer (chat reassigned) * New assignee (new chat assigned) * Previous assignee (chat transferred) * **Real-time Sync**: Instant updates across all connected clients ### Automated Chat Management * **Auto-close**: AI-handled chats automatically close after 24 hours of inactivity * **Reason Tracking**: End chat reasons and descriptions for analytics * **Background Processing**: Daily worker checks for inactive chats ## Real-time Features ### Live Updates * Socket.IO integration for instant notifications * Real-time chat status changes * Multi-client synchronization * Toast notifications for user actions ### Notification System * Chat takeover notifications * Reassignment alerts * Status change updates * New message indicators ## What's Next? After setting up advanced chat management: 1. **Configure Filters**: Set up default filters for your team 2. **Train Agents**: Educate team on takeover and reassignment features 3. **Monitor Analytics**: Track chat lifecycle and agent performance 4. **Optimize Workflows**: Use reassignment for workload balancing 5. **Review Auto-close**: Adjust inactive chat timeout if needed # CLI Source: https://docs.chattermate.chat/features/cli Use the ChatterMate CLI to sign up, log in, mint access tokens, and configure agents, workflows, and knowledge from your terminal, built for automation and CI. # ChatterMate CLI The ChatterMate CLI (`chattermate`) lets you sign up, log in, mint access tokens, and configure agents, workflows, and knowledge sources directly from your terminal — no browser required. It's ideal for automation, CI pipelines, and scripting your ChatterMate setup. The CLI and MCP server are part of the **enterprise/commercial edition**. They authenticate with [Personal Access Tokens](#personal-access-tokens), which require the enterprise backend. **Not the tool you were looking for?** This page is the **account CLI** — it signs you up and manages agents, workflows, and knowledge against the ChatterMate API. If you want to **self-host ChatterMate with Docker**, you need the separate self-host CLI (`npm install -g chattermate-deploy`), documented in the [Quickstart → Self-host](/quickstart#option-b-self-host-with-docker). Both install a `chattermate` command, but they are different tools. ## Installation The CLI installs two commands: `chattermate` (with the alias `cmate`) and [`chattermate-mcp`](/features/mcp-server). Install it from **PyPI** (`chattermate-cli`) or **npm** (`chattermate-cli`, a thin wrapper that runs the Python CLI via `uvx`/`pipx`). ```bash pipx (recommended) theme={null} pipx install chattermate-cli ``` ```bash pip theme={null} pip install chattermate-cli ``` ```bash npm theme={null} npm install -g chattermate-cli ``` ```bash uvx (no install) theme={null} uvx --from chattermate-cli chattermate --help ``` The npm package requires `uv` or `pipx` on your PATH (it launches the Python CLI). Prefer pure Python? Use `pip`/`pipx` directly. Verify the install: ```bash theme={null} chattermate --version ``` ## Pointing at your instance By default the CLI talks to the hosted API at `https://api.chattermate.chat` — no configuration needed. Only set the API URL when targeting a local or self-hosted backend. ```bash theme={null} # Local / self-hosted backend, per-command chattermate --api-url http://localhost:8000 whoami # Or for the whole session export CHATTERMATE_API_URL=http://localhost:8000 ``` The URL resolves in this order: the `--api-url` flag, the `CHATTERMATE_API_URL` environment variable, your saved config, then the default `https://api.chattermate.chat`. ## Authentication You can authenticate two ways. Best for day-to-day terminal use. Stores JWT access + refresh tokens in `~/.chattermate/config.json` (mode `600`) and refreshes them automatically. ```bash theme={null} chattermate login --email you@acme.com # password is prompted securely ``` Best for automation, CI, and AI agents. Long-lived and revocable. Pass it via the `CHATTERMATE_TOKEN` environment variable. ```bash theme={null} export CHATTERMATE_TOKEN=cmat_xxxxxxxxxxxxxxxxxxxx chattermate whoami ``` ### Sign up Create a new organization and admin user without leaving the terminal. Signup emails a **one-time code** to `--admin-email`; supply it with `--otp` or enter it at the prompt: ```bash theme={null} chattermate signup \ --name "Acme Inc" \ --domain acme.com \ --admin-email admin@acme.com \ --admin-name "Ada Admin" # a one-time code is emailed to admin@acme.com — enter it when prompted # admin password is prompted securely ``` You're logged in automatically after signup. Running a **single-org self-hosted** instance (no email delivery)? Add `--community` to create the org directly without OTP verification. ## Personal Access Tokens Personal Access Tokens (PATs) are long-lived, revocable credentials prefixed with `cmat_`. They are the recommended way to authenticate the [MCP server](/features/mcp-server), CI jobs, and any headless automation. A token's secret is shown **only once**, at creation time. Store it somewhere safe — it cannot be retrieved again. ```bash theme={null} chattermate token create laptop-cli # optionally set an expiry: chattermate token create ci --expires-in-days 90 ``` The output includes the `cmat_...` secret and a ready-to-paste [MCP client config](/features/mcp-server#configuration) snippet. ```bash theme={null} chattermate token list ``` Only the non-secret prefix and metadata are shown. ```bash theme={null} chattermate token revoke ``` PATs are also managed through the API at `/api/v1/enterprise/tokens` (`POST` create, `GET` list, `DELETE /{id}` revoke). ## Managing resources Every command supports a `--json` flag for machine-readable output, making the CLI easy to script. ```bash theme={null} # List agents chattermate agent list # Inspect one chattermate agent get # Create an agent (type: customer_support, sales, tech_support, general, custom) chattermate agent create \ --name "Support" \ --type customer_support \ -i "Be concise and friendly" \ -i "Escalate billing questions to a human" # Update instructions / state chattermate agent update -i "New instruction" --inactive ``` ```bash theme={null} # Get the workflow attached to an agent chattermate workflow get # Create a workflow chattermate workflow create --agent-id --name "Onboarding" # Update metadata (status: draft, published, archived) chattermate workflow update --status published # Read or replace nodes & connections chattermate workflow nodes chattermate workflow set-nodes --file nodes.json ``` ```bash theme={null} # Upload local PDF file(s) (optionally attach to an agent) chattermate knowledge add-file ./guide.pdf ./faq.pdf --agent-id # Add website and/or PDF URLs (optionally attach to an agent) chattermate knowledge add-url \ --website https://docs.acme.com \ --pdf-url https://acme.com/guide.pdf \ --agent-id # List sources linked to an agent chattermate knowledge list # Link / unlink an existing source chattermate knowledge link chattermate knowledge unlink # Check ingestion progress chattermate knowledge status ``` ```bash theme={null} # New organizations already use the free ChatterMate model by default. # Switch to your own provider/key at any time: chattermate ai setup --model-type openai --model-name gpt-4o --api-key sk-... # Or (re)apply the free ChatterMate model: chattermate ai setup # Show the current AI configuration chattermate ai show ``` Providers: `chattermate` (free managed), `openai`, `anthropic`, `google`, `groq`, `mistral`, `ollama`, and more. Custom models require a Pro plan. ```bash theme={null} # Create an embeddable widget for an agent — prints the widget id + embed snippet chattermate widget create --agent-id --name "Website widget" # List an agent's widgets (their ids are what you embed) chattermate widget list ``` The widget id is what goes in `window.chattermateId` — see [Widget integration](/features/widget). ```bash theme={null} # Show an agent's lead-capture configuration chattermate lead-capture show # Turn lead capture on and choose which details to collect chattermate lead-capture set --enable --fields email,name,company # Mark extra fields required and require GDPR consent chattermate lead-capture set --required email,company --consent # Turn it off chattermate lead-capture set --disable ``` `set` fetches the current config, applies your flags, and saves the result (custom fields configured in the dashboard are preserved). Email is always collected and required. Lead capture is a **Pro** feature — see [Lead capture](/features/lead-capture). ```bash theme={null} # Show an agent's chat widget appearance chattermate customization show # Colors + design theme chattermate customization set --accent "#7c3aed" --style GLASS # Welcome message, quick actions, and toggles chattermate customization set \ --welcome-title "Hi there!" \ --quick-action "Pricing" --quick-action "Book a demo" \ --collect-email ``` Options include colors (`--accent`, `--background`, `--bubble`, `--text`, `--icon-color`), design theme `--style` (`CHATBOT`, `ASK_ANYTHING`, `GLASS`, `TERMINAL`, `PLAYFUL`, `CALM_MINT`, `AURORA`, `SUNRISE`), `--position` (`FLOATING`/`FIXED`), `--font`, `--custom-css`, welcome title/subtitle/message, `--quick-action`, `--initiation-message`, `--show-citations` and `--collect-email`. Only the options you pass change — the rest keep their current values. See [Chat customization](/features/ai-customization). Text limits: welcome title ≤ 100, subtitle ≤ 250, message ≤ 500, and each initiation nudge ≤ 100 characters (nudges are also clamped to 4 lines in the launcher). ```bash theme={null} # Let the agent hand off to a human, and ask visitors to rate the chat chattermate agent update --transfer-to-human --ask-for-rating # Turn them off chattermate agent update --no-transfer-to-human --no-ask-for-rating ``` ## Command reference | Command | Description | | --------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `chattermate signup` | Create an organization and admin user | | `chattermate login` | Log in and store JWT credentials | | `chattermate logout` | Remove stored credentials | | `chattermate whoami` | Show the authenticated user | | `chattermate token create ` | Create a Personal Access Token | | `chattermate token list` | List your tokens | | `chattermate token revoke ` | Revoke a token | | `chattermate agent list\|get\|create\|update` | Manage AI agents (including `--transfer-to-human` / `--ask-for-rating`) | | `chattermate customization show\|set` | Show/configure an agent's chat widget appearance | | `chattermate workflow get\|create\|update\|nodes\|set-nodes` | Manage workflows | | `chattermate knowledge add-file\|add-url\|list\|link\|unlink\|status` | Manage knowledge sources (local PDFs or URLs) | | `chattermate widget create\|list` | Create/list embeddable widgets and get the widget id to embed | | `chattermate lead-capture show\|set` | Show/configure an agent's lead capture (Pro) | | `chattermate ai setup\|show` | Set/show the org's AI model (defaults to the free ChatterMate model) | ## Configuration & environment | Variable | Purpose | | ------------------------ | ----------------------------------------------------------------------------------------------- | | `CHATTERMATE_API_URL` | API base URL (default `https://api.chattermate.chat`; set to `http://localhost:8000` for local) | | `CHATTERMATE_TOKEN` | A Personal Access Token (`cmat_...`) for non-interactive auth | | `CHATTERMATE_CONFIG_DIR` | Override the config directory (default `~/.chattermate`) | Credentials and the saved API URL live in `~/.chattermate/config.json` (written with `600` permissions). ## Next steps Let AI agents configure ChatterMate through the Model Context Protocol. Learn how ChatterMate handles users, sessions, and tokens. # File Attachments Source: https://docs.chattermate.chat/features/file-attachments Let customers share images, documents, and files in ChatterMate chats by enabling secure uploads per agent with configurable file types, sizes, and storage. # File Attachments Allow customers to share files directly in chat conversations. ChatterMate supports secure file uploads with configurable file types, size limits, and storage options. ## Enabling File Attachments File attachments are configured per agent. To enable: Go to your agent configuration in the ChatterMate dashboard. Click on the **Advanced** tab in agent settings. Toggle **Allow Attachments** to enable file uploads for this agent. Optionally restrict which file types are allowed. ## Supported File Types **Supported formats:** * JPEG / JPG * PNG * GIF * WebP **Maximum size:** 5MB per file **Supported formats:** * PDF * Microsoft Word (.doc, .docx) * Microsoft Excel (.xls, .xlsx) * Plain Text (.txt) * CSV (.csv) **Maximum size:** 10MB per file ### File Type Reference | Category | Extensions | MIME Types | Max Size | | -------- | ------------------------------ | ------------------------------------------------------------------------------------------- | -------- | | Images | .jpg, .jpeg, .png, .gif, .webp | image/jpeg, image/png, image/gif, image/webp | 5MB | | PDF | .pdf | application/pdf | 10MB | | Word | .doc, .docx | application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document | 10MB | | Excel | .xls, .xlsx | application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | 10MB | | Text | .txt, .csv | text/plain, text/csv | 10MB | SVG files are intentionally excluded from supported types due to potential XSS (Cross-Site Scripting) security vulnerabilities. ## Security Features ChatterMate implements multiple layers of security for file uploads: Files are validated by their binary signature (magic bytes), not just MIME type or extension. This prevents file type spoofing. Strict file size limits are enforced server-side to prevent abuse and ensure system stability. Configure allowed file types per agent to only accept what you need. File downloads use temporary signed URLs that expire, preventing unauthorized access. ### How Magic Byte Validation Works Unlike simple MIME type checking, magic byte validation reads the actual file header to verify its true type: ``` JPEG: Starts with FF D8 FF PNG: Starts with 89 50 4E 47 PDF: Starts with 25 50 44 46 (%PDF) ``` This prevents attackers from renaming malicious files with safe extensions. ## Storage Configuration ### AWS S3 (Production) For production deployments, files are stored in AWS S3: ```bash theme={null} # Environment variables for S3 storage AWS_ACCESS_KEY_ID=your_access_key AWS_SECRET_ACCESS_KEY=your_secret_key AWS_S3_BUCKET=your-bucket-name AWS_REGION=us-east-1 ``` **Storage path structure:** ``` uploads/chat_attachments/{org_id}/{unique_filename} ``` ### Local Storage (Development) For local development, files are stored on the filesystem: ```bash theme={null} # Files stored in backend/uploads/chat_attachments/{org_id}/{unique_filename} ``` Local storage is intended for development only. Use S3 or compatible object storage for production deployments. ## Agent Configuration ### Enable All Attachments ```json theme={null} { "allow_attachments": true } ``` ### Restrict to Specific Types Limit uploads to specific categories: ```json Images Only theme={null} { "allow_attachments": true, "allowed_attachment_types": ["images"] } ``` ```json Documents Only theme={null} { "allow_attachments": true, "allowed_attachment_types": ["documents"] } ``` ```json Images and PDFs theme={null} { "allow_attachments": true, "allowed_attachment_types": ["images", "pdf"] } ``` ## User Experience ### Upload Flow When file attachments are enabled, users can: 1. Click the attachment icon in the chat input 2. Select files from their device 3. Preview images before sending 4. See upload progress indicator 5. View attached files in chat history ### Chat Interface Images display as inline previews in the chat with click-to-expand functionality. Documents appear as downloadable links with file name and size displayed. ## Best Practices 1. **Enable Only What You Need** * If you only need image uploads, restrict to images only * Reduces potential attack surface * Improves user experience with focused UI 2. **Monitor Storage Usage** * Track file storage consumption * Set up alerts for unusual upload patterns * Implement retention policies for old files 3. **Consider File Processing** * Large files may impact chat performance * Consider async processing for document analysis * Compress images when possible 4. **Inform Users** * Display accepted file types in the UI * Show clear error messages for rejected files * Indicate file size limits ## Troubleshooting * Verify the file extension matches the actual file type * Check if the file type is in the allowed list * Ensure the file hasn't been renamed with a different extension * Try re-exporting the file from its source application * Check file size against limits (5MB images, 10MB documents) * Compress images before uploading * Split large documents into smaller parts * Verify S3 credentials are configured correctly * Check S3 bucket permissions * Ensure CORS is configured on your S3 bucket * Review backend logs for storage errors * Signed URLs may have expired (refresh the chat) * Check S3 bucket access policies * Verify the file wasn't deleted from storage ## What's Next? After enabling file attachments: 1. Test upload functionality with various file types 2. Configure file type restrictions as needed 3. Set up S3 storage for production Learn about deploying and customizing widget apps # Human Agents Source: https://docs.chattermate.chat/features/human-agents Manage human agents in ChatterMate by adding users, assigning roles, organizing teams into groups, and routing chats so people and AI handle support together. # Human Agents Management Configure and manage human agents to provide seamless customer support alongside AI agents. Human Agents Dashboard ## User Management ### Adding Users 1. Click "+Add User" in the Users tab 2. Fill in user details: * Full Name * Email Address * Role Selection * Active Status * Password (for new users) ### Password Security * Minimum 8 characters required * Must include uppercase and lowercase letters * Must include numbers and special characters * Real-time password strength indicator * Secure password validation ### User Status Options * Active: Full system access enabled * Inactive: Access temporarily suspended * Status can be changed anytime ## Groups Management ### Creating Support Groups 1. Navigate to Groups tab 2. Click "+Add Group" 3. Set group name and description 4. Configure group settings ### Group Features Customize group settings and details Control group membership ### Member Management * Add or remove group members * View member information * Manage member roles * Track member status Next: Learn how to manage roles and permissions # Jira Integration Source: https://docs.chattermate.chat/features/jira-integration Connect ChatterMate with Jira so AI agents create and update tickets from customer chats and answer status inquiries, streamlining issue tracking and support. # Jira Integration Integrate ChatterMate with Jira to enable AI-based ticket management and status inquiries. Let your AI agents create and update tickets based on customer issues to seamlessly track and resolve support requests. Jira Integration Dashboard ## Integration Benefits AI agents automatically create and update Jira tickets based on customer conversations Customers can ask about ticket status and receive immediate updates from AI agents ## Seamless Integration ChatterMate connects to Jira using OAuth authentication, providing a secure and straightforward setup process: 1. Navigate to the Integrations page in ChatterMate 2. Select Jira from the available integrations 3. Click the "+ Connect" button 4. Authorize the connection using Jira OAuth Only Jira OAuth authentication is required. No complex configuration or webhook setup needed. ## Agent-Specific Configuration Each AI or human agent can be configured with specific Jira integration settings: Agent-specific Jira Configuration ### Ticket Creation Triggers Configure when tickets should be automatically created in Jira: * Issues without immediate resolution * No transfer agent available * Transfer requests not attended * Customer follow-ups * Complex issues requiring tracking You can enable or disable automatic ticket creation for each agent individually, allowing for specialized handling based on agent roles and responsibilities. ## Ticket Creation ### AI-Powered Ticket Creation AI agents can automatically: * Detect when a customer issue requires tracking * Create appropriate Jira tickets with relevant details * Update customers on ticket status * Add conversation context to ticket descriptions ### One-Click Ticket Creation for Human Agents Human agents can create Jira tickets with a single click: Create Jira Ticket Dialog The ticket creation dialog allows agents to: * Select the appropriate project * Choose the issue type * Set priority * Add a summary and description * Include conversation context automatically ## Ticket Customization ### Project Selection Choose which Jira project tickets should be created in based on: * Customer issue type * Support department * Agent specialization ### Issue Type Configuration Map ChatterMate conversation categories to appropriate Jira issue types: * Bug reports * Feature requests * Support inquiries * Account issues ### Priority Setting Set ticket priority based on: * Customer status * Issue urgency * Business impact * Resolution timeframe ## Customer Experience Customers benefit from the integration through: * **Transparent Tracking**: Receive ticket IDs and status updates directly in the conversation * **Status Inquiries**: Ask about ticket status at any time and receive immediate responses * **Seamless Handoffs**: Transition between AI and human agents while maintaining ticket context * **Consistent Updates**: Receive notifications as their issue progresses through resolution stages # Knowledge Base Source: https://docs.chattermate.chat/features/knowledge-base Train ChatterMate AI agents on your own content — crawl websites and sitemaps, upload PDFs, or paste text — then review, edit and re-embed every indexed page. # Knowledge Base Train your AI agents on your own content so they answer accurately and in context. ChatterMate crawls websites and sitemaps, ingests PDFs and pasted text, and lets you review, edit, and re-embed every page it learned from. Knowledge explorer — sources on the left, extracted page content on the right ## Where to manage knowledge There are two places to work with knowledge, both backed by the same content: The sources a single agent learns from. Add, review, and edit the content that grounds that agent's answers. A dedicated page (in the main menu) to manage every source across your whole organization, with plan-usage meters. The layout is a **master–detail explorer**: sources (and their crawled sub-pages) on the left, the selected page's extracted content on the right. ## Adding a source Click **Add source** to open the source picker, choose a type, and configure it. Crawling happens in the background — you'll be notified when indexing finishes. Add knowledge source dialog with Website, Sitemap, Document and Plain text options A single page or a whole site. Choose the **crawl scope**: *This page only*, or *Follow links on this domain* to discover and queue linked pages. Point at a `sitemap.xml` and ChatterMate indexes every page it lists (including `sitemap-index` files) as one source. Upload a PDF (up to 25 MB). Text is extracted, split into sections, and indexed; scanned PDFs are run through OCR. Paste a title and content directly. Indexed immediately — no crawling needed. Each website, sitemap, PDF, or text entry counts as **one knowledge source**. The number of pages a crawl stores per source is capped by your plan's sub-pages limit. ## Reviewing and editing pages Expand a source to see its crawled **sub-pages**, then select one to read exactly what the AI learned from it. Fix or refine a page's extracted text. Saving re-embeds it immediately, so answers stay current. Manually add a page to a source with a title, content, and an optional source URL — useful for content a crawler can't reach. Remove an individual page or an entire source from the knowledge base. Jump to the original page URL to compare against the live content. ## Source status Each source shows its live status while it is being indexed: Queued for crawling. It appears in the list immediately and updates as work starts. Pages are being fetched, extracted, and embedded. Progress updates as each page completes. Successfully indexed and available to the agent. Something prevented indexing. The source shows the reason so you can act on it. **Bot-protected sites.** If a site's bot protection (e.g. a Cloudflare / WordPress.com "Checking your browser" page) blocks automated crawling, the source fails with a clear message asking you to add the content manually — upload a PDF or paste the text instead. ## Sharing knowledge between agents A source can ground more than one agent. From the dedicated Knowledge base page you manage every source in one place, and the same source can be linked to multiple agents. ### Benefits * Maintain consistency across different agent types * Avoid duplicate content and processing * Central management — updates propagate to every linked agent ### Use cases * Company policies shared across all agents * Product docs shared by sales and support * Technical specs for multiple specialist agents When you edit a page, it is re-embedded and every agent that uses that source immediately benefits — no manual reprocessing needed. ## Notifications When Firebase Cloud Messaging is enabled, ChatterMate notifies you when a source finishes processing: ```json Success theme={null} { "title": "Knowledge Processing Complete", "body": "Your knowledge source '[name]' has been successfully processed", "type": "knowledge_processed" } ``` ```json Error theme={null} { "title": "Knowledge Processing Failed", "body": "Failed to process '[name]'. Click for details", "type": "knowledge_failed" } ``` ## Best practices 1. **Prefer a sitemap** when a site has one — it indexes exactly the pages you want, without following stray links. 2. **Use crawl scope** — pick *This page only* for a single article, *Follow links* to capture a whole docs section. 3. **Review after indexing** — open a few pages to confirm the extracted text is clean; edit anything that isn't. 4. **Fill gaps manually** — paste content or add a sub-page for anything a crawler can't reach (paywalled, gated, or bot-protected pages). 5. **Keep it current** — edit pages when your product changes; re-embedding is instant. ## Limitations * PDF size limit: 25 MB per file * Pages crawled per source are capped by your plan's sub-pages limit * URLs must be publicly reachable and return extractable text (no scanned-only content without OCR) * Sites behind strict bot protection may not be crawlable — add that content manually ## What's Next? After adding knowledge sources: 1. Test AI responses with the new knowledge 2. Review and edit extracted pages for accuracy 3. Keep content up to date as your product evolves Next: Learn how to test your AI agent's knowledge # Lead Capture Source: https://docs.chattermate.chat/features/lead-capture Let your AI agents collect and qualify visitor contact details naturally in conversation, then manage every lead and customer from the People page. # Lead Capture Lead Capture lets your AI agent collect a visitor's contact details **in the flow of conversation** — no forms. The agent helps first, then asks for details at a natural moment, qualifies the lead with an AI-written summary, and everyone captured shows up on the **People** page. Lead Capture and the People page are a **Pro** feature. On the Free and Base plans the tab and page are locked with an upgrade prompt. ## How it works When enabled for an agent, Lead Capture behaves like transfer-to-human — a prompt-driven capability the agent decides when to use: 1. **Help first.** The agent answers the visitor's question and delivers value. 2. **Ask naturally.** At a good moment (usually right after being helpful) it asks for the details you configured — one at a time, never on the first message. 3. **Validate & consent.** It only accepts a properly formatted email, and — when consent is required — asks for a clear "yes" before recording (GDPR). 4. **Record & qualify.** The lead is saved with the captured fields and a short AI qualification summary, and the person is promoted from *Visitor* to *Lead*. ## Configuring an agent Open an agent → **Lead Capture** tab: * **Enable lead capture** — the master toggle. * **What to collect** — pick the standard fields (email, name, company, phone) and add your own custom fields (with optional allowed values). Tap the **optional / required** pill on any field to control whether the agent insists on it before recording. Email is always required. * **Require consent (GDPR)** — the agent must get an explicit "yes" before recording. Recommended. * **Guidance** — optional freeform steer for *when* and *how* the agent asks (e.g. "be more proactive on the pricing page"). Routing (assign-to / CRM sync / Slack) is shown as **Coming soon** — the config is saved for a future release but nothing is sent anywhere yet. ## The People page **People** in the sidebar is an org-wide view of everyone your agents have touched: * **KPI strip** — total people, new leads (7d), customers. * **Stage tabs** — All / Visitors / Leads / Customers. * **Search** — by name, email or company. * **Detail drawer** — captured attributes, the AI qualification summary, the page a lead converted on, conversation history, and a **Mark as customer** action. If a returning visitor gives an email that already belongs to another person, the two profiles are automatically **merged** into one — history, sessions and captured details are combined, so you never see duplicate leads. ## Configure from the CLI You can also configure lead capture with the [ChatterMate CLI](/features/cli): ```bash theme={null} # Turn it on and choose which details to collect chattermate lead-capture set --enable --fields email,name,company # Mark extra fields required and require consent chattermate lead-capture set --required email,company --consent # Show the current configuration chattermate lead-capture show ``` ## Lifecycle stages Anyone who has chatted but not shared qualifying details yet. Set automatically once the agent records a qualifying capture (valid email + consent). A manual promotion from the People detail drawer when a lead converts. # MCP Server Source: https://docs.chattermate.chat/features/mcp-server Let AI agents manage ChatterMate through the Model Context Protocol by connecting the MCP server to Claude, IDE assistants, or any MCP-compatible client. # ChatterMate MCP Server The ChatterMate MCP server (`chattermate-mcp`) exposes your ChatterMate instance to AI agents through the [Model Context Protocol](https://modelcontextprotocol.io). Connect it to Claude, an IDE assistant, or any MCP-compatible client and the agent can read and manage your agents, workflows, and knowledge sources on your behalf. **This is the inverse of [MCP Tools](/features/mcp-tools).** *MCP Tools* let your ChatterMate agents **call out** to external services. The *MCP Server* described here lets an external AI agent **call in** to ChatterMate to configure it. ## How it works The server is a thin, stdio-based bridge over the ChatterMate API. It ships in the same `chattermate-cli` package as the [CLI](/features/cli) and is authenticated with a [Personal Access Token](/features/cli#personal-access-tokens). Launched by your MCP client as a subprocess — the standard way agents run local MCP servers. Uses a `cmat_` Personal Access Token from the `CHATTERMATE_TOKEN` environment variable. Every action runs as the token's owner, limited to that user's organization and permissions. ## Prerequisites The server runs via `uvx` (no install) or after `pipx install chattermate-cli`. See the [CLI installation guide](/features/cli#installation). ```bash theme={null} chattermate token create my-agent ``` Copy the `cmat_...` secret — it's shown only once. ## Configuration Add the server to your MCP client's configuration, supplying your personal access token via `CHATTERMATE_TOKEN`. The server targets the hosted API (`https://api.chattermate.chat`) by default, so no API URL is needed. Running `chattermate token create` prints this exact snippet for you. ```json Claude Desktop / generic theme={null} { "mcpServers": { "chattermate": { "command": "uvx", "args": ["--from", "chattermate-cli", "chattermate-mcp"], "env": { "CHATTERMATE_TOKEN": "cmat_xxxxxxxxxxxxxxxxxxxx" } } } } ``` ```bash Claude Code (CLI) theme={null} claude mcp add chattermate \ --env CHATTERMATE_TOKEN=cmat_xxxxxxxxxxxxxxxxxxxx \ -- uvx --from chattermate-cli chattermate-mcp ``` If you installed with `pipx`, you can use the `chattermate-mcp` command directly instead of `uvx`: ```json theme={null} { "mcpServers": { "chattermate": { "command": "chattermate-mcp", "env": { "CHATTERMATE_TOKEN": "cmat_xxxxxxxxxxxxxxxxxxxx" } } } } ``` Targeting a local or self-hosted backend? Add `"CHATTERMATE_API_URL": "http://localhost:8000"` to the `env` block. ## Available tools The server exposes the following tools. Read-only tools are safe to run freely; mutating tools create or change configuration. | Tool | Description | | ---------------------- | ------------------------------------------------------------- | | `whoami` | Return the authenticated user (id, email, organization, role) | | `list_agents` | List all agents in the organization | | `get_agent` | Get a single agent by id | | `get_workflow` | Get the workflow attached to an agent | | `get_workflow_nodes` | Get all nodes and connections for a workflow | | `list_knowledge` | List knowledge sources linked to an agent | | `get_ingestion_status` | Check the status of a knowledge ingestion job | | Tool | Description | | ----------------------- | ----------------------------------------------------- | | `create_agent` | Create an AI agent | | `update_agent` | Update an agent's instructions, name, or active state | | `create_workflow` | Create a workflow for an agent | | `update_workflow` | Update a workflow's metadata | | `update_workflow_nodes` | Replace a workflow's nodes/connections | | `add_knowledge_url` | Add website/PDF URLs to the knowledge base | | `link_knowledge` | Link a knowledge source to an agent | | `unlink_knowledge` | Unlink a knowledge source from an agent | ## Example prompts Once connected, you can ask your AI agent things like: * *"List my ChatterMate agents and tell me which ones have no workflow."* * *"Create a customer\_support agent named 'Billing Bot' with instructions to handle refunds and escalate disputes to a human."* * *"Add [https://docs.acme.com](https://docs.acme.com) to the Billing Bot's knowledge base and tell me when ingestion finishes."* * *"Create an 'Onboarding' workflow for agent \ and publish it."* The agent translates these into the appropriate tool calls. ## Security A Personal Access Token grants the agent the same permissions as its owner. Treat it like a password. * Scope risk by creating a **dedicated token per agent/integration** and setting an expiry with `--expires-in-days`. * **Revoke** a token at any time with `chattermate token revoke ` (or from the API); the server stops working immediately. * The server never stores your token — it reads it from the environment on each run. ## Next steps Manage tokens and resources from your terminal. The reverse direction — give your ChatterMate agents external tools. # MCP Tools Source: https://docs.chattermate.chat/features/mcp-tools Extend ChatterMate AI agents with external tools via the Model Context Protocol (MCP), connecting file systems, APIs, and databases to act beyond text replies. # MCP Tools Enhance your AI agents with powerful external tools and services using the Model Context Protocol (MCP). Connect to file systems, APIs, databases, and more to extend your agent's capabilities beyond text-based responses. MCP Tools Dashboard ## What are MCP Tools? The Model Context Protocol (MCP) is a standardized way to connect AI agents to external tools and services. MCP tools enable your AI agents to: Read, write, and manage files and directories Connect to external APIs and web services Query and interact with databases Manage version control repositories Search the internet for real-time information Access weather and environmental data ## Transport Types MCP tools support three different transport protocols for communication: * **Best for**: Local command-line tools and scripts * **Communication**: Process spawning with stdin/stdout * **Use cases**: File system access, local Git operations, CLI tools * **Configuration**: Command and arguments * **Best for**: Real-time streaming applications * **Communication**: HTTP with server-sent events * **Use cases**: Live data feeds, monitoring services * **Configuration**: URL, headers, and timeout settings * **Best for**: Traditional REST APIs and web services * **Communication**: Request/response over HTTP * **Use cases**: API integrations, web services * **Configuration**: URL, headers, and connection settings ## Managing MCP Tools ### Adding MCP Tools ChatterMate provides two ways to add MCP tools to your agents: Configure new MCP servers from scratch or use presets Connect to MCP tools already configured in your organization ### Tool Sharing MCP tools can be shared across multiple agents within your organization: * **Organization-wide**: Tools created by any team member are available to all agents * **Reusable Configuration**: Set up once, use across multiple agents * **Centralized Management**: Update tool configuration in one place * **Access Control**: Only organization members can access shared tools ### Use Cases for Tool Sharing * Common API integrations across support and sales agents * Shared file system access for documentation * Organization-wide weather or search capabilities * Centralized database connections When you update a shared MCP tool configuration, all agents using that tool will automatically use the updated settings. ## Popular MCP Tool Presets ChatterMate includes pre-configured templates for common use cases: ### File System Access ```json theme={null} { "name": "File System", "description": "Access and manage files and directories", "transport_type": "stdio", "command": "uvx", "args": ["@modelcontextprotocol/server-filesystem"], "env_vars": { "ALLOWED_DIRECTORIES": "/path/to/allowed/directory" } } ``` ### Git Repository Management ```json theme={null} { "name": "Git Repository", "description": "Interact with Git repositories", "transport_type": "stdio", "command": "uvx", "args": ["@modelcontextprotocol/server-git"], "env_vars": {} } ``` ### Web Search Integration ```json theme={null} { "name": "Web Search", "description": "Search the web using Brave Search API", "transport_type": "stdio", "command": "uvx", "args": ["@modelcontextprotocol/server-brave-search"], "env_vars": { "BRAVE_API_KEY": "your-api-key" } } ``` ### Weather Information ```json theme={null} { "name": "Weather", "description": "Get weather information", "transport_type": "stdio", "command": "uvx", "args": ["@modelcontextprotocol/server-weather"], "env_vars": { "WEATHER_API_KEY": "your-api-key" } } ``` ## Configuration Guide ### STDIO Transport Configuration For command-line tools and local services: #### Required Fields * **Command**: The executable command (e.g., `npx`, `uvx`, `node`) * **Args**: Array of command arguments #### Optional Fields * **Environment Variables**: Key-value pairs for environment configuration * **Working Directory**: Set the working directory for the process #### Example Configuration ```json theme={null} { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"], "env_vars": { "ALLOWED_DIRECTORIES": "/home/user/documents,/home/user/projects", "READONLY": "false" } } ``` ### SSE Transport Configuration For server-sent events and streaming data: #### Required Fields * **URL**: The SSE endpoint URL #### Optional Fields * **Headers**: HTTP headers for authentication or configuration * **SSE Read Timeout**: Maximum time to wait for events (default: 60 seconds) * **Timeout**: Connection timeout (default: 30 seconds) #### Example Configuration ```json theme={null} { "url": "https://api.example.com/sse/events", "headers": { "Authorization": "Bearer your-token", "Accept": "text/event-stream" }, "sse_read_timeout": 120, "timeout": 45 } ``` ### HTTP Transport Configuration For REST APIs and web services: #### Required Fields * **URL**: The API base URL #### Optional Fields * **Headers**: HTTP headers for authentication or content type * **Timeout**: Request timeout (default: 30 seconds) * **Terminate on Close**: Whether to terminate the connection when the chat session ends #### Example Configuration ```json theme={null} { "url": "https://api.example.com", "headers": { "Authorization": "Bearer your-api-key", "Content-Type": "application/json" }, "timeout": 60, "terminate_on_close": true } ``` ## Security Considerations ### Environment Variables * Store sensitive data like API keys in environment variables * Never hardcode credentials in configuration * Use secure key management practices ### Access Control * Limit file system access to specific directories * Use read-only permissions when possible * Validate API endpoints and permissions ### Network Security * Use HTTPS for all external connections * Validate SSL certificates * Configure appropriate timeouts MCP tools run with the same permissions as your application. Always validate tool configurations and limit access to sensitive resources. ## Tool Status Management ### Tool States * Tool is active and available to the agent * Will be loaded when the agent starts * Can be used in conversations * Tool configuration is saved but not active * Will not be loaded by the agent * Can be re-enabled without reconfiguration * Tool failed to initialize or connect * Check configuration and credentials * Review logs for detailed error information ### Troubleshooting Common issues and solutions: 1. **Connection Timeouts** * Increase timeout values in configuration * Check network connectivity * Verify service availability 2. **Authentication Errors** * Validate API keys and credentials * Check header configuration * Ensure proper permissions 3. **Command Not Found (STDIO)** * Verify command is installed and in PATH * Check argument syntax * Test command manually ## Best Practices ### Tool Configuration 1. **Use Environment Variables** for sensitive data 2. **Test Locally** before deploying to agents 3. **Set Appropriate Timeouts** to prevent hanging 4. **Document Tool Purpose** in descriptions 5. **Use Descriptive Names** for easy identification ### Performance Optimization 1. **Enable Only Needed Tools** to reduce startup time 2. **Configure Reasonable Timeouts** to prevent delays 3. **Monitor Tool Usage** and performance 4. **Cache Results** when possible ### Security Guidelines 1. **Principle of Least Privilege** - grant minimal necessary access 2. **Regular Credential Rotation** for API keys 3. **Audit Tool Access** and usage patterns 4. **Secure Configuration Storage** for sensitive settings ## Monitoring and Debugging ### Tool Logs * Access tool execution logs through the dashboard * Monitor connection status and errors * Track tool usage and performance metrics ### Debug Mode * Enable verbose logging for troubleshooting * Test tool connections independently * Validate configuration parameters ### Performance Metrics * Track tool response times * Monitor success/failure rates * Analyze usage patterns ## Limitations * Maximum 10 MCP tools per agent * STDIO tools require server-side command availability * Network-based tools depend on external service reliability * Some tools may require specific software dependencies * Tool execution timeout maximum: 300 seconds ## Integration Examples ### Customer Support with File Access ```json theme={null} { "name": "Support Documents", "description": "Access customer support documentation", "transport_type": "stdio", "command": "uvx", "args": ["@modelcontextprotocol/server-filesystem"], "env_vars": { "ALLOWED_DIRECTORIES": "/var/www/support-docs", "READONLY": "true" } } ``` ### Sales Agent with CRM Integration ```json theme={null} { "name": "CRM API", "description": "Customer relationship management integration", "transport_type": "http", "url": "https://api.salesforce.com", "headers": { "Authorization": "Bearer sf_token", "Content-Type": "application/json" } } ``` ### Technical Support with Git Access ```json theme={null} { "name": "Code Repository", "description": "Access to technical documentation repository", "transport_type": "stdio", "command": "uvx", "args": ["@modelcontextprotocol/server-git"], "env_vars": { "GIT_REPO_PATH": "/opt/repositories/tech-docs" } } ``` ## What's Next? After configuring MCP tools: 1. Test tool functionality with your agent 2. Monitor tool performance and usage 3. Configure additional tools as needed 4. Review security and access permissions Next: Learn how to test your agent with MCP tools Back: Configure your AI agent settings # Setup Organization Source: https://docs.chattermate.chat/features/organization Set up your organization in ChatterMate by configuring your organization name, primary domain, and core workspace settings to get AI support ready in minutes. # Organization Setup Setting up your organization is the first step in getting started with ChatterMate. This guide will walk you through each field in the setup process. Organization Setup Form ## Organization Details ### Organization Name The name of your company or organization that will be displayed to your customers and agents. * Example: "Acme Corporation" * This will appear in the chat widget and dashboard * Can be changed later in organization settings ### Domain Your organization's primary domain name. This is used for: * Validating widget installations * Email communications * Whitelisting API access * Example: "acme.com" ### Timezone Your organization's primary timezone that will be used for: * Scheduling business hours * Reporting and analytics * Agent shift management * Displayed in (GMT±XX:XX) format with city name ## Business Hours Configure when your organization is available for customer support: * Toggle switches for each day of the week * Set specific hours for each working day * Default working hours: 09:00 to 17:00 * Outside these hours: * AI agent continues to operate * Human chat requests are queued * Customers receive after-hours notifications ### AI Agent Behavior Outside Business Hours When human handoff is enabled in your AI agent configuration: * During business hours: AI agent will transfer chats to human agents when needed * Outside business hours: * AI agent will NOT transfer chats to human agents * Instead, it will inform customers that human support is unavailable * Provides a message like "Our support team is currently offline. We've noted your request and will get back to you when we return tomorrow at \[business hours start time]" * Continues to provide automated support within its capabilities * Logs all conversation details for human review during business hours ### Working Days * Monday through Friday enabled by default * Saturday and Sunday disabled by default * Each day can be individually toggled ### Working Hours * Set custom start and end times for each day * 24-hour format (HH:MM) * Can be different for each day of the week ## Administrator Account ### Admin Name * Full name of the primary administrator * Will be displayed in the dashboard and communications * Example: "John Smith" ### Admin Email * Primary contact email for the administrator * Used for: * Login credentials * System notifications * Security alerts * Example: "[admin@yourdomain.com](mailto:admin@yourdomain.com)" ### Admin Password * Secure password for the administrator account * Requirements: * Minimum 8 characters * At least one uppercase letter * At least one number * At least one special character ### Confirm Password * Re-enter the password to prevent typos * Must match exactly with the admin password ## What Happens Next? After creating your organization: 1. You'll receive a confirmation email 2. You'll be logged into the admin dashboard 3. You can start configuring your AI provider 4. You can invite additional team members 5. You can customize your chat widget ## Security Notes * All passwords are securely hashed ## Best Practices * Use a business email domain that matches your organization domain * Set realistic business hours that you can maintain * Choose a strong, unique password * Save your login credentials securely * Review and update timezone settings if you have a global team # Roles & Permissions Source: https://docs.chattermate.chat/features/roles Manage role-based access control in ChatterMate by assigning Admin and Agent roles and tuning the permissions that control what each team member can see and do. # Roles & Permissions Configure access control and manage user permissions through role-based authentication. Roles and Permissions Dashboard ## Role Types ### Default Roles Complete system access and management capabilities Chat and assigned features access ### Custom Roles Create specialized roles with: * Custom permission sets * Specific access levels * Department-based permissions * Feature-based restrictions ## Permission Categories ### View Permissions * View agent information * Access analytics dashboard * View assigned conversations * Read knowledge base * User administration * Role configuration * Agent management * Chat assignment control * Organization settings * Subscription management * System configuration * Advanced features ## Role Features ### Role Creation 1. Custom role naming 2. Permission selection 3. Access level definition 4. Feature restrictions ### Role Management * Edit existing roles * Update permissions * Modify access levels * Track role changes ### Role Assignment * Assign to users * Bulk role updates * Role inheritance * Access control Next: Learn how to manage customer conversations # Testing AI Agent Source: https://docs.chattermate.chat/features/testing Test your ChatterMate AI agent in a simulated chat before going live to verify responses, customer identification, and behavior, catching issues pre-production. # Testing AI Agent Test your AI agents in a simulated environment to ensure they provide accurate and appropriate responses before deploying to production. AI Agent Testing Interface ## Customer Identification ### Email Collection * Email is required before starting a chat * Automatically identifies returning customers * Loads previous conversation history * Maintains context across sessions ## Testing Features ### Conversation Testing * Test standard greetings and responses * Verify tone and communication style * Check response formatting * Test multi-turn conversations * Test queries against added knowledge * Verify accurate information recall * Check context maintenance * Test complex multi-topic queries * Test automatic transfer triggers * Verify after-hours behavior * Check transfer messages * Test manual transfer requests ## Test Scenarios ### Customer Context 1. **New Customer** * First-time interaction * No previous history * Basic profile creation 2. **Returning Customer** * Previous history loaded * Context from past interactions * Personalized responses ### Common Test Cases Test product knowledge and pricing responses Verify troubleshooting capabilities Test account-related responses Multi-step problem resolution ## Chat History ### History Features * Complete conversation logs * Timestamp for each interaction * Session summaries * Action tracking (transfers, resolutions) ### History Usage * Context for personalized responses * Issue tracking and follow-up * Training data for improvements * Quality assurance reviews Chat history is automatically associated with the customer's email address, allowing for seamless continuation of conversations across multiple sessions. ## Testing Best Practices 1. **Systematic Testing** * Start with basic queries * Progress to complex scenarios * Test edge cases * Verify error handling 2. **Knowledge Testing** * Test recently added content * Verify cross-document knowledge * Check information accuracy * Test knowledge updates 3. **Customer Experience** * Verify response times * Check message formatting * Test file attachments * Validate email notifications ## Test Environment ### Features Available * Real-time chat interface * Knowledge base access * History simulation * Transfer scenarios ### Testing Tools * Chat widget preview * Response analysis * Performance metrics * Error logging Test thoroughly in the staging environment before deploying changes to production. This includes testing with different customer profiles and various conversation scenarios. ## What's Next? After testing your AI agent: 1. Review test results 2. Make necessary adjustments 3. Update knowledge if needed 4. Deploy to production Next: Learn how to integrate the chat widget into your website # Widget Integration Source: https://docs.chattermate.chat/features/widget Add the ChatterMate AI chat widget to any website in minutes with a one-line script snippet or iframe embed, with no code changes beyond pasting the snippet. # Widget Integration Add the ChatterMate chat widget to your website using either direct script integration or iframe embedding. Widget Integration Options ## Integration Methods ### 1. Script Integration (Recommended) Add the following code snippet to your website's HTML, just before the closing `` tag: ```html theme={null} ``` Replace `YOUR_WIDGET_ID` with your unique widget identifier from the ChatterMate dashboard. ### 2. IFrame Integration Alternatively, embed the chat widget using an iframe: ```html theme={null} ``` The iframe method is useful for testing or when you need more control over the widget's placement and dimensions. ## Widget Configuration ### Customization ```javascript theme={null} // Update chat bubble color window.postMessage({ type: 'CUSTOMIZATION_UPDATE', data: { chat_bubble_color: '#f34611' // Your brand color } }, '*'); ``` ### Widget Position By default the launcher sits 20px from the bottom-right corner. To move it — for example, to clear a fixed bottom navigation bar — initialize the widget with `ChatterMate.init()` and pass a `position`. Both values are in pixels, measured from the bottom and right edges of the screen. The chat window stays anchored above the launcher, and the offset applies on mobile too. ```html theme={null} ``` You can also reposition the widget at any time after it has loaded — useful when your layout changes, such as a bottom bar appearing: ```javascript theme={null} ChatterMate.setPosition({ bottom: 100, right: 24 }); ``` `position` and `setPosition()` accept `bottom` and `right` in pixels. On mobile the chat window opens full-screen, so the offset controls where the closed launcher button sits — handy for keeping it clear of a bottom navigation bar. ### Mobile Responsiveness The widget automatically adapts to different screen sizes: ```css Desktop theme={null} width: 400px; height: 600px; border-radius: 24px; ``` ```css Mobile theme={null} width: 100%; height: 100vh; border-radius: 0; ``` ## Event Handling The widget supports the following events: ### Token Management ```javascript theme={null} // Listen for token updates from the widget window.addEventListener('message', (event) => { if (event.data.type === 'TOKEN_UPDATE') { // Store the token securely const token = event.data.token; localStorage.setItem('ctid', token); } }); ``` ### Scroll Control ```javascript theme={null} // Scroll chat to bottom window.postMessage({ type: 'SCROLL_TO_BOTTOM' }, '*'); ``` ## Security Features * Tokens are encrypted and stored securely * Communication uses postMessage for security * Automatic token management * Domain validation for widget loading ## Widget Features ### Customer Identification * Email collection before chat starts * Automatic returning customer detection * Previous conversation history loading * Context maintenance across sessions ### Chat Interface * Real-time message updates * Typing indicators * Message status tracking * File attachment support * Markdown formatting support * Emoji support ### Styling The widget uses CSS variables for consistent theming: ```css theme={null} :root { --primary-color: #f34611; --background-base: #ffffff; --text-color: #1F2937; --border-color: #E5E7EB; --radius-lg: 24px; --space-md: 16px; --space-sm: 8px; } ``` ## Testing Your Integration ### Test Project We provide a sample test project at `github.com/chattermate/chattermate.chat/tree/main/chattermate-test`: 1. Clone and setup: ```bash theme={null} git clone https://github.com/chattermate/chattermate.chat cd chattermate-test npm install ``` 2. Start test server: ```bash theme={null} npm start ``` 3. Open `http://localhost:3000` and enter your widget ID The test project demonstrates: * Basic widget initialization * Token management * Style customization * Mobile responsiveness ## Best Practices 1. **Implementation** * Add script just before closing body tag * Enable secure token storage * Test on multiple browsers * Verify mobile responsiveness 2. **Security** * Store tokens securely * Use HTTPS only * Implement proper CSP headers * Enable domain restrictions 3. **User Experience** * Test email collection flow * Verify history loading * Check offline behavior * Test connection handling ## Troubleshooting * Verify localStorage access * Check token storage events * Clear stored tokens and retry * Verify domain permissions * Check CSS variables * Verify mobile breakpoints * Test iframe dimensions * Validate color codes * Verify widget ID * Check network connectivity * Test WebSocket connection * Validate API endpoints ## What's Next? After integrating the widget: 1. Test customer identification flow 2. Verify conversation persistence 3. Monitor connection stability 4. Test mobile responsiveness Next: Learn how to manage human agents # Widget Apps Source: https://docs.chattermate.chat/features/widget-apps Create and manage embeddable ChatterMate widget apps for any website or application, customizing appearance, behavior, and functionality to match your brand. # Widget Apps Widget Apps are embeddable chat interfaces that you can add to any website or application. Customize the appearance, behavior, and functionality to match your brand and use case. ## Creating a Widget App Every agent in ChatterMate has an associated widget that can be embedded on your website. Navigate to **Agents** in the dashboard and create a new agent or select an existing one. Click on the **Widget** tab in the agent configuration. Copy the provided code snippet. Paste the code just before the closing `` tag on your website. ## Chat Styles Choose the chat style that best fits your use case: ### Traditional Support Interface The classic customer support chat experience with agent branding. **Features:** * Email collection before chat starts * Agent avatar and name displayed * Formal, business-focused layout * "Powered by ChatterMate" branding * Standard greeting message **Best for:** * Customer support portals * E-commerce websites * Service-based businesses * Help desk interfaces ### Modern AI Assistant Interface A clean, conversation-focused interface perfect for AI assistants. **Features:** * No email required to start chatting * Customizable welcome title and subtitle * Larger, prominent design * Anonymous conversation support * Modern, AI-focused aesthetics **Best for:** * Documentation assistants * Knowledge base Q\&A * General-purpose AI helpers * Product exploration tools The "Ask Anything" style automatically creates anonymous customer sessions. Users can optionally provide their email later in the conversation. ## Integration Methods Simple, lightweight integration with a single script tag. Automatically handles updates and optimizations. Embed as an iframe for more control over placement and dimensions. Useful for specific layout requirements. ### Script Integration Add this code before your closing `` tag: ```html theme={null} ``` ### iFrame Integration For iframe embedding: ```html theme={null} ``` ## Customization Options ### Visual Customization Customize your widget's appearance in the **Chat Customization** tab: | Option | Description | | --------------------- | ----------------------------------------- | | **Background Color** | Main background of the chat interface | | **Chat Bubble Color** | Color of message bubbles | | **Accent Color** | Buttons, links, and interactive elements | | **Font Family** | Typography (Inter, system-ui, sans-serif) | ### Welcome Messages (Ask Anything Style) | Field | Description | Max Length | | -------------------- | ----------------------------------- | -------------- | | **Welcome Title** | Main greeting headline | 100 characters | | **Welcome Subtitle** | Descriptive text about capabilities | 250 characters | Example: ``` Title: "Welcome to TechSupport AI" Subtitle: "I can help you troubleshoot issues, find documentation, and answer questions about our products. What can I help you with?" ``` ### CSS Variables The widget uses CSS variables for consistent theming: ```css theme={null} :root { --primary-color: #f34611; --background-base: #ffffff; --text-color: #1F2937; --border-color: #E5E7EB; --radius-lg: 24px; --space-md: 16px; --space-sm: 8px; } ``` ## Widget Events The widget communicates via `postMessage` events: ### Listen for Events ```javascript theme={null} window.addEventListener('message', (event) => { switch(event.data.type) { case 'TOKEN_UPDATE': // New conversation token generated const token = event.data.token; localStorage.setItem('ctid', token); break; case 'CHAT_OPENED': // Widget was opened console.log('Chat opened'); break; case 'CHAT_CLOSED': // Widget was closed console.log('Chat closed'); break; } }); ``` ### Send Commands ```javascript theme={null} // Scroll chat to bottom window.postMessage({ type: 'SCROLL_TO_BOTTOM' }, '*'); // Update customization window.postMessage({ type: 'CUSTOMIZATION_UPDATE', data: { chat_bubble_color: '#f34611' } }, '*'); ``` ## Domain Restrictions Protect your widget from unauthorized embedding: Navigate to your agent's configuration. Add domains that are allowed to embed your widget. Turn on domain checking to block unauthorized sites. When domain restrictions are enabled, the widget will only load on whitelisted domains. Requests from other domains will be blocked. ## Mobile Responsiveness The widget automatically adapts to different screen sizes: ```css Desktop (> 768px) theme={null} .widget-container { width: 400px; height: 600px; border-radius: 24px; position: fixed; bottom: 20px; right: 20px; } ``` ```css Mobile (< 768px) theme={null} .widget-container { width: 100%; height: 100vh; border-radius: 0; position: fixed; top: 0; left: 0; } ``` ### Mobile Features * Full-screen chat interface on mobile devices * Touch-optimized buttons and inputs * Smooth animations and transitions * Keyboard-aware input positioning ## Widget Features Instant messaging with typing indicators and read receipts Share images and documents in conversations Rich text formatting in messages Full emoji picker for expressive conversations Persistent conversation history across sessions Seamless transfer to human agents when needed ## Best Practices 1. **Placement** * Add script just before closing `` tag * Ensure no conflicting CSS styles * Test on multiple pages 2. **Performance** * The widget loads asynchronously * Minimal impact on page load time * Consider lazy loading on high-traffic pages 3. **User Experience** * Test on both desktop and mobile * Verify email collection flow (Chatbot style) * Check conversation history persistence * Test offline/reconnection behavior 4. **Branding** * Match colors to your brand * Use consistent typography * Customize welcome messages for your audience ## Troubleshooting * Verify widget ID is correct * Check browser console for JavaScript errors * Ensure script is placed before `` tag * Check if ad blockers are interfering * Widget uses scoped CSS to minimize conflicts * Check for global CSS rules affecting the widget * Use browser DevTools to identify conflicting styles * Ensure viewport meta tag is present: `` * Check for CSS that might affect fixed positioning * Test in actual mobile devices, not just browser emulation * Verify localStorage is available and not blocked * Check if cookies/storage are being cleared * Ensure same widget ID is used across pages ## What's Next? After deploying your widget: 1. Configure authentication for secure access 2. Enable file attachments if needed 3. Set up human agent handoff 4. Monitor conversations in the dashboard Learn how to secure your widget with token authentication # Workflow Builder Source: https://docs.chattermate.chat/features/workflow-builder Build no-code conversation workflows for AI agents with the ChatterMate drag-and-drop builder, adding conditional logic, data collection, and automated actions. # Workflow Builder Design custom conversation journeys for your AI agents using our intuitive drag-and-drop workflow builder. Create sophisticated chat flows with conditional logic, data collection, and automated actions. Workflow Builder Interface ## Getting Started ### Creating a Workflow 1. **Switch to Workflow Mode**: Click the "Workflow" button in your agent configuration 2. **Access Workflow Builder**: Navigate to the "Workflow Builder" tab 3. **Create New Workflow**: Click "+ Create Workflow" to start building 4. **Name Your Workflow**: Provide a descriptive name and optional description Create New Workflow Modal ### Workflow Management Once created, you can manage your workflows with the following actions: * **Open Builder**: Access the visual workflow editor * **Edit**: Modify workflow name and description * **Delete**: Remove the workflow permanently * **Status**: Track workflow status (Draft, Published) Workflow Management ## Workflow Builder Interface The workflow builder provides a comprehensive visual interface for designing conversation flows: ### Canvas Area * **Drag-and-Drop Interface**: Build workflows by dragging nodes from the sidebar * **Visual Flow Design**: Connect nodes to create conversation paths * **Real-time Preview**: See your workflow structure as you build ### Node Sidebar Access all available node types for building your workflow: Workflow Canvas with Node Types ### Properties Panel Configure each node's settings and behavior: Node Properties Panel ## Node Types ### Landing Page Display a welcome screen with customizable heading and content **Purpose**: Create the initial interaction point for users entering your workflow **Configuration**: * **Node Name**: Identify the node in your workflow * **Description**: Optional description for documentation * **Heading**: Welcome message or title for users * **Content**: Detailed text displayed below the heading **Use Cases**: * Welcome messages for new visitors * Introduction to services or products * Setting expectations for the conversation *** ### Message Send a predefined message to the user **Purpose**: Deliver static content or information to users at specific points in the conversation **Configuration**: * **Message Content**: The text to be sent to the user * **Formatting**: Support for rich text and basic formatting * **Delay Settings**: Optional delay before sending the message **Use Cases**: * Providing information or instructions * Confirming user actions * Delivering notifications or updates *** ### LLM (Large Language Model) AI model processing with configurable prompts **Purpose**: Integrate AI-powered responses and intelligent conversation handling **Configuration**: * **Model Selection**: Choose the AI model to use * **System Prompt**: Define the AI's behavior and personality * **Context Management**: Control conversation history and context * **Response Parameters**: Temperature, max tokens, and other AI settings **Use Cases**: * Dynamic question answering * Intelligent conversation routing * Content generation and assistance *** ### Condition Branch conversation based on conditions **Purpose**: Create decision points that route conversations based on user input, data, or other criteria **Configuration**: * **Condition Logic**: Define the criteria for branching * **Multiple Paths**: Create different routes based on conditions * **Default Path**: Fallback route when conditions aren't met * **Variable Evaluation**: Use collected data in conditions **Use Cases**: * Routing based on user preferences * Handling different user types or roles * Creating complex conversation logic *** ### Form Collect structured data from users **Purpose**: Gather specific information from users through structured input fields **Configuration**: * **Field Types**: Text, email, number, select, etc. * **Validation Rules**: Required fields and format validation * **Field Labels**: User-friendly labels for each input * **Submission Handling**: Define what happens after form completion **Use Cases**: * User registration and onboarding * Contact information collection * Survey and feedback forms * Service request details *** ### Human Agent Let a human agent handle the conversation **Purpose**: Transfer the conversation to a live human agent when AI assistance isn't sufficient **Configuration**: * **Agent Assignment**: Specify which agents can handle transfers * **Transfer Conditions**: Define when transfers should occur * **Context Passing**: Share conversation history with human agents * **Escalation Rules**: Set priority and urgency levels **Use Cases**: * Complex issue resolution * Sales conversations requiring human touch * Sensitive customer complaints * Technical support escalation *** ### End Terminate conversation flow **Purpose**: Properly conclude the workflow and end the conversation **Configuration**: * **Ending Message**: Final message to the user * **Session Cleanup**: Clear temporary data and variables * **Analytics Tracking**: Record completion metrics * **Follow-up Actions**: Optional post-conversation tasks **Use Cases**: * Successful conversation completion * User-initiated conversation ending * Error handling and graceful exits * Redirecting to external resources ## Workflow Management ### Workflow States **Draft**: * Workflow is being created or edited * Not active for live conversations * Changes can be made freely **Published**: * Workflow is live and handling conversations * Users interact with the published version * Editing requires creating a new draft ### Best Practices 1. **Start Simple**: Begin with basic flows and add complexity gradually 2. **Test Thoroughly**: Use the preview feature to test all conversation paths 3. **Plan User Journeys**: Map out expected user interactions before building 4. **Use Clear Naming**: Give nodes descriptive names for easy maintenance 5. **Handle Edge Cases**: Include fallback paths for unexpected user behavior 6. **Regular Updates**: Keep workflows current with business changes ### Advanced Features **Variable Management**: * Store and use data collected throughout the conversation * Pass information between nodes * Use variables in conditions and messages **Integration Capabilities**: * Connect to external APIs and services * Trigger webhooks and notifications * Database operations and data storage **Analytics and Monitoring**: * Track user progress through workflows * Identify bottlenecks and drop-off points * Measure conversion rates and success metrics Workflows provide powerful automation capabilities while maintaining the flexibility to handle complex conversation scenarios. Start with simple flows and gradually build more sophisticated interactions as you become familiar with the system. Back: Learn about AI agent configuration and customization # Quickstart: Launch Your AI Support Agent in 5 Minutes Source: https://docs.chattermate.chat/quickstart Get your ChatterMate AI support agent live in about 5 minutes — sign up, connect your AI provider, train it on your docs, and embed the chat widget on your site. # Quickstart Guide There are two ways to run ChatterMate. Pick the one that fits you: Sign up and manage everything from the dashboard or the CLI. No infrastructure to run. **Best for most people.** Run the full ChatterMate stack on your own infrastructure with the self-host CLI. **Two different `chattermate` commands.** The **hosted CLI** (`pip install chattermate-cli`) signs you up and manages agents/knowledge against the ChatterMate API. The **self-host CLI** (`npm install -g chattermate-deploy`) scaffolds and runs the Docker stack. They are separate tools. ## Option A — Hosted service (fastest) Create a free account and configure your first agent — no browser required. ```bash theme={null} pip install chattermate-cli # installs the `chattermate` command # or: npm install -g chattermate-cli ``` See the [CLI reference](/features/cli) for `pipx`/`uvx`/`npm` options. ```bash theme={null} chattermate signup \ --name "Acme Inc" \ --domain acme.com \ --admin-email you@acme.com # password is prompted securely — you're logged in automatically ``` Prefer a browser? Sign up at [app.chattermate.chat](https://app.chattermate.chat) instead. ```bash theme={null} chattermate agent create --name "Support" --type customer_support -i "Be concise and friendly" chattermate knowledge add-url --website https://docs.acme.com --agent-id ``` Embed the [chat widget](/features/widget) on your site, or let an AI agent drive everything via the [MCP server](/features/mcp-server). A single copy-paste flow from signup to a live widget — built for AI agents and CI pipelines. ## Option B — Self-host with Docker Run the entire stack on your own machine with the self-host CLI (`chattermate-deploy`). ```bash theme={null} npm install -g chattermate-deploy ``` Initialize a new ChatterMate project: ```bash theme={null} chattermate-deploy init my-chattermate-project cd my-chattermate-project ``` Start all services with Docker: ```bash theme={null} chattermate-deploy start ``` Open your browser and visit: * Frontend Dashboard: `http://localhost/` * Backend API: `http://localhost:8000` * API Documentation: `http://localhost:8000/docs` ### Self-host CLI commands ```bash Project Management theme={null} chattermate-deploy init # Initialize a new project chattermate-deploy reset # Reset and cleanup project ``` ```bash Service Management theme={null} chattermate-deploy start # Start all services chattermate-deploy stop # Stop all services chattermate-deploy status # Check service status chattermate-deploy logs # View service logs ``` ## Manual Installation If you prefer to set up ChatterMate manually or need custom configuration: ### Backend Setup ```bash Setup Commands theme={null} # Clone the repository git clone https://github.com/chattermate/chattermate cd chattermate/backend # Create and activate virtual environment python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # Install dependencies pip install -r requirements.txt # Copy and configure environment variables cp .env.example .env # Edit .env file with your configurations ``` ```bash .env theme={null} # Copy .env.example to .env and configure these values: DATABASE_URL=postgresql://user:pass@localhost:5432/chattermate FIREBASE_CREDENTIALS=firebase-credentials.json JWT_SECRET_KEY=your-secret-key CONVERSATION_SECRET_KEY=yoursecretkey ENCRYPTION_KEY=encryption.key CORS_ORIGINS=["https://yourdomain.com"] ``` ### Frontend Setup ```bash Setup Commands theme={null} # Navigate to frontend directory cd frontend # Install dependencies npm install # Copy and configure environment variables cp .env.example .env # Edit .env file with your configurations ``` ```bash .env theme={null} # Copy .env.example to .env and configure these values: VITE_API_URL=http://localhost:8000 VITE_WS_URL=ws://localhost:8000 ``` ### Database Setup Create a PostgreSQL database and enable the vector extension: ```sql theme={null} CREATE DATABASE chattermate; \c chattermate CREATE EXTENSION vector; ``` Apply the database migrations: ```bash theme={null} alembic upgrade head ``` ### Running the Application ```bash Backend theme={null} # Start the backend server uvicorn app.main:app --reload --port 8000 ``` ```bash Frontend theme={null} # Start the frontend development server npm run dev ``` ## Verify Installation 1. Open your browser and navigate to `http://localhost:8000/docs` to view the API documentation 2. Visit `http://localhost/` to access the web interface (CLI) or `http://localhost:3000` (manual setup) 3. Try sending a test message in the chat widget ## Next Steps Setup new organization Configure AI provider Customizing AI agent Adding knowledge to AI agent Testing AI agent Adding chat widget to the website Adding Human Agent Managing Roles and Permission Managing Customer chat and Taking over chat