# 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](/docs/chat-agents/widget-greeting-and-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](/docs/chat-agents/widget-greeting-and-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 - **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](/docs/chat-agents/weather-tool)) - **Custom Tools** — Connect external services via MCP **Booking meetings in a chat.** Turn on the calendar tools in the agent's tool list and the agent offers free times from a connected Google or Microsoft 365 calendar and books the one the visitor picks, as voice and SMS agents do. It uses the calendar of the person who created the agent. The agent asks for the visitor's email before booking, so the invite reaches them. Without one the meeting is still booked and linked to the visitor, and the Calendar page says no email is on the invite. The meeting shows on the contact's record and on the Calendar page, with a link back to the chat it was booked in. Anyone can open a chat, so a visitor reaches only their own meetings: - **Free times** and **booking** work as on other channels: only times inside your bookable hours (**Settings → Timezone & bookable hours**, Monday to Friday 09:00–17:00 until you change them), inside the host's own hours when they set them (**Calendar → Your hours**), and free on the calendar are offered, each written in the visitor's own timezone when the agent knows it. - **Finding a person's meetings** shows only the visitor's own: the ones linked to their contact record or booked in that chat, and, when their contact record has an email, the meetings on the calendar with that email (for example one they booked through a booking link). Never with the other attendees. - **Changing a meeting** works only for one of those (Google Calendar), and not for a meeting other contacts are also on, unless it was arranged in that chat: the agent offers to pass the request to the host. A visitor can be added to the invite, but never removes anyone else from it. - **Sending a booking page** (**calendar-booking-page-link**) gives the visitor the host's published page to pick a time themselves: their personal link when the chat knows who they are, the page's own address when it does not ([Booking pages](/help/crm/booking-pages#personal-links)). - **Listing the calendar's events**, **listing calendars** and **sharing the calendar** do not run in a chat; the agent offers free times instead. **Mail and file tools in a chat.** Google Workspace and Microsoft 365 mail, drive and document tools run in a chat when you turn them on. Anyone who opens the chat can then ask the agent to read, send or change things in that account. The tool list says this under each one, so turn them on only when that is what you want. ## 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 `` 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. ### Allowed origins The widget answers only on the websites you list. In the agent editor, open the **Embed** tab and fill in **Allowed Origins** under **Embed & Notifications**: a comma-separated list of origins, such as `https://example.com, https://www.example.com`. An origin is the scheme and host (plus the port, if it is not the default), with no path. If the list is empty, the widget works on no website. Changes reach the live widget when you click **Save & Push Live**. ### Testing on localhost (Development agents) While you build a site, the widget often runs on `http://localhost` on a port that changes, or on preview addresses you cannot list in advance. A chat agent marked as Development can switch off its embed security instead: 1. Open the agent editor. On the **Setup** tab, under **Basic Configuration**, set **Environment** to **Development** and save. 2. Open the **Embed** tab. A section named **Development: Embed Security** appears below **Embed & Notifications**. 3. Turn on **Turn off embed security — load from any URL, including localhost**. 4. Click **Save & Push Live**. The widget now loads on any page, including `http://localhost`, without checking **Allowed Origins** and without its Content-Security-Policy. While it is off, the editor's header shows an **Any origin (dev)** badge, the agent's view page reads *Embed Security: Off*, and its row on the Agents page reads *Any origin (dev)*. Things to know: - **Anyone who has the embed code can run the agent on their own site**, and those conversations use your AI usage. Keep this for agents you are developing. - **It only works on Development agents.** If you change **Environment** to **Staging** or **Production**, the agent goes back to **Allowed Origins** straight away, even with the switch still on. The section then says *Not in effect* so you can clear it. - **The rest stays on.** The widget's access token, the draft-preview check and the rate limits still apply. Only the allowed-origins check and the Content-Security-Policy are switched off. - **Development agents are left out of dashboards and statistics**, so test conversations do not skew your numbers. ## Testing You can test the widget directly from the chat agent detail page before embedding it on your site.