# AI Training

## Overview

AI Training is where you build chat assistants — text-based AI personas — and train them on your own content. A trained assistant powers the chatbot widget on your site. You manage them under More → AI Training.

A chat assistant is two things: a persona and model setup (greeting, character brief, tone, language, provider, model, reply length, creativity, fallback, and human-handoff rules) and a set of knowledge sources (web links, files, free text, and Q&A pairs). When someone chats, the assistant draws on your material to answer — see Where the assistant is used.

These are separate from the voice AI Call Assistant: chat assistants reply in text, voice assistants answer phone calls. Build a chat assistant with the five-step Smart Agent Builder: Identity, Persona, Brain, Safety, and Knowledge.

> Prerequisite — the admin sets the provider keys. You don't paste an API key here. The platform admin sets up the OpenAI / Anthropic Claude / Google Gemini keys once under Admin → AI & API Keys, and every chat assistant uses them automatically. The builder says it directly: "Admin pre-configures the API keys — no key required from you."

> Plan-gated. AI Training needs the AI Chat Assistant plan feature — the same one the chatbot widget relies on — so a workspace without it can't create assistants.

## Creating a chat assistant

1. Open the builder from the AI Training list (or open an existing assistant to edit it).
2. Work through the five steps below. Use Save draft at any point; the persona and model settings save together.
3. Add knowledge sources in Step 5. Each source is checked right away and lands in a ready (or failed) state.
4. Set status to Live (Step 1) so the assistant can be selected in chatbot widgets — only Live assistants appear in the widget picker.
5. Attach it to a chatbot widget to put it to work.

A brand-new assistant starts with sensible defaults (a friendly greeting, a concise "helpful website assistant" brief, OpenAI `gpt-4o-mini`, 400-token replies, creativity 0.7, handoff on). You can change any of them before the first save.

## Step 1 · Identity

Field | Required | Default | What it does
--- | --- | --- | ---
Agent display name | Yes (max 120) | — | For your records only; visitors don't see it.
Roll-out status | No | Live | Live (selectable in widgets) or Paused (stays in the list but can't be attached to new widgets).
Preferred language | No (max 16) | English | A standard language code; the assistant auto-matches a visitor's language if it differs.
Conversational tone | No (max 32) | Helpful | Sets the writing style, separate from the character brief — see the tone table.

### Tone options

Tone | Style
--- | ---
Helpful | Calm and on-point.
Friendly | Warm and casual.
Formal | Neutral and precise.
Playful | Light and witty.

The chosen tone shapes the assistant's writing style on every reply, alongside its language.

## Step 2 · Persona & opening line

Field | Required | What it does
--- | --- | ---
Opening line | Yes (max 1000) | Visitor-facing; shown as the first bubble when chat opens, e.g. "Hi! How can I help today?".
Character brief (system instructions) | No (max 8000) | Internal, never shown to visitors. Spell out who the assistant is, the do's and don'ts, price/escalation limits, and refusal rules.

> Safety lives in the brief. The character brief is the right place for guardrails — for example "never quote prices above $500 (escalate to a human instead)" or "politely refuse to discuss competitors." Everything you write here is fed to the assistant word-for-word, so it shapes every reply.

## Step 3 · Model & reply controls

Choose the brain and tune how it answers.

Field | Default | Range / values | What it does
--- | --- | --- | ---
Model provider | OpenAI | OpenAI, Anthropic, Gemini | OpenAI (GPT family), Anthropic (Claude family), or Google (Gemini family).
Model name | `gpt-4o-mini` | free text, max 80 | The exact model name, so new models work without waiting for an app update.
Reply length budget (tokens) | 400 | 50–4000 | About a paragraph at 400. Roughly 1 token ≈ 4 characters.
Creativity | 0.7 | 0–2 | Lower is consistent and factual; higher varies the phrasing.

### Model reference

Example model names the builder suggests for each provider:

Provider | Example model name
--- | ---
OpenAI | `gpt-4o-mini` (default)
Anthropic | `claude-haiku-4-5-20251001`
Google Gemini | `gemini-2.5-flash-lite`

## Step 4 · Fallback & human handoff

Field | Default | What it does
--- | --- | ---
Fallback reply | "A teammate will follow up shortly — thanks for your patience." | Sent verbatim if the model returns nothing or the API call fails, so a visitor never sees a blank reply (max 1000).
Enable handoff to a human | On | When on, a visitor typing the trigger phrase stops the assistant and lights up the Team Inbox.
Trigger phrase | "talk to human" | The words that trigger the handoff anywhere in a message (max 60). The assistant is also told this phrase so it recognises the intent.
Handoff acknowledgement | "Sure — pulling in a teammate now." | The final message the assistant sends before going silent (max 1000).

## Step 5 · Train the agent (knowledge)

Add the material the assistant answers from. Each source is processed on the spot and shown in a ready (or failed) state with a rough size estimate. There are four kinds of source:

Kind | How it is read in | Limit
--- | --- | ---
Live URL | Fetches the public web page and pulls out the plain text (stripping out menus, scripts, and styling). Good for blog posts, FAQs, and short marketing copy. | Up to about 80,000 characters per page.
Free text | Paste a help-doc snippet or policy directly; stored as-is. | Up to 200,000 characters.
Q&A pair | One question with its standard answer, so the assistant sees both sides. Both fields are required. | Question max 5,000; answer max 20,000.
Document file | Upload a knowledge file (TXT, Markdown, CSV, LOG, HTML, PDF, or DOCX); its text is extracted and stored (PDF and DOCX have their text pulled out automatically), and the file is kept for your workspace. | 10 MB upload; content trimmed to about 200,000 characters.

Sources can apply to one assistant or to the whole workspace. A source can be deleted at any time, and uploaded files are removed when the source is deleted. The source list shows the kind, label, state, and size estimate per row.

> File formats. Accepted file types are TXT, Markdown (.md / .markdown), plain text, CSV, LOG, HTML (.html / .htm), PDF, and DOCX. PDF and DOCX files have their text extracted automatically. Any other file type returns a clear error.

> URL safety & limits. The URL reader only opens public web pages (http / https). It refuses anything else and blocks any address that points to a private, internal, or local network — so a link you add can't be used to reach internal systems. It waits up to 20 seconds and reads up to about 80,000 characters per page.

## Where the assistant is used

A ready chat assistant becomes the brain of a chatbot widget. When a visitor sends a message, the widget:

1. Saves the visitor's message to the conversation.
2. If the widget runs an assistant, generates a reply and saves it, then shows it to the visitor.
3. If anything goes wrong, shows the assistant's fallback message instead of an error.

The reply is built from your character brief, tone, language, and handoff phrase, plus your knowledge sources. It uses every ready source that applies to this assistant or the whole workspace, in order, up to 12,000 characters total. Recent conversation history (about the last 20 turns) is also included so replies stay on topic.

> Other channels. Today the chatbot widget is what uses chat assistants. The same persona and knowledge setup is designed to power other text-AI channels in future (for example, auto-replies to inbound WhatsApp messages).

## Managing assistants

- Duplicate an assistant — copies the persona, model settings, and all training sources into a new paused "(copy)". Useful for branching a persona, e.g. cloning a "Pricing concierge" into a Spanish variant.
- Delete an assistant — removes it from the list while keeping the underlying data.
- The list shows totals — all assistants, active assistants, total knowledge entries, and how many are ready — plus each row's provider, knowledge count, tone, and last-updated time, with name search.

## Cost cautions

> Every source you add is given to the assistant on each reply, so more (and larger) sources mean more cost per reply, up to the 12,000-character limit.

- Keep sources tight and relevant; a single good FAQ Q&A often covers more than a whole-site dump.
- Lean on Q&A pairs for the answers that matter most — they're compact and unambiguous.
- Prefer a smaller model (for example `gpt-4o-mini` or `gemini-2.5-flash-lite`) with a sensible reply length for high-traffic widgets.
- When using admin keys, replies count toward your workspace's monthly AI usage limit; hitting it blocks further replies until you upgrade or switch to your own key.

## Troubleshooting

Symptom | Likely cause & fix
--- | ---
The assistant does not appear in the widget picker | Only Live assistants can be selected. Set its status to Live in Step 1.
A URL source shows failed | The page was unreachable, returned an error, contained no text, or pointed to a private/internal address. Try the main public URL, or paste the text into a Free text source.
A file upload is rejected | Accepted file types are TXT, Markdown, plain text, CSV, LOG, HTML, PDF, and DOCX, max 10 MB. Convert or paste any other format into a Free text source.
The bot answers but ignores my content | Confirm the source is ready and applies to this assistant or the whole workspace. Remember the content is capped at 12,000 characters in order — trim or reorder if you exceed it.
Visitors get the fallback message a lot | That fires when the model returns nothing or errors. Check the admin provider key is valid and the model name is correct; review the monthly usage limit.
Handoff never triggers | Enable handoff in Step 4 and make the trigger phrase something visitors actually type (e.g. "talk to human").
The menu item is missing entirely | Your plan lacks the AI Chat Assistant feature. Upgrade or move to a plan that includes it.