> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chattermate.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize AI Agent

> 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](https://mintcdn.com/chattermatechat/KuJSDVe8niV0oBYv/images/agent-management.png?fit=max\&auto=format\&n=KuJSDVe8niV0oBYv\&q=85\&s=4e02163751054ac7ae637977b57e80af)

## 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

Either can also be switched off entirely with **Let AI Answer**, which hands every
conversation to your team instead. See [Let AI Answer](#let-ai-answer) below.

> [tab] Agent
>
> ![Agent Configuration](https://mintcdn.com/chattermatechat/KuJSDVe8niV0oBYv/images/agent-tab.png?fit=max\&auto=format\&n=KuJSDVe8niV0oBYv\&q=85\&s=3058fa7d897b0eb75da231ee808b466f)
>
> ## 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
>
> ### Let AI Answer
>
> On by default. Turn it off to put the agent in **human mode**: it never answers
> with AI, and every conversation goes straight to your inbox for a person to reply
> to, from the customer's first message.
>
> Use it when you want ChatterMate as a shared inbox for your team, or while you're
> still writing an agent's instructions and don't want it talking to customers yet.
>
> In human mode:
>
> * The model is never called, so the conversation costs you nothing in AI usage
>
> * The customer gets a short acknowledgement, then waits for your team
>
> * Your team gets the usual new-chat notification
>
> * The conversation shows as **Waiting for human** in the inbox until someone takes it
>
> * The widget header follows your [business hours](https://docs.chattermate.chat/features/organization.md) instead of
>   promising an instant reply, and the AI disclaimer is hidden
>
> > [!NOTE]
> >
> > Human mode is not a transfer — there was no AI in the conversation to hand it on.
> > Customers see no "connecting you to a teammate" message and no handoff form.
>
> Pick the groups that should handle these chats under **Transfer Groups**, which stays
> available in human mode.
>
> ### Transfer to Human
>
> Only applies while the AI is answering. Enable automatic transfer to human agents when:
>
> * AI agent can't handle the query
>
> * Customer specifically requests human support
>
> * Complex issues require human intervention
>
> > [!NOTE]
> >
> > 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

> [tab] Chat Customization
>
> ![Chat Customization](https://mintcdn.com/chattermatechat/KuJSDVe8niV0oBYv/images/chat-customization.png?fit=max\&auto=format\&n=KuJSDVe8niV0oBYv\&q=85\&s=0b62735aa6ef2ecc60a30f1c53b1839a)
>
> ## Visual Customization
>
> ### Chat Design
>
> Choose the look of the chat interface:
>
> | Design | Description |
> | - | - |
> | **Legacy** | The original look — light, neutral, classic chatbot. |
> | **Ask Anything** | Modern AI assistant style for general queries. |
> | **Aurora** | Dark, with a glowing aurora orb avatar. |
> | **Glass** | Frosted dark glass with soft glow and rounded bubbles. |
> | **Terminal** | Monospace developer style, square corners. |
> | **Playful** | Light, friendly and very rounded with warm accents. |
> | **Calm Mint** | Clean dark-teal with subtle borders. |
> | **Sunrise** | Bright, warm and airy — a light theme with a soft coral accent. |
>
> #### The Ask AI panel
>
> **Ask Anything** and **Aurora** do not open as a chat window in the corner. They open as a centered command palette over a dimmed page — press ⌘K (Ctrl+K on Windows and Linux), Esc or a click outside to dismiss it.
>
> * One input at the top, with suggested questions while it is empty
> * Answers written as prose, with their sources listed underneath
> * The answer types out as it arrives, and the panel grows to fit it
> * Customizable welcome title and subtitle
>
> These are also the only two designs that can use the **search bar** placement, which replaces the launcher bubble with an "Ask anything" bar. See [Widget Integration](https://docs.chattermate.chat/features/widget.md#placement).
>
> > [!NOTE]
> >
> > Every other design opens as a normal chat window and works in any placement.
>
> ### Welcome Message (Ask Anything and Aurora)
>
> When using the Ask Anything or Aurora design, 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 Inter, Instrument Sans, Space Grotesk, JetBrains Mono or your system font
> * Ensure readability and brand alignment
> * Consistent typography across all chat elements
>
> ### Chat Behaviour
>
> | Setting | Default | What it does |
> | - | - | - |
> | **Show citations** | On | Lists the knowledge sources an answer came from. |
> | **Collect email before chat** | Off | Requires visitors to enter their email before they can start chatting. |
> | **Show AI disclaimer** | On | Adds "AI can make mistakes" to the widget footer. Hidden automatically once a human agent takes over. |
> | **Let visitors start a new chat** | Off | Adds a **New chat** control that ends the conversation and starts a fresh one. |
>
> #### Let visitors start a new chat
>
> A conversation normally continues where the visitor left off, which is what most people want — they come back and their history is still there. Turn this on when they might arrive with an unrelated question and would rather start clean.
>
> The control asks for confirmation before discarding the conversation, and is hidden while a human agent is handling the chat so a visitor cannot accidentally end a live conversation with your team.
>
> Starting a new chat does not change who the visitor is: if your app identified them with [token authentication](https://docs.chattermate.chat/features/authentication.md), the new conversation arrives in the inbox as the same person, with their `custom_data`.
>
> ### Widget Placement
>
> The **Widget placement** section sets where the widget sits on your site — a floating bubble, a full-height drawer or a search bar — and whether it uses the built-in launcher at all. Anything set in your embed snippet overrides these defaults for that page.
>
> See [Widget Integration](https://docs.chattermate.chat/features/widget.md#placement) for the full list of options and the JavaScript API.
>
> > [!NOTE]
> >
> > All customizations are instantly reflected in the chat preview on the right side of the interface.

> [tab] Test & Preview
>
> ![Test & Preview](https://mintcdn.com/chattermatechat/KuJSDVe8niV0oBYv/images/test-preview.png?fit=max\&auto=format\&n=KuJSDVe8niV0oBYv\&q=85\&s=dae21effda589a3c31a582b48677727f)
>
> ## 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
>
> > [!NOTE]
> >
> > Use this preview to thoroughly test your agent before making it live to ensure the best customer experience.

> [tab] Knowledge
>
> ![Knowledge Sources](https://mintcdn.com/chattermatechat/-wE-OCNZRRyM6A4m/images/knowledge-sources.png?fit=max\&auto=format\&n=-wE-OCNZRRyM6A4m\&q=85\&s=296e3d06a5db0c2bb6d29ee327dbaf3a)
>
> ## 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
>
> > [!NOTE]
> >
> > Add knowledge sources to improve the agent's responses and reduce "I don't know" scenarios.

> [tab] Integrations
>
> ![Agent Integrations](https://mintcdn.com/chattermatechat/KuJSDVe8niV0oBYv/images/agent-integrationtab.png?fit=max\&auto=format\&n=KuJSDVe8niV0oBYv\&q=85\&s=8b65ce9bbfe921cd4e1e12a71e91d3e3)
>
> ## 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
>
> > [!NOTE]
> >
> > Jira connection must be established in settings before enabling ticket creation.

> [tab] MCP Tools
>
> ![MCP Tools](https://mintcdn.com/chattermatechat/KuJSDVe8niV0oBYv/images/mcp-tools.png?fit=max\&auto=format\&n=KuJSDVe8niV0oBYv\&q=85\&s=ee492d771cfb90648eba2048b198db95)
>
> ## 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
>
> > [!NOTE]
> >
> > MCP tools require proper configuration and may need API keys or specific permissions to function correctly.

> [tab] Widget
>
> ![Widget Integration](https://mintcdn.com/chattermatechat/KuJSDVe8niV0oBYv/images/agent-widgettab.png?fit=max\&auto=format\&n=KuJSDVe8niV0oBYv\&q=85\&s=fbc3449768b30f00c5b901f7f8787f7e)
>
> ## Widget Integration
>
> Add the chat widget to your website by copying and pasting the following code:
>
> ```html theme={null}
> <script>window.chattermateId='YOUR_WIDGET_ID';</script>
> <script src="YOUR_WIDGET_URL/webclient/chattermate.min.js"></script>
> ```
>
> 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

> [tab] Advanced
>
> ![Advanced Settings](https://mintcdn.com/chattermatechat/KuJSDVe8niV0oBYv/images/agent-advancedtab.png?fit=max\&auto=format\&n=KuJSDVe8niV0oBYv\&q=85\&s=5181c4c4327f0fa467b612a307a1902e)
>
> ## 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
>
> > [!NOTE]
> >
> > 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

> [!NOTE]
>
> Switch between AI Mode and Workflow using the toggle buttons at the top of the agent configuration.

> [card] [MCP Tools](https://docs.chattermate.chat/features/mcp-tools.md)
>
> Learn how to extend your AI agent with external tools and services

> [card] [Workflow Builder](https://docs.chattermate.chat/features/workflow-builder.md)
>
> Next: Learn how to create advanced conversation workflows

> [card] [Knowledge Base](https://docs.chattermate.chat/features/knowledge-base.md)
>
> Learn how to enhance your AI agent with domain knowledge


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.