> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soneka.africa/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Training: Build Chat Assistants Trained on Your Content
> Build text-based chat assistants in Soneka's five-step Smart Agent Builder, train them on URLs, files, free text, and Q&A pairs, then attach them to your chatbot widget.
**AI Training** is where you build *chat assistants* — text-based AI personas — and train them on your own content. A trained assistant becomes the brain of a [chatbot widget](/features/ai-agents) on your site or a Soneka auto-reply flow. You'll find it under **More → AI Training**.
A chat assistant is two things bundled together:
* A **persona and model setup** — greeting, character brief, tone, language, provider, model, reply length, creativity, fallback, and human-handoff rules.
* A set of **knowledge sources** — web links, files, free text, and Q\&A pairs the assistant answers from.
When a visitor chats, the assistant draws on your material to answer. Chat assistants are separate from the voice [AI Call Assistant](/features/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 → Knowledge**.
**Admin sets the provider keys once.** You don't paste an API key here. Your platform admin configures the OpenAI / Anthropic Claude / Google Gemini keys under **Admin → AI & API Keys**, and every chat assistant uses them automatically.
**Plan-gated.** AI Training needs the **AI Chat Assistant** plan feature — the same one the chatbot widget uses. Without it, a workspace can't create assistants.
## Creating a chat assistant
From the AI Training list, click **New assistant** (or open an existing one to edit).
Fill in Identity, Persona, Brain, Safety, and Knowledge. Use **Save draft** at any point — the persona and model settings save together.
In Step 5, add URLs, files, free text, or Q\&A pairs. Each is checked immediately and lands in a *ready* (or *failed*) state.
In Step 1, flip the roll-out status to **Live** so the assistant appears in the chatbot widget picker. Only Live assistants can be selected.
Head to your chatbot widget settings and pick the assistant 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, and handoff on. 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. |
### Tone options
| Tone | Style |
| ------------ | -------------------- |
| **Helpful** | Calm and on-point. |
| **Friendly** | Warm and casual. |
| **Formal** | Neutral and precise. |
| **Playful** | Light and witty. |
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, 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 | GPT, Claude, or Gemini families. |
| **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
| Provider | Example model |
| ------------- | --------------------------- |
| 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](/features/team-inbox). |
| **Trigger phrase** | "talk to human" | 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's read in | Limit |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **Live URL** | Fetches the public web page and pulls out the plain text (stripping menus, scripts, styling). Good for blog posts, FAQs, marketing copy. | Up to \~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 required. | Question max 5,000; answer max 20,000. |
| **Document file** | Upload a knowledge file (TXT, Markdown, CSV, LOG, HTML, PDF, or DOCX); text is extracted and stored, and the file is kept for your workspace. | 10 MB upload; content trimmed to \~200,000 characters. |
Sources can apply to **one assistant** or the **whole workspace**. Delete a source at any time — its uploaded file is removed with it. The source list shows kind, label, state, and size estimate per row.
**File formats.** Accepted types: TXT, Markdown (.md / .markdown), plain text, CSV, LOG, HTML (.html / .htm), PDF, and DOCX. PDF and DOCX 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 addresses that point to private, internal, or local networks — so a link you add can't be used to reach internal systems. It waits up to 20 seconds and reads up to \~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, saves it, and 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**. Every *ready* source that applies to this assistant or the whole workspace is included, 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** — 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** — removes the assistant 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 (e.g. `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 doesn't 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 types: TXT, Markdown, plain text, CSV, LOG, HTML, PDF, 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. 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. |