Agent Settings

Agent Settings

The Settings page is where you define everything about how your agent behaves, looks, and interacts with users. Every setting described in this reference is accessible from the Settings tab in your agent dashboard. Changes take effect immediately and propagate to all deployment channels automatically.

General Settings

Agent Name

The display name for your agent. This appears in the chat widget header, the shareable link page, analytics reports, and conversation logs. Choose a name that reflects its purpose and feels natural to your users.

Examples:

• "Acme Support" for a customer support agent.
• "ProductBot" for a product Q&A assistant.
• "HR Assistant" for an internal employee-facing agent.

Agent Description

A brief internal description of the agent's purpose. This is not displayed to end users -- it is for your own reference and your team's, visible on the dashboard and in agent lists.

Visibility

Controls whether the agent is publicly accessible or restricted to API access only. See the Connect & Deploy guide for full details on public vs. private visibility and its implications for each deployment method.

System Prompt

The system prompt is the most powerful configuration option for controlling your agent's behavior. It defines the agent's identity, personality, tone, scope of knowledge, and behavioral boundaries. The AI model reads the system prompt before every response, treating it as foundational instructions.

Writing an Effective System Prompt

A strong system prompt includes five elements:

1. Identity -- Who the agent is and what company or product it represents.
2. Scope -- What topics the agent is authorized to discuss.
3. Tone -- How the agent should communicate (formal, friendly, technical, etc.).
4. Boundaries -- What the agent should not do (make up information, discuss competitors, share internal data).
5. Fallback behavior -- What to do when the agent does not know the answer.

Example: E-commerce Customer Support

You are the customer support assistant for ShopWave, an online fashion retailer.

Your role is to help customers with:
- Order status and tracking
- Returns and exchanges (our policy allows returns within 30 days)
- Product sizing and recommendations
- Shipping information and delivery estimates
- Account and payment questions

Communication style:
- Be warm, helpful, and conversational
- Use the customer's name when available
- Keep responses concise but complete
- Use bullet points for multi-part answers

Boundaries:
- Never make up information. If you do not have the answer, say: "I don't have that information right now. Let me connect you with our team at [email protected]."
- Never discuss competitors or compare products to other brands
- Never share internal pricing strategies or margin information
- Do not process refunds or make account changes — direct the user to the support team for actions

Always end complex interactions by asking if there is anything else you can help with.

Example: SaaS Product Assistant

You are the product assistant for CloudSync, a file synchronization and backup platform.

Your purpose is to help users understand CloudSync features, troubleshoot common issues, and guide them through setup and configuration.

When answering technical questions:
- Provide step-by-step instructions when applicable
- Include relevant settings paths (e.g., Settings > Sync > Advanced)
- Reference specific plan features when they vary by tier
- If a feature is only available on certain plans, mention which plans include it

Tone: Professional but approachable. Avoid jargon where possible. When technical terms are necessary, briefly explain them.

If a user reports a bug or an issue you cannot resolve:
1. Acknowledge the issue
2. Suggest basic troubleshooting steps (restart app, check connection, update to latest version)
3. If unresolved, direct them to submit a ticket at support.cloudsync.io

Never share information about unreleased features, internal roadmap, or pricing changes not yet announced publicly.

Example: Healthcare Information Agent

You are a health information assistant for WellPath Clinic.

You provide general health education and help patients navigate clinic services, appointment scheduling, and insurance questions.

CRITICAL BOUNDARIES:
- You are NOT a doctor. Never diagnose conditions, recommend treatments, or interpret test results.
- Always include the disclaimer: "This is general information only. Please consult your healthcare provider for medical advice specific to your situation."
- Never recommend stopping or changing medications
- If a user describes an emergency, immediately respond: "If you are experiencing a medical emergency, please call 911 or go to your nearest emergency room."

You CAN help with:
- Clinic hours, locations, and contact information
- General information about services offered
- Insurance and billing questions
- Appointment scheduling guidance
- General wellness information from reputable sources

Example: Real Estate Agent

You are the virtual assistant for PrimeRealty, a residential real estate brokerage.

Help potential buyers and sellers with:
- Property search guidance and market information
- Explaining the buying/selling process
- Mortgage and financing basics
- Neighborhood information and comparisons
- Scheduling viewings (collect name, email, phone, and preferred times)

Tone: Professional, knowledgeable, and enthusiastic about helping people find their perfect home. Be encouraging without being pushy.

When a user expresses interest in a specific property or wants to schedule a viewing, collect their contact details and let them know an agent will follow up within 24 hours.

Never provide specific property valuations or guarantee market predictions. Use phrases like "based on recent trends" and "typically in the range of" when discussing pricing.

Instructions

Instructions are supplementary behavioral rules that refine your agent beyond what the system prompt defines. While the system prompt sets the overall identity and tone, instructions are best for specific, granular rules.

How Instructions Differ from the System Prompt

Example instructions:

• "Always greet the user by name if their name is available from lead capture."
• "Respond in the same language the user writes in."
• "Never share pricing information. Direct users to https://yoursite.com/pricing."
• "When a user asks about a feature that requires a paid plan, mention which plan includes it."
• "If the user expresses frustration, acknowledge their feelings before providing a solution."
• "Limit responses to 3 paragraphs maximum. Use bullet points for lists."

Model Selection

The AI model determines the intelligence, speed, and cost of your agent's responses. Chatsby supports multiple models to accommodate different use cases and budgets.

Choosing the Right Model

• Start with GPT-4o Mini. It offers the best balance of quality, speed, and cost for most customer support use cases.
• Upgrade to GPT-4o if you need more nuanced reasoning, better handling of complex multi-part questions, or more sophisticated tone control.
• Use GPT-4.1 or GPT-4.1 Mini when your agent needs to work with very large sources or maintain context across long conversations.
• Use GPT-4.1 Nano for extremely high-volume, simple FAQ scenarios where cost efficiency is the primary concern.

Temperature

Temperature controls the randomness and creativity of the model's responses. It is a value between 0 and 1.

Default: 0.7. For most customer support use cases, we recommend lowering this to 0.2 - 0.4 for more consistent, reliable responses.

Max Tokens

Max tokens sets the upper limit on the length of the agent's responses. One token is approximately 4 characters or 0.75 words in English.

Setting max tokens too low may cause responses to be cut off mid-sentence. Setting it too high does not force the model to generate longer responses -- it simply allows it to when needed. The model naturally produces responses of appropriate length for the question asked.

Chat Interface Customization

These settings control the visual appearance and behavior of the chat widget. All changes preview in real-time on the Settings page and propagate immediately to all deployed widgets.

Appearance

Content

Behavior

Branding

On the Free plan, a "Powered by Chatsby" badge appears at the bottom of the widget. This badge is removed on the Starter plan and above.

Lead Capture Configuration

Lead capture collects user contact information, turning anonymous conversations into identifiable leads for your sales or support team.

Available Fields

Capture Timing

• Before conversation -- The lead capture form appears when the user first opens the chat, before they can send a message. This maximizes capture rate but adds friction.
• During conversation -- The form appears after the user sends their first message and receives a response. This reduces friction and captures leads who are already engaged.

Lead Data Access

Captured leads appear in the Contacts section of your agent dashboard. They can also be accessed via the API or exported as CSV. For CRM integration, configure a webhook to send lead data to your system in real-time. See Managing Contacts for more details.

Notification Settings

Configure how your team is notified about agent conversations and events.

Email Notifications

Receive email alerts when:

• A new conversation starts
• A conversation is escalated to a human agent
• A user leaves negative feedback

Configure the recipient email address(es) in Settings. Multiple addresses can be added, separated by commas.

Slack Notifications

Connect a Slack workspace and channel to receive real-time conversation alerts. See the Slack Integration Guide for setup instructions.

Webhook Notifications

Send conversation events to any HTTP endpoint for custom processing. Webhooks fire for:

• conversation.started -- A new conversation is initiated.
• conversation.message -- A new message is sent (user or agent).
• conversation.escalated -- The conversation is escalated to a human.
• lead.captured -- A user submits the lead capture form.

{
  "event": "conversation.started",
  "agent_id": "agent_abc123",
  "conversation_id": "conv_xyz789",
  "timestamp": "2026-04-02T14:30:00Z",
  "user": {
    "name": "Jane Smith",
    "email": "[email protected]"
  }
}

Escalation Settings

Define the conditions under which a conversation is flagged for human review:

• When the agent's confidence score falls below a threshold you set.
• When a user explicitly requests to speak with a human.
• When negative feedback is submitted.

Escalated conversations are highlighted in the dashboard and trigger the notification channels you have configured.

Security Settings

Allowed Domains

Restrict which domains can load your chat widget. When configured, the widget only functions on the specified domains. Leave empty to allow all domains.

yoursite.com, app.yoursite.com, help.yoursite.com

This prevents unauthorized parties from embedding your agent on their own websites, which would consume your plan's conversation credits and potentially misrepresent your brand.

Rate Limiting

Configure rate limits to protect against abuse:

Rate-limited users receive a polite message asking them to wait before sending another message. These limits protect your agent from automated abuse without affecting normal users.

Import and Export Configuration

Export

Export your agent's complete configuration as a JSON file. This includes the system prompt, instructions, model settings, interface customization, lead capture configuration, and notification settings. It does not include training sources (which are managed separately).

Use exports for:

• Backup -- Save a snapshot of your configuration before making major changes.
• Replication -- Apply the same configuration to a new agent.
• Version control -- Track configuration changes over time by storing exports in your version control system.

Import

Import a previously exported configuration JSON file to apply it to any agent. This overwrites the agent's current settings with the imported values.

Settings Best Practices

1. Start with the system prompt. Get the identity, tone, and boundaries right before tuning anything else. The system prompt has more impact on response quality than any other setting.
2. Lower the temperature for support agents. Most customer-facing agents perform best at 0.2-0.4. Reserve higher temperatures for creative or conversational use cases.
3. Use instructions for specific rules. Keep the system prompt focused on identity and personality. Use instructions for granular behavioral rules that may change frequently.
4. Test every change in the Playground. Never assume a setting change will produce the desired effect. Always validate in the Playground before it reaches real users.
5. Enable lead capture strategically. "During conversation" capture has higher completion rates than "before conversation" because users are already engaged. Only require fields you will actually use.
6. Set up notifications early. Configure at least email notifications before going live so you can monitor conversations from day one.
7. Export your configuration after major changes. Maintain a backup so you can revert quickly if a change has unintended consequences.