Creating a Chat Agent

This guide covers the main steps for setting up a new chat agent for your website.

Basic Settings

• Name — A descriptive name for the agent
• Text Number — Optional phone number for SMS capabilities

Instructions

Use the instructions field to define how the chat agent should behave. A strong prompt usually covers:

• Identity — Who the chat agent represents (your business name, role)
• Purpose — What the agent should help visitors with
• Tone — Friendly, professional, casual, etc.
• Knowledge — Key facts about your business, products, services
• Boundaries — Topics to avoid or redirect

Writing Effective Instructions

• Include your business hours, location, and contact details when relevant
• Define how to handle pricing or qualification questions
• Specify when to collect contact information
• Set rules for when to summon a human operator
• Include answers or guidance for common questions

Appearance

Customize the widget experience to better match your site:

• Avatar — Upload a custom image for the chat bubble
• Greeting — The two-line welcome message (bold Static Greeting + muted Static User Instruction), with page-targeted variants so different pages can open with different guidance — see Widget Greeting & Nudges
• Attention Messages — Rotating nudge messages shown on the chat bubble to encourage visitors to click (e.g., "Hi there! Need help?"), each targetable to specific pages with URL rules — see Widget Greeting & Nudges
• Theme — The widget automatically inherits styling compatible with most websites

Tools

Enable the tools the agent should be allowed to use:

• Web Search — Search the internet for answers
• Knowledge Base — Search your uploaded documents and vector stores
• Calendar Booking — Let visitors book appointments
• Contact Lookup — Identify returning visitors
• Summon Operator — Request a human to join the chat
• Form Collection — Collect structured data from visitors
• Weather — Live Environment Canada conditions and alerts for Canadian cities (see Weather Tool)
• Custom Tools — Connect external services via MCP

Embedding the Widget

After saving, use the embed code snippet to place the widget on your website:

1. Open the chat agent detail page
2. Copy the embed code
3. Paste it into your website's HTML, typically just before the closing </body> tag
4. The widget will appear as a chat bubble in the corner of your site

The widget can be embedded on many kinds of websites, including static sites, WordPress, Shopify, and React applications.

Content Security Policy (CSP)

If your website uses a Content-Security-Policy header, you'll need to allow the widget's domain. Add these two directives:

Directive	Value
script-src	https://chat.karmaflow.ai
frame-src	https://chat.karmaflow.ai

Example:

Content-Security-Policy: script-src 'self' https://chat.karmaflow.ai; frame-src https://chat.karmaflow.ai;

No additional connect-src, img-src, or style-src entries are needed — the chat UI runs inside an iframe with its own security policy. If your site does not set a CSP header, no action is needed.

Testing

You can test the widget directly from the chat agent detail page before embedding it on your site.