Agent Settings

What is an Agent?

An agent is your AI chatbot. Each agent has its own name, personality, knowledge base, and visual appearance. When customers chat with your WebApp, they're talking to an agent that draws on its assigned sources and Q&A pairs to provide helpful, accurate responses.

You can create multiple agents for different purposes — one for customer support, another for sales inquiries, and so on. Each agent can be customized independently.

Creating an Agent

To create a new agent, go to the Agents tab in instraCHAT and click Create. You'll need to provide:

• Name — A unique identifier for your agent (max 30 characters). This is how you'll recognize it in your dashboard
• Purpose — A brief description of what the agent does (max 256 characters). This helps you and your team understand the agent's role
• AI Model — The underlying AI model that powers responses. Different models offer different capabilities and response styles
• Secondary Model — Optional fallback model used when the primary model fails to generate a response
• Base Instructions — Custom instructions that guide the agent's behavior, tone, and response style (max 256 characters)

Cloning Agents

You can clone an existing agent to create a copy with all its settings, sources, Q&A pairs, and appearance. The clone gets an auto-generated name like "[CLONE] Original Name" which you can change. This is useful for creating variations or testing changes without affecting the original.

Agent Detail Page

Click on any agent to open its detail page. Here you'll find several tabs for managing different aspects of the agent:

Overview Tab

The Overview tab shows key statistics for your agent:

• Total Conversations — Number of chat sessions with users
• Total Sources — Knowledge sources assigned to this agent
• Total Q&As — Question-answer pairs available to this agent
• Average Response Time — How quickly the agent responds

Below the stats, you'll see a list of conversations. You can filter by user, source used, status (Active, Escalated, Resolved, Ended), and search for specific conversations. Click any conversation to view the full message history.

Playground Tab

The Playground lets you test your agent before going live. Send messages and see how the agent responds based on its current configuration, sources, and Q&A pairs.

Use the Playground to:

• Verify responses are accurate and helpful
• Test different question types
• Check that base instructions are being followed
• Ensure sources are being used correctly

Sources Tab

Manage the knowledge sources assigned to this agent. You can:

• Create new sources — Upload files or add URLs directly for this agent
• Assign existing sources — Link sources from your main Sources library
• Remove sources — Unlink sources without deleting them from the library

Sources created here are also stored in the main Sources library, so you can assign them to other agents later. See Agent Sources for more details.

Q&A Tab

Manage the question-answer pairs for this agent. Q&A pairs provide direct answers to specific questions and can be displayed as suggestions in the chat widget.

• Create new Q&As — Add questions with specific answers
• Assign existing Q&As — Link Q&As from your main library
• Set page references — Specify which pages should show each Q&A

See Agent Q&A for more details.

Integration Tab

Get the code to embed your agent on external websites and manage the chat bubble within your WebApp.

Chat Bubble (WebApp)

Toggle the chat bubble to display this agent as a floating chat widget throughout your WebApp. Only one agent can have the chat bubble enabled at a time. If another agent is using it, enabling it here will switch the bubble to this agent.

Widget Integration Code

For embedding on external websites, copy the integration code and paste it before the closing </body> tag in your HTML. The widget will automatically initialize and display the chat bubble.

Passing User Data (External Embeds)

When embedding on external websites with their own authentication, you can pass user data to the widget. This allows conversations to be tracked with user emails in your admin panel, making it easier to identify who's chatting. For WebApp users, this is handled automatically through authentication.

Email Integration

Enable your agent to receive and respond to customer emails using the same AI and knowledge base it uses for chat. When someone emails your agent, it generates an intelligent response and sends it back — just like a chat conversation, but over email.

To set up email for an agent:

1. Open the agent's Integration tab and find the Email section
2. Select a sender email address from your configured sender emails (e.g., support@yourdomain.com). Each email address can only be assigned to one agent
3. Enable the email agent toggle to start receiving emails

Rate limiting — Each email agent has configurable rate limits to prevent spam. You can set limits per minute (1–100, default 10) and per hour (1–1000, default 100). Emails exceeding these limits are silently dropped.

Email verification — When someone who isn't an existing contact sends an email for the first time, they receive a verification email with a confirmation link. Their message is held until they verify. Once verified, all future emails are processed immediately. Verification links expire after 1 hour.

Email threading — Replies are threaded correctly so the conversation stays organized in the customer's inbox. If the AI determines the query needs human attention or the customer explicitly requests escalation, the conversation is escalated and the sender receives an escalation notification email.

Settings Tab

Configure all aspects of your agent:

Basic Information

• Name — Update the agent's name (must be unique)
• Purpose — Update the description
• AI Model — Change the primary AI model
• Secondary Model — Set or change the fallback model
• Base Instructions — Customize behavior guidelines
• Status — Toggle between Active and Inactive

Avatar

Upload a custom avatar image that appears in the chat widget header and conversation list. Drag and drop an image or click to browse. Supported formats include JPEG, PNG, and GIF.

Appearance

Assign an appearance template to customize how the chat widget looks. You can:

• Select from existing templates
• Create a new template directly from here
• Edit the currently assigned template
• Remove the assigned template to use default styling

See Appearance for details on creating and managing templates.

Human Agent Settings

Configure how human support appears when conversations are escalated:

• Human Agent Name — The name shown when a human responds
• Human Agent Avatar — Optional avatar for human responses

These settings help users distinguish between AI responses and human support during escalated conversations. Currently, these settings are shared across your entire team — regardless of which team member responds, they all appear with the same name and avatar. Individual team member profiles for support responses are planned for a future update.

Delete Agent

Permanently delete the agent and all its conversations. This action cannot be undone. Sources and Q&A pairs remain in the main library — only their assignment to this agent is removed.

Agent Status

Each agent can be either Active or Inactive:

• Active — The agent is live and will respond to user messages. The chat bubble will appear if enabled
• Inactive — The agent is disabled and won't respond. The chat bubble is hidden even if enabled

Use Inactive status when you need to temporarily disable an agent without deleting it — for example, during maintenance or while updating its knowledge base.

Best Practices

• Write clear base instructions — Tell the agent its role, tone, and any specific behaviors or restrictions
• Test before going live — Use the Playground extensively to verify responses before enabling the chat bubble
• Start with focused sources — Begin with a few high-quality sources rather than many broad ones
• Monitor conversations — Review conversations regularly to identify gaps in knowledge or areas for improvement
• Use descriptive names — Name agents clearly so you can quickly identify their purpose (e.g., "Support Bot", "Sales Assistant")