# Agent Settings Source: https://docs.chatref.ai/agents/agent-settings Set your bot's names, description, button label, dark mode, and the messages visitors see first. The **Settings** tabs hold the details that name your bot and shape what visitors see first. Everything here **saves automatically** – there's no Save button. This page covers the **General** and **Messages** tabs. Your bot's **model**, **personality**, and **system prompt** live in the **Playground**, not here. ## Where settings live Settings is split into tabs: | Tab | What it covers | | ----------------- | ---------------------------------------------------------------- | | **General** | Names, description, button label, dark mode (this page) | | **Appearance** | Colors, logo, widget icon, position | | **Messages** | Welcome message, opening bubble, suggested questions (this page) | | **Actions** | Buttons in the widget header | | **Display Rules** | Which pages the widget appears on | For everything except General and Messages, see the **Widget Customization** pages, starting with [Appearance](/widget/appearance). ## General The **General** tab holds your bot's identity and theme. | Setting | What it does | | ---------------- | ---------------------------------------------------------------------------------------------------------- | | **Agent name** | The name you see in your dashboard. Visitors never see it. | | **Bot name** | The name shown in the chat, like "Bean & Brew Assistant". | | **Description** | A short note for your own reference. Up to **200 characters**. | | **Button label** | The text on the chat launcher button. Up to **30 characters**. | | **Dark mode** | A toggle for a dark theme. **Off by default** – your bot starts in light mode. Turn it on for a dark look. | New bots start in **light mode**. Dark mode is off until you turn it on here. ## Messages The **Messages** tab controls the first things a visitor sees. | Setting | What it does | | ---------------------- | ------------------------------------------------------------------------------------------------ | | **Welcome message** | The greeting inside the chat when a visitor opens it. Up to **100 characters**. | | **First message** | The bubble that pops up on its own near the launcher to invite a chat. Up to **300 characters**. | | **Suggested messages** | Clickable starter questions that help visitors begin. | Make your suggested messages match what people actually ask. A coffee store might add "Where's my order?" and "How do subscriptions work?" so visitors get going in one tap. ## Next steps Set colors, your logo, the launcher icon, and where the widget sits. Set your bot's model, personality, and system prompt here. # Choosing a Model Source: https://docs.chatref.ai/agents/choosing-a-model Chatref is multi-model – pick the right AI model for each agent from four tiers, balancing cost and reasoning power. Chatref is **multi-model**: you can pick any AI model for each agent. Models are grouped into four tiers, from cheap-and-fast to deep-reasoning. You choose in the **Playground**, so each bot can run on the model that fits its job. The default model is **GPT-5.4 Mini**. It handles everyday support well, so most bots never need to change it. ## The four tiers Pricier tiers cost a little more per message but reason more deeply. Start low and move up only if your bot's answers need it. | Tier | Good for | Example models | | ------------ | ------------------------------------------ | ----------------------------------------------------------------------------------- | | **Budget** | Simple FAQs – the cheapest option | GPT-4o Mini, GPT-5.4 Nano, Gemini 3.1 Flash Lite, Llama 4 Maverick, DeepSeek V4 Pro | | **Standard** | Everyday support – the default | GPT-5.4 Mini (default), Kimi K2.6, Grok 4.3, Gemini 3.5 Flash | | **Premium** | Trickier questions that need more thinking | GPT-4.1, GPT-5.4, Gemini 3.1 Pro, Claude Sonnet 4.6 | | **Flagship** | The hardest reasoning | Claude Opus 4.8, GPT-5.5 | Models come from seven providers – **OpenAI**, **Anthropic**, **Google**, **xAI**, **Meta**, **DeepSeek**, and **Moonshot** – all available from the same dropdown. ## How cost works Your bot spends from your balance each time it answers, priced by the AI it uses. Higher tiers cost more per message than lower ones. A dental clinic answering routine "What are your hours?" questions does fine on a Budget or Standard model, while a SaaS app fielding deep technical questions may earn its keep on Premium. See [How Pricing Works](/billing/how-pricing-works) for the full picture. ## How to change the model Go to your agent and open the **Playground**. In the left panel, open the **Model** dropdown. Models are grouped by tier – pick the one you want. Click **Deploy** to save it. Test a few questions in the live preview to see how the new model answers. Start with the default. Only move up a tier if your bot's answers need deeper reasoning – it's the simplest way to keep costs down. ## Next steps Where you pick the model and test how it answers. See how each message is priced by the model and tokens used. # Creating an Agent Source: https://docs.chatref.ai/agents/creating-an-agent Create your first AI bot in Chatref – either from your website in seconds, or from scratch with a name. An **agent** is one AI bot for one website or use-case. You train it on your own content, give it a personality, and embed it on your site. One workspace can hold several agents – for example a **Support** bot and a **Sales** bot, each with its own knowledge and tone. There are two ways to create one. Most people start from their website. ## Option A – Start from your website (recommended) This is the fastest path. You paste your website address and Chatref builds the bot for you – its name, personality, welcome message, and starter questions – then begins reading your site into the **Knowledge Base**. Right after you sign up, Chatref asks **"What's your website?"** and shows a single box for your address. Enter your full address, like `https://yourstore.com`, and submit. While it works, a **Learning** preview shows your site being scanned. Chatref reads your homepage and fills in a name, personality, welcome message, and suggested questions. It also queues a crawl of your whole site into the Knowledge Base, so training starts on its own. You arrive in the **Playground** with training already running. From here you can test your bot and fine-tune it. You can always add, edit, or remove what Chatref generated. Nothing is locked in – the website scan is just a head start. ## Option B – Start from scratch Prefer to build it yourself? Create a blank agent with just a name. Chatref fills in sensible defaults so it works right away, and you shape it from there. Click **Agents** in the sidebar to see every agent in your workspace. Click **New Agent** and give it a clear name, like "Support" or "Sales". This name is only for you – your visitors never see it. Chatref creates the agent with a default personality, a starter system prompt, a welcome message, and a default model. It starts in **light mode**. Give each agent one clear job. A focused "Sales" bot trained on your pricing pages answers better than one bot trying to do everything. ## What happens next However you create it, your new agent opens to a dashboard with tabs for the **Playground** (shape and test it), **Sources** (its Knowledge Base), **Settings**, **Deploy**, and more. Your first stops are usually the Playground and the Knowledge Base. ## Next steps Shape your bot's personality and model, then test it live. Train your bot on your website, files, and text so it answers accurately. # The Playground Source: https://docs.chatref.ai/agents/playground Shape your bot's personality, model, and behavior on the left, then test it live on the right before you deploy. The **Playground** is where you shape and test your bot. It has two panels: on the left you set how your bot behaves, and on the right you chat with a live preview of your real widget. This is where your bot's **model**, **personality**, and **system prompt** are set – not on the **Settings** page. ## The two panels ### Left – configuration This panel controls how your bot thinks and answers. | Setting | What it does | | ----------------------- | ------------------------------------------------------------------------------------------ | | **Personality** | A dropdown of 11 ready-made personas – pick one or choose **Custom**. | | **System prompt** | Your own instructions for the bot (its role, tone, and rules). | | **Model** | The AI model your bot uses, grouped by tier (Budget, Standard, Premium, Flagship). | | **Temperature** | Creativity, from 0 to 1 (default **0.7**). Higher is more creative, lower is more focused. | | **Max response length** | A cap on how long each reply can be. | The 11 personality presets are: **AI Agent**, **Travel Agent**, **Customer Support**, **Sales**, **Product Specialist**, **Technical Support**, **Content Creator**, **Business Analyst**, **Educational Tutor**, **Marketing Strategist**, and **Research Assistant** – plus **Custom** to write your own from scratch. ### Right – live preview The right panel is a live preview of your **real** widget – the same one your visitors see, not a mockup. Type into it to test your bot's answers. Ask the questions your visitors will ask, then try a tricky one to see how it handles the edge. The preview shows your bot as it is right now. Changes you make on the left only reach the preview after you click **Deploy**. ## Shape, test, deploy Pick a **Personality** preset, or choose **Custom** and write your own **system prompt**. Adjust **Temperature** and **Max response length** if you want. Choose a **Model** from the tier-grouped dropdown. The default suits most bots – see [Choosing a Model](/agents/choosing-a-model). Chat with the live preview. Check that answers are accurate, on-brand, and the right length. Click **Deploy** to save your changes. The preview refreshes so you can confirm the new behavior right away. Re-test after every change. Tweak the prompt, **Deploy**, then ask the same question again to see the difference. ## Next steps Compare the four model tiers and pick the right one for your bot. Write clear instructions that give your bot its personality. # System Prompt Source: https://docs.chatref.ai/agents/system-prompt Give your bot its instructions and personality – pick a ready-made persona or write your own system prompt. The **system prompt** is your bot's instructions and personality. Your bot reads it before every conversation, so it shapes how every visitor is answered – the tone, what the bot covers, and what it avoids. You set it in the **Playground**. ## Two ways to start You have two starting points, both in the **Playground**: * **Pick a Personality preset** – choose from 11 ready-made personas (like **Customer Support** or **Sales**). Good when you want a solid bot fast. * **Write a custom System prompt** – choose **Custom** and write your own instructions. Best when you want full control over voice and rules. You can start from a preset and still add your own system prompt on top to tailor it to your business. ## What to include A clear system prompt usually covers four things: * **Role** – who the bot is and which business it speaks for. * **Tone** – how it should sound: warm, formal, playful, concise. * **What to do and avoid** – the topics it covers, and the ones it should not. * **When to suggest a human** – when to point the visitor to your team instead of guessing. Keep it specific and short. A few clear sentences beat a long, vague essay – your bot follows tight instructions more reliably. ## Example prompts **A coffee store support bot:** ```text theme={null} You are the support assistant for Bean & Brew, an online coffee store. Be warm, friendly, and concise. Help visitors with orders, shipping, subscriptions, and brewing tips. - Answer using our store information and policies. - If you are unsure or it's an account-specific issue, suggest emailing hello@beanandbrew.com. - Never invent prices, delivery dates, or stock levels. ``` **A dental clinic bot:** ```text theme={null} You are the front-desk assistant for Bright Smile Dental. Use a calm, reassuring, professional tone. Help visitors with services, hours, location, and what to expect at a visit. - Stick to the information on our website. - For booking or anything medical, suggest the visitor call the clinic to speak with our team. - Do not give medical diagnoses or advice. ``` ## Next steps Write your system prompt, then test it live before you deploy. Pair your prompt with the right model for the job. # Add Funds Source: https://docs.chatref.ai/billing/adding-funds Top up your Chatref balance so your bot keeps answering, and see how the free trial and expiry work. Chatref is **pay as you go** – you keep a balance in US dollars and your bot spends a little from it each time it works. When the balance runs low, you top it up. There's no monthly plan and nothing to cancel. ## Your free trial Every new account starts with **\$50 of free trial credit** so you can build and test your bot before paying anything. The trial credit is valid for **7 days**. The moment you make your first real top-up, your leftover trial credit stops expiring – so you keep it. Build and test during the trial. As soon as you go live and add funds, your remaining trial credit is yours to keep. ## How to top up In your dashboard, go to **Settings → Balance**. Your **Available Balance** shows at the top in dollars. Pick a preset – **$50**, **$100**, or **$250** – or type a custom amount. The minimum top-up is **$50**. Checkout opens through **Paddle**, our payment provider. After payment your balance updates automatically. You don't need to top up on a schedule. Add funds whenever your balance is running low – a healthy buffer keeps your bot answering without interruption. ## How expiry works Each top-up is valid for **1 year** from the day you add it. Your bot always spends the oldest credit first, so nothing expires before it's used unless your balance simply sits unspent for a year. If credit reaches its one-year mark unused, it's removed from your balance. Top up amounts you expect to use within the year to avoid losing any. ## Good to know | Topic | Detail | | ------------------------ | ------------------------------------------------------------ | | Free trial | \$50, valid for 7 days | | Trial after first top-up | Stops expiring – your leftover trial credit is yours to keep | | Minimum top-up | \$50 | | Preset amounts | $50, $100, \$250 – or a custom amount | | Payment provider | Secure checkout by Paddle | | Expiry | Each top-up is valid for 1 year | | Order used | Oldest credit is spent first | | Expired credit | Removed from your balance | ## Next steps See how pay as you go works and what uses your balance. Understand how cost is worked out and what each tier costs. # Existing Subscribers Source: https://docs.chatref.ai/billing/existing-subscribers If you signed up on an older monthly plan, nothing changes – here's how it relates to pay as you go. If you joined Chatref on an older **monthly plan** – the kind with a set number of message **coins** each period – you're all set. Nothing changes for you. Your plan keeps working exactly as it did, and your bot keeps answering as normal. ## What's different now New accounts use **pay as you go**: a **Balance** in dollars that you top up when it runs low, with no monthly fee. Your existing plan sits alongside this, untouched. | | Your current plan | Pay as you go | | -------------------- | ------------------- | --------------------------------------- | | Billing | Continues as before | Top up a dollar balance when you choose | | What changes for you | Nothing | – | ## Want to switch? You're welcome to move to pay as you go if you'd prefer a balance you top up instead of a monthly plan. New top-ups are handled through our secure payment provider, **Paddle**. Reach out to support and we'll help you make the switch. There's no rush and no pressure. Stay on your current plan as long as it suits you, or switch whenever you're ready. ## Next steps See how pay as you go works for new accounts. How top-ups, the free trial, and expiry work on pay as you go. # How Pricing Works Source: https://docs.chatref.ai/billing/how-pricing-works Understand how Chatref works out cost – you pay for the text the AI reads and writes, and pricier models cost a bit more. You pay for what the AI actually does. Every time your bot works, Chatref measures how much text it reads and writes, then takes a small amount from your **Balance**. Longer chats and smarter models cost a little more. ## What you pay for The AI reads and writes text in small pieces called **tokens**. A short reply uses few tokens, a long one uses more. Your cost depends on three things: * **How much it reads** – the visitor's question plus the parts of your Knowledge Base your bot looks at. * **How much it writes** – the length of the answer it sends back. * **Which model it uses** – higher tiers cost more per message than lower ones. So a quick "What are your opening hours?" costs far less than a long troubleshooting chat. You don't have to track tokens yourself – this is just what's happening behind the scenes. ## Cost by tier You pick a model for each agent from four tiers. Cheaper tiers are fine for most support. Only move up if your bot's answers need deeper reasoning. | Tier | Relative cost per message | Good for | | ------------ | ------------------------- | ------------------------------------------ | | **Budget** | Lowest | Simple, repeat FAQs | | **Standard** | Low | Everyday support | | **Premium** | Higher | Trickier questions that need more thinking | | **Flagship** | Highest | The hardest reasoning | The default model, **GPT-5.4 Mini**, sits in the Standard tier and handles everyday support well. See [Choosing a Model](/agents/choosing-a-model) to pick the right one for each bot. ## What gets charged A small amount comes out of your balance for each of these: * **Chat replies** – every answer your bot writes to a visitor. * **Knowledge-base training** – when your bot learns from your websites, files, and text. * **Auto-tagging** – when chats are sorted into topics for you. * **Insights** – when your dashboard summaries and tips are generated. * **Inbox summaries** – when a long chat is summarized for you. Each is priced the same way – by the text the AI reads and writes. Under the hood, costs are tracked in a tiny unit called **credits**, where 1,000 credits = \$1. You never need to count them – the **Balance** you see is always in dollars. Want to spend less? Start on the default model and add a tight, well-trained Knowledge Base. A travel agency with clear policy pages keeps answers short, and short answers cost less. ## Next steps Compare the four tiers and pick the right model per agent. Top up your balance and see how the free trial works. # Billing Overview Source: https://docs.chatref.ai/billing/overview Chatref is pay as you go – keep a balance in dollars and your bot spends a little from it whenever it works. Chatref is **pay as you go**. You keep a **Balance** in US dollars, and your bot spends a little from it whenever it works – answering chats, training on your content, and more. When the balance runs low, you top it up. There's no monthly plan and nothing to cancel. ## How it works Think of your **Balance** like prepaid credit on a phone. You add funds once, and the cost of each thing your bot does is taken out of that balance as it happens. You only pay for what your bot actually does. New accounts start with **\$50 of free trial credit**, so you can build and test your bot before paying anything. See [Add Funds](/billing/adding-funds) for how the trial and top-ups work. ## What uses my balance? A small amount comes out of your balance for each of these: * **Chat replies** – every answer your bot writes to a visitor. * **Training** – when your bot learns from your websites, files, and text. * **Auto-tagging** – when chats are sorted into topics for you. * **Insights** – when your dashboard summaries and tips are generated. * **Inbox summaries** – when a long chat is summarized for you. Each one is priced by how much text the AI reads and writes, so a short FAQ reply costs far less than a long back-and-forth. The model you pick also matters – see [How Pricing Works](/billing/how-pricing-works). There's no monthly fee and no subscription. You're never billed on a schedule – your balance only changes when your bot does something or when you top up. ## Keeping an eye on it Your current balance is always shown in your dashboard under **Settings → Balance**, in plain dollars. When it gets low, add funds and your bot keeps working without interruption. A coffee store doing light support can run for a long time on a single top-up. Check your balance now and then, and top up before it reaches zero so your bot never goes quiet. ## Next steps See how cost is worked out and what each tier costs. Use your free trial and learn how to top up your balance. # Key Concepts Source: https://docs.chatref.ai/concepts A plain-English glossary of the words you'll see across Chatref. Chatref uses a few terms over and over. This page explains each one in a sentence or two, so the rest of the docs make sense on the first read. ## The basics An **agent** is your bot – one AI chat assistant for one website or use-case. A coffee store might run a "Support" agent; an agency might run a separate agent for each client. ### Workspace Your account. A workspace can hold many agents, so you keep all your bots in one place – for example, a "Support Bot" and a "Sales Bot" side by side. ### Knowledge Base / Sources The content your bot learns from. You add **Sources** – your website, files, or text – under the Knowledge Base tab, and your bot answers from them. **Training** is the step where your bot reads a source and learns it. You add a source, Chatref processes it in the background, and the source shows as **Trained** when it's ready to use in answers. ## On your visitor's screen ### Widget The chat bubble visitors see on your site. They click it to open the chat and talk to your bot. You style it under **Settings** and add it with one line of code. ### Visitor vs Owner A **visitor** is a person on your website who chats with your bot. The **owner** is you – the person with the Chatref account who builds and manages the bot. ### Conversation One chat thread between a visitor and your bot, from the first message to the last. Every conversation is saved so you can read it later. ## Reading and steering chats ### Inbox Where you read every visitor conversation. Pick a chat on the left to see the full transcript on the right. **Human handoff** lets you step in as a real person. It's **owner-initiated** – your bot never hands off on its own. When you send the first human reply, the bot pauses for that chat; click **Return to AI** to let it resume. Turn it on per agent with **Allow human handoff**. ### Tags & Engagement **Tags** are labels on a conversation, added by you or automatically. Each chat also gets an **engagement** type: | Engagement | What it means | | ---------- | -------------------------------------------------------------------------- | | QUESTION | The visitor asked a real question or had a problem. | | NAVIGATION | The visitor tapped a menu, suggestion, or topic – routing, not a question. | | NONE | A greeting, thanks, test, or gibberish. | Only QUESTION chats count toward your answered vs couldn't-answer rate, so casual browsing never skews your numbers. ### Insights Your analytics dashboard. It shows what your bot did over the last 7 or 30 days – how many chats it had, what it answered, what it couldn't, and what to improve next. ## Behind the answers ### Model The AI brain that writes your bot's replies. You pick one per agent from four tiers, and pricier tiers cost a little more per message. | Tier | When to use it | | -------- | ------------------------------------------------ | | Budget | Simple, high-volume support at the lowest cost. | | Standard | A balanced default for most bots. | | Premium | Trickier questions that need stronger reasoning. | | Flagship | The most demanding, high-stakes conversations. | The default model is **GPT-5.4 Mini**. Models come from OpenAI, Anthropic, Google, xAI, Meta, DeepSeek, and Moonshot. ### Balance The money your account holds, shown in US dollars. Chatref is **pay as you go**: your balance is drawn down a little each time your bot works – answering chats, training, tagging, and Insights. You **top up** when it runs low. New accounts start with **\$50 of free trial credit**. ## Next steps Put these pieces together and get a live bot in minutes. Create your first bot and explore its dashboard tabs. # API / Webhook Actions Source: https://docs.chatref.ai/custom-actions/api-webhook-actions Let your bot call your own API mid-chat – no visitor form – and use the response to keep answering. Use this when your bot needs a live answer from your own system mid-chat – an order status, a price, a stock count. An API / Webhook action lets your bot call your own API in the middle of a conversation. There's no form for the visitor to fill in. The bot gathers what it needs from the chat, calls your endpoint, and uses the response to keep answering. A travel agency could check live prices this way. An online coffee store could add a "Check order status" action that looks up an order by its number. ## How it works 1. The visitor asks something your bot can't answer from its training alone – like "Where's order 4172?". 2. The AI fills in the request from the chat (here, the order number) and calls your endpoint. 3. Your API replies with the data. 4. Chatref feeds that reply back to the bot, which uses it to finish its answer – "Order 4172 shipped yesterday and arrives Friday." ## What you configure * **Method** – the HTTP method, defaulting to **POST**. You can also pick GET, PUT, PATCH, or DELETE. * **URL** – your API endpoint. * **Request Body Fields** – the inputs the AI fills from the chat. Each field has a **Field Name**, a type, whether it's **Required**, and a **Description** that tells the AI what to put there. These become the inputs the bot supplies when it calls your API. * **Headers** – extra header keys and values. Put auth tokens here. In your agent's dashboard, go to the **Actions** tab and create a new action. Pick **API / Webhook** as the action type. Name the action, like "Check order status", and write a description that tells the AI when to call it – for example, "Use this to look up an order by its order number." Choose the **Method** (default **POST**) and enter your endpoint **URL**. Click **Add Field** for each input the AI should send – for an order lookup, one field named `orderNumber`. Add a **Description** for each so the AI knows what value to fill in. Click **Add Header** for any auth tokens or content type your endpoint needs, then save. Your bot can now call your API whenever the chat matches your description. Secure your endpoint. The bot can call it with values it gathered from a public chat, so your API should validate every request and only return data that's safe to share. Keep secrets – API keys, tokens – in **Headers**, never in the URL or a request field. ## Seeing calls Each call is recorded in the **Action Submissions** table – see [Custom Actions](/custom-actions/overview) for how to read it. GET lookups are not recorded; other methods are. ## Next steps How actions work and the three types. Collect details from the visitor instead. Show a one-tap button in the chat. Train your bot on your own content. # Button Actions Source: https://docs.chatref.ai/custom-actions/button-actions Give your bot a one-tap button it can show in the chat, then record the click and call your webhook. A button action gives your bot a single, clear button it can show in the chat – like a "Start my return" button for an online coffee store. The AI decides when to show it; when the visitor clicks, Chatref records the click and calls a webhook you choose. ## What you configure * **Button Label** – the text on the button, e.g. "Start my return". * **URL** (optional) – an external link to open when clicked, e.g. your returns page. * **Style** – the button's look (its variant), so it fits the moment. * **Confirmation Message** (optional) – a short "Are you sure?" prompt shown before the action runs. Leave it empty for no confirmation. * **Payload** (optional) – extra data sent with the click, so your webhook knows the context. ## Create a button action In your agent's dashboard, go to the **Actions** tab and create a new action. Pick **Button** as the action type. Name the action, like "Start a return", and write a description that tells the AI when to show it – for example, "Use this when a visitor wants to return an order." Enter the **Button Label** and pick a **Style**. Optionally add a **URL** to open, a **Confirmation Message**, and a **Payload**. Enter the **Webhook URL** the click should call, plus any **Headers** your endpoint needs. Save the action. Your bot can now show this button when the chat matches your description. ## What happens on click When a visitor clicks the button, Chatref records the click as a submission and calls your webhook (sending the payload, if you set one). If you added a URL, it also opens that link in a new tab. Keep labels short and action-led – 2 to 4 words like "Start my return" or "View plans". Have the bot explain the choice in its message, then show one clear button rather than several at once. ## Seeing clicks Every click is saved in the **Action Submissions** table – see [Custom Actions](/custom-actions/overview) for how to read it. ## Next steps How actions work and the three types. Collect several details instead of one click. Let the bot call your API directly. Read the chats where the button was shown. # Form Actions Source: https://docs.chatref.ai/custom-actions/form-actions Let your bot show a form inside the chat to collect details, then save them and send them to your webhook. A form action lets your bot show a short form right inside the chat. The visitor fills it in – name, email, a message – and submits without leaving the conversation. A dental clinic might add an "Open a support ticket" form, or a SaaS app a "Book a demo" form. When the visitor submits, two things happen: Chatref **saves the entry** so you can read it later, **and** sends it to a **webhook URL** you choose, so it can land in your own tools. ## What you configure * **Form title and description** – a heading and a line of context shown above the fields. * **Fields** – the inputs the visitor fills in (see below). * **Submit Button Text** – the label on the submit button, e.g. "Send request". * **Webhook URL** – where Chatref sends the submission. * **Headers** (optional) – extra header keys and values your endpoint needs, such as an auth token. * **Retries** (optional) – how many times Chatref retries if the webhook fails. Each field has its own settings: | Field setting | What it does | | --------------- | --------------------------------------------- | | **Name** | The internal key for the value (e.g. `email`) | | **Label** | What the visitor sees (e.g. "Your email") | | **Type** | The kind of input – see the table below | | **Required** | Whether the visitor must fill it in | | **Placeholder** | Faint hint text inside the field | ## Supported field types | Type | What it collects | | ------------ | --------------------------------------------------------- | | **text** | A single line of text – names, short answers | | **email** | An email address, checked for valid format | | **tel** | A phone number | | **number** | A numeric value – quantity, order number | | **textarea** | A longer, multi-line message | | **select** | A drop-down – you must add the **options** to choose from | | **date** | A date, picked from a calendar | A **select** field needs at least one option. Add the choices when you set up the field, or the drop-down will be empty. ## Create a form action In your agent's dashboard, go to the **Actions** tab and create a new action. Pick **Form** as the action type. Give the action a clear name like "Book a demo", and a description that tells the AI when to fire it – for example, "Use this when a visitor wants to book a demo." Click **Add Field** for each input. Set its **Name**, **Label**, **Type**, and whether it's **Required**. For a demo form you might add Name (text), Work email (email), and Preferred date (date). Enter the **Submit Button Text**, then the **Webhook URL** where submissions should go. Add any **Headers** and a **Retries** count if your endpoint needs them. Save the action. Your bot can now show this form whenever the conversation matches your description. Offer a form at the right moment – usually after the bot has answered the visitor's first questions and they want to follow up with your team. The clearer your description, the better the AI's timing. ## Seeing submissions Every form submission is saved in the **Action Submissions** table – see [Custom Actions](/custom-actions/overview) for how to read it. ## Next steps How actions work and the three types. Add a one-tap button instead of a form. Let the bot call your API directly. Read the chats where the form was shown. # Custom Actions Source: https://docs.chatref.ai/custom-actions/overview Make your bot do things, not just answer – with forms, buttons, and API calls it fires on its own. Custom Actions turn your bot from a question-answerer into a doer. You give the bot a few tools – like a contact form or a "Start my return" button – and during a chat it decides on its own when to use them. You don't script the conversation; you describe each action and let the AI pick the right moment. ## How an action works You create an action with two key things: * A **name** – what the action is, e.g. "Open a support ticket". * A **description** – a plain-English note that says *when to use it*, e.g. "Use this to collect a support request." At chat time, the AI reads that description and fires the action when a visitor's message matches it. A travel agency might add a "Request a quote" form; the bot shows it the moment a visitor asks about pricing. The **description** is what tells the AI when to use the action. Write it clearly and start with "Use this to…" – for example, "Use this to collect a support request." A vague description means the bot fires the action at the wrong time, or never. ## The three action types There are exactly three kinds of action you can build. The bot shows a form inside the chat. The visitor fills it in – name, email, a message – and submits without leaving the conversation. The bot shows a clickable button in the chat, like "Start my return". One tap triggers the action. The bot calls your own API in the middle of a chat – no visitor form – and uses the answer to keep replying. Forms and buttons appear right inside the chat for the visitor to use. An API / Webhook action runs quietly in the background. ## Where actions live Open an agent's dashboard and go to the **Actions** tab. From there you can create an action, edit it, turn it on or off, or delete it. Each action can be a Form, a Button, or an API / Webhook. ## Seeing what your bot did Every time an action runs – a form is submitted, a button is clicked, or your API is called – Chatref records it in the **Action Submissions** table on the **Actions** tab. Each row has five columns: **Submitted At**, **Action**, **Status**, **Completed At**, and **Details**. The **Status** tells you how the call went: | Status | What it means | | ------------ | ----------------------------------------- | | **PENDING** | Recorded, waiting to reach your webhook | | **SUCCESS** | Your endpoint received it and replied OK | | **FAILED** | The call to your endpoint did not succeed | | **RETRYING** | Chatref is trying again after a failure | Open **Details** on any row to see the data that was submitted, your webhook's response, and the retry count. Booking a meeting or scheduling a call is not a built-in tool. You build it yourself with a **Form action** (collect the visitor's preferred time and details) or an **API / Webhook action** (call your own calendar system). ## Next steps Collect details from visitors inside the chat. Add a one-tap button the bot can show. Let the bot call your own API mid-chat. Read the chats where your actions ran. # Allowed Domains Source: https://docs.chatref.ai/deploy/allowed-domains Lock your widget so it only runs on your own sites by keeping an allow-list of domains. **Allowed Domains** is an allow-list of the sites where your widget is allowed to run. It stops someone from copying your script and loading your bot on a site that isn't yours. If the list is **empty**, the widget works on **any** site. The moment you add even one domain, the widget runs **only** on the domains you list. ## How matching works * **Subdomains are included automatically.** Adding `example.com` also covers `shop.example.com` and `help.example.com`. * **Wildcards** work too. Use `*.example.com` to match every subdomain. * If a site **isn't** on the list, the widget won't load there at all. For a travel agency, adding `travelco.com` covers the main site plus `book.travelco.com` – one entry, every subdomain. ## Add a domain In your agent's dashboard, open the **Deploy** page and find the **Allowed Domains** section. Type your domain – for example `example.com` or `*.example.com` – and add it to the list. Repeat for each site that should run the widget. Save the list. From now on the widget loads only on the domains you added. Before you embed the widget on a new domain, add that domain here **first**. If it isn't on the list, the widget will be blocked and won't load on that site. ## Next steps Paste your script tag and put your bot live on your site. Show different agents on different pages from a single workspace script. # Embed on Your Website Source: https://docs.chatref.ai/deploy/embed-on-website Put your bot live on your site with a single script tag, and learn where to paste it. Putting your bot live takes one line of code. You copy a script tag from the **Deploy** page and paste it into your site. The chat bubble then appears on every page automatically – no plugin, no developer needed. ## Add the script tag In your bot's dashboard, open the **Deploy** page. You'll see a ready-to-use script tag with your bot's key already filled in. Click **Copy** to put the snippet on your clipboard. It looks like this: ```html theme={null} ``` Your real `apiKey` is already in the snippet on the Deploy page – the one above just shows the shape. It loads your bot. Paste the script into your site's HTML, just before the closing `` tag. The `async` attribute keeps your page fast – the bot loads in the background. Save and publish. The bubble now shows on every page. The first time the widget loads on your live site, your bot is marked as **deployed**. Tested your bot but haven't embedded it yet? Chatref sends you a friendly reminder email with the snippet, so the code is always one click away when you're ready to go live. ## Where to paste it You only paste the script once. Where it goes depends on your site builder, but the rule is the same everywhere – put it in the page `` (or a "header scripts" / "custom code" box) so it loads on every page. | Platform | Where to paste | | -------------------- | ----------------------------------------------------------------------------------------- | | **WordPress** | Your theme's header, or a header-scripts plugin (e.g. a "headers and footers" plugin) | | **Shopify** | **Online Store → Themes → Edit code**, then paste into `theme.liquid` inside the `` | | **Webflow / Framer** | Site-wide custom code, in the **Head** section of your project settings | | **Plain HTML** | Directly in your HTML file, just before `` | If your builder only offers a single "custom code" box, paste the script there. Site-wide head code is what makes the bot appear on every page at once. ## Rotating your key If your key is ever shared by mistake, you can rotate it from the **Deploy** page. Rotating creates a **new key** and disables the **old one** right away. After you rotate, your old snippet stops working. Update the script tag **everywhere you pasted it** – every site, theme, or page – with the new key, or the bot will stop loading there. ## Next steps Use one workspace script to show different agents on different pages. Allow only your own domains to load the widget. # Multi-Agent Routing Source: https://docs.chatref.ai/deploy/multi-agent-routing Run several agents from one workspace with a single script, and show the right agent on each page. Have more than one agent? You can run them all from a **single script tag** instead of pasting a different snippet on every page. Each agent's **Display Rules** decide which pages it shows on, and one default agent covers everything else. A SaaS app, for example, might put a **Sales** agent on `/pricing` and `/plans`, and a **Support** agent everywhere else – all from the same one line of code. ## How it works Instead of one agent's `apiKey`, the workspace script uses a **workspaceKey**. That one key loads your whole workspace, then Chatref picks which agent to show on each page: * It checks every agent's **Display Rules** against the page URL. * If a page matches an agent's rules, that agent shows. * If no agent matches, your **default** agent shows. ## Set it up On the **Deploy** page, switch to the **Multi-Agent Routing** tab and copy the workspace script. It uses a `workspaceKey` instead of one agent's `apiKey`: ```html theme={null} ``` Paste it once into your site, just before `` – the same place as a single-agent script. See [Embed on Your Website](/deploy/embed-on-website) for where that is on each platform. Open each agent and set its **Display Rules** to the pages it should appear on. For the example above, the Sales agent matches `/pricing` and `/plans`. Choose one agent as the **default**. It shows on every page that no other agent's rules match – so the Support agent covers the rest of the site. Start with two agents and one default, then add more as you grow. Keep the default agent broad so no page is ever left without an agent. ## Next steps Control which pages each agent shows on with URL match rules. Where to paste the script on WordPress, Shopify, Webflow, and more. # Conversations Source: https://docs.chatref.ai/inbox/conversations Read every chat your bot has with visitors in the Inbox, in real time, and reply as a human when you need to. The **Inbox** is where you read every chat your bot has with visitors. It has two panels: the **conversation list** on the left, and the full **transcript** of the selected chat on the right. New messages land here as they happen – you never have to refresh. ## What each chat shows Pick a chat in the list and the transcript opens on the right – every message, in order, from the first **Welcome** bubble to the latest reply. Alongside the transcript you can see useful context about that visitor: | You'll see | What it tells you | | -------------------------- | -------------------------------------------------------------------------------------------- | | **Captured email / phone** | The contact details the visitor shared during the chat – your leads. | | **Unread status** | Chats you haven't opened yet stand out in the list, so the Inbox works as a to-do list. | | **Tags** | Colored labels – some added by your bot automatically, some by you. See [Tags](/inbox/tags). | A travel agency watching for new bookings can scan the list for chats with a **captured email** and an unread marker – those are fresh leads to follow up on. ## Find and read a chat From your agent's dashboard, open the **Inbox** tab. Every chat for that agent appears in the list on the left, newest activity first. Click any chat in the list. Its full transcript opens on the right, and the chat is marked read for you. Scroll the transcript to see the whole back-and-forth between the visitor and your bot. New messages on an open chat appear live, with no refresh. ## Reply as a human You don't have to leave every chat to the bot. When a visitor needs a real person, you can step in and reply yourself. Select the chat in the Inbox so its transcript is on the right. Use the reply box below the transcript and send your message. The chat shows a **Support agent joined** note, and your bot pauses for that one chat. Click **Return to AI** to let your bot take over that chat again. Stepping in is **owner-initiated** – your bot never hands a chat off on its own. You turn it on per agent first; see [Human Handoff](/inbox/human-handoff) for the full setup and flow. ## Close and reopen Each chat has **Close** and **Reopen** actions. Close a chat once it's handled to keep your list tidy; reopen it later if the visitor comes back or there's more to do. ## Next steps Turn on human handoff and learn exactly how pausing your bot works. See how chats get labeled automatically and how to add your own tags. # Human Handoff Source: https://docs.chatref.ai/inbox/human-handoff Step into any chat and reply as a real person – your bot pauses until you hand it back. Sometimes a visitor needs a real person. **Human handoff** lets you step into a chat and reply yourself, while your bot keeps handling every other chat as usual. ## How it works Handoff is **owner-initiated** – you decide when to step in. * Your **first human reply** in a chat pauses the bot for that one chat. * The visitor sees a **"Support agent joined"** note, so they know a person took over. * Your bot will not answer that chat again until you click **Return to AI**. While you're handling a chat, the AI stays **paused for that chat only**. Other chats keep getting bot replies as normal. Nothing resumes for that one chat until you click **Return to AI**. The AI never escalates on its own. There is no auto-handoff and no "talk to a human" trigger that pauses the bot for you – stepping in is always your choice. This changed: older versions let the bot escalate automatically. ## Turn it on and take over Open your agent's **Settings** and turn on **Allow human handoff**. This is off by default and is set per agent. In the **Inbox**, pick the chat you want to step into so its transcript is on the right. Type in the reply box and send. Your first reply pauses the bot for this chat, and the visitor sees the **Support agent joined** note. Once the visitor is sorted, click **Return to AI**. Your bot resumes handling that chat. A dental clinic might step in to confirm an appointment time, then click **Return to AI** so the bot can answer the visitor's follow-up questions about parking or opening hours. ## Next steps Read chats, see captured contact details, and close or reopen a chat. Label the chats that tend to need a human so they're easy to spot. # Tags Source: https://docs.chatref.ai/inbox/tags Organize and label your chats with automatic and manual tags, and learn how engagement types feed your Insights. **Tags** are short labels that organize and describe your chats. They let you scan the Inbox and instantly see which chats are about pricing, which are bug reports, and which are just someone saying hello. ## Where tags come from Tags arrive two ways, and you can mix both: Your bot tags chats for you. Shortly after it replies, it reads the recent messages and applies any labels that fit – you don't have to lift a finger. You create your own tags and apply them to chats yourself, for the categories that matter to your business. ## Engagement types On top of your own tags, Chatref sorts **every** chat into one engagement type. This is automatic and always on. It answers a simple question: did the visitor actually ask for something? | Type | What it means | Example | | -------------- | ------------------------------------------------------------------ | ------------------------------------ | | **QUESTION** | The visitor asked a real question or raised a problem. | "Do you ship to Canada?" | | **NAVIGATION** | They just tapped a menu item or a quick option – no real question. | Tapping a **Track my order** button. | | **NONE** | A greeting, a thanks, or a test message. | "hi", "thanks!", "testing" | ### Why it matters Only **QUESTION** chats count in your Insights **answered vs couldn't answer** rate. A coffee store owner doesn't want a hundred "hi" messages dragging down the score – so greetings and menu taps are left out, and the rate reflects only the chats where someone genuinely needed an answer. Insights uses engagement types to show how often your bot actually answered. ## Create a manual tag From your agent's dashboard, open the **Tags** tab. Click to create a tag, then give it a short, plain-English name – for example **Refund request** or **Booking question**. Write a clear description of the kind of chat this tag is for. Your bot reads this description to decide which chats to label automatically. Save the tag. From now on, new chats that match are labeled for you. ## Re-tag past conversations New tags apply to chats going forward. If you want a tag applied to older chats too, you can re-tag your past conversations in one action from the Tags screen. Tagging uses a small amount of your **Balance**, like other AI tasks – the bot reads the chat to label it. Tagging new chats as they arrive is light; re-tagging a batch of past conversations costs a bit more, because every older chat is read again. ## Next steps See where tags appear and how to read and reply to chats. Track your answered vs couldn't-answer rate, built from QUESTION chats. # Answered vs Couldn't Answer Source: https://docs.chatref.ai/insights/answered-vs-couldnt Find the questions your bot can't handle yet and learn the loop to fix them. This is the most useful view in Insights. It shows you, in plain language, what your bot is good at – and exactly where it falls short. Better still, it tells you how to close each gap. You'll find two lists side by side. ## What your bot answered The first list is **questions your bot fully answered on its own** – the ones it handled without any help. This is a quick confidence check that your training is paying off. Each row links to that chat in your Inbox, so you can read how your bot replied. If it's empty, your bot hasn't fully answered anything on its own yet. Give it more content and a little time. ## Questions your bot couldn't answer The second list is **questions your bot couldn't answer**. Instead of a long, messy list, similar questions are grouped into short **themes** – a few words each – with the **most common theme first**. So a coffee store might see "international shipping" at the top, meaning lots of visitors asked about it and the bot came up short. Every theme has a **How to fix** tip. The advice is always the same simple move: Add that topic to your **Knowledge Base** and retrain, so your bot can answer questions like it next time. ## The improvement loop Fixing your bot is a short, repeatable loop. Run it whenever a new theme climbs the list. Open Insights and look at the top of the **couldn't answer** list. The theme at the top is the one hurting you most. Go to the **Sources** tab and add what's missing – a **Website** page, a **File**, or a quick **Text** note. A coffee store would add its shipping page or paste a short shipping FAQ. Let the new source finish training. You'll get an email when the batch is done, and your bot can then answer from the new content. Come back to Insights in a day or two. That theme should fall down the **couldn't answer** list – or disappear as your bot starts handling it. Tackle the most frequent theme first. It's at the top of the list for a reason – fixing it helps the most visitors with the least effort. ## Next steps The three ways to train your bot on new content. What "answered" and "couldn't answer" really measure. # Every Number Explained Source: https://docs.chatref.ai/insights/metrics-explained A plain-English guide to every stat in your Insights dashboard and what counts as answered. Insights shows a row of stat cards at the top. Here's what each one means, in plain English. None of them need any setup – your bot fills them in as visitors chat. ## The stat cards | Metric | What it means | | -------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Conversations** | Total chats in the time range. Every visitor who opened your bot and said something. | | **Question rate** | The share of chats where the visitor actually asked something. The rest were greetings, menu taps, or idle browsing. | | **Answered** | Of those questions, how many your bot **fully answered on its own**. Higher is better. | | **Couldn't answer** | Questions your bot failed to handle. Lower is better – this is your fix-it list. | | **Handed to humans** | Chats where you stepped in and took over from your bot. | | **Leads captured** | Chats where your bot collected an email or phone number. | | **Happy ratings** | The share of thumbs-up out of all the chats visitors rated. | **Question rate** matters because not every chat is a question. A dental clinic's bot gets plenty of "hi" and "thanks" – those shouldn't count for or against it. Question rate tells you how many chats had a real ask behind them. ## What counts as answered? A chat counts as **fully answered on its own** only when all three of these are true: * The visitor asked a **real question** – not a greeting, a menu tap, or small talk. * Your bot **resolved it** – the question was actually handled by the end of the chat. * It was **not handed to a human** – your bot did it on its own. Whether the question was answered is judged by the **AI reading the chat** (semantic) – not by the chat's status. A closed or reopened chat doesn't change the verdict; what was actually said does. This keeps the score honest. The **answered** and **couldn't answer** rates are always measured against questions only – never against every chat. So a quiet day full of "hello" and window-shopping never makes your bot look worse than it is. ## About the trend arrows Each stat card shows a small **arrow**. It compares the current period to the period just before it – the last 7 days against the 7 before, or the last 30 days against the 30 before. An up arrow on **Answered** is good news; an up arrow on **Couldn't answer** means more questions are slipping through. ## Next steps Turn the "couldn't answer" number into a clear fix-it list. See how the whole dashboard fits together. # Insights Overview Source: https://docs.chatref.ai/insights/overview See how your bot performed over the last 7 or 30 days, what needs attention, and what to fix next. **Insights** is a dashboard for each agent that shows how your bot is doing. It turns every chat into clear numbers and a short, action-first list – so you know what's working and what to fix next. Pick the time range with the **7 days / 30 days** toggle at the top. Everything below updates to match. Give your bot a day or two of real chats before you expect much here. Insights fills up as visitors talk to it, so a brand-new agent looks quiet at first. ## How the page reads Insights is laid out top to bottom, so you read it action-first – fix problems, then check the numbers, then dig into the detail. ### What needs attention The first thing you see is up to **5 issues** the AI picked out for you – things like a topic visitors keep asking about that your bot can't answer, or a run of unhappy ratings. Each item has a **view chats** link that opens those exact conversations in your Inbox. A quiet day reads "Nothing urgent today." ### The numbers Next come the **stat cards** – total chats, how many were real questions, how many your bot answered, and more. Each card shows a trend arrow comparing this period to the one before. Below the cards, two charts plot **conversations over time** and **answered vs couldn't answer** so you can see the movement. ### Answered vs couldn't answer This is the most useful part for improving your bot. It's an action list with two sides: questions your bot **answered well**, and questions it **couldn't answer** yet – grouped into short themes, most common first. Each unanswered theme comes with a tip on how to fix it. ### Where it's happening The detail section breaks chats down by **topic**, **channel**, **country**, and **sentiment** (how happy visitors were), plus a busy-times grid showing when people chat most. A travel agency might learn most questions land on weekends. ## Things to try Alongside the attention list, the AI suggests up to **3 things to try** – ranked, practical ideas to improve your bot. For example, "Add a refunds page to your Knowledge Base." Treat them as a short to-do list. The attention list and things to try are written by AI, so generating them uses a small amount of your **Balance**, like other AI tasks. See [How Pricing Works](/billing/how-pricing-works). ## Your daily insights email You also get a short **daily insights email** covering all your agents. It sums up yesterday in a few lines: what needs attention, a handful of key numbers, and one thing to try. It's a quick way to keep an eye on things without opening the dashboard. ## Next steps What each stat means, in plain English. Find the questions your bot misses and fix them. # Welcome to Chatref Source: https://docs.chatref.ai/introduction Put a smart AI chat assistant on your website that answers visitors using your own content. Chatref lets any business put a smart AI chat assistant on its website. Your bot answers visitors using your own content – your pages, files, and FAQs – so the answers always match your business. It's built for people who run the business, not the code. Store owners, SaaS founders, agencies, and clinics can set up a bot in minutes – no developers and no plugins to install. ## Find your way around Set up your bot – one per website or use-case – and give it a name. Feed it your website, files, and text so it answers from your own content. Match the chat bubble to your brand with colors, an icon, and a logo. Add your bot to your site with a single line of code. See every visitor conversation in your Inbox and reply as a human when needed. Watch what your bot answered, what it couldn't, and where to improve. ## How Chatref works Your bot follows a simple loop. You train it, test it, deploy it, then keep improving it as you learn what your visitors ask. Point Chatref at your website and add any files or text. Your bot learns your content so it can answer questions about your business. Try your bot in the **Playground** – a live chat that uses your real settings. Ask it questions and adjust the personality or AI model. Copy the one-line script from **Deploy** and paste it into your site. Your bot goes live for every visitor. Read real chats in the **Inbox** and check **Insights** to see what to add to your Knowledge Base next. ## Try it free Every new account starts with **\$50 of free trial credit**, so you can build, train, and test before paying anything. Chatref is [pay as you go](/billing/overview) – no monthly plan, nothing to cancel. ## Next steps Go from sign-up to a live bot on your website in minutes. Learn the handful of words that make Chatref click. # Knowledge Base Overview Source: https://docs.chatref.ai/knowledge-base/overview Learn how the Knowledge Base trains your bot and the three ways to add content. Your bot only knows what you teach it. The **Knowledge Base** is where you add that knowledge – your website pages, your documents, and your own written notes. The more you add, the more questions your bot can answer. ## The three ways to train your bot Pick whichever fits the content you have. Most owners use a mix of all three. Paste a URL and Chatref crawls your site, learning the text on every page. Upload documents like PDFs and spreadsheets, and Chatref reads the text. Paste a title and content directly – great for a quick FAQ or policy. Training uses a small amount of your **Balance**, priced by how much content the AI reads, like other AI tasks. See [How Pricing Works](/billing/how-pricing-works). ## How answering works When a visitor asks something, your bot searches your sources for the closest match and writes its answer from what it finds. It does not make things up. If your bot can't find the answer in your sources, it says so politely instead of guessing. Those moments also show up in your [Insights](/insights/overview), so you can see exactly what to add next. A coffee store that adds its shipping page, a returns policy, and a short FAQ will cover most of what visitors ask – often before any real chat happens. ## Where to manage it Open your agent and go to the **Sources** tab. From there you can: * Add new content from **Websites**, **Files**, or **Text** * See the training status of every source * Retry a source that failed, or delete one you no longer need ## Keep it up to date Your bot answers from what you've trained it on, so retrain when your content changes. Updated your prices or shipping times? Add the new page or text and your bot stays accurate. Outdated sources lead to outdated answers. ## Next steps Crawl a whole site, or a single page, into your Knowledge Base. Upload manuals, price lists, and policies. Paste an FAQ or policy in seconds. See what's trained and retry anything that failed. # Training Status Source: https://docs.chatref.ai/knowledge-base/training-status Track when your sources finish training, retry failures, and read the training-complete email. Every source you add is queued and read by a background worker before your bot can use it. The training status tells you where each source is. You'll find it next to each source on the **Sources** tab. ## What each status means | Status | Meaning | | ------------ | ------------------------------------------------- | | **Trained** | Done – your bot can answer from this source now. | | **Training** | In progress – Chatref is reading the content. | | **Pending** | Waiting in the queue to be read. | | **Failed** | Something went wrong – the source wasn't learned. | ## Retry or remove a source Each source has its own controls on the **Sources** tab: * **Retry** a source that shows **Failed** to send it through training again. A retry helps when the failure was temporary – say, your site was briefly down during a crawl. * **Delete** any source you no longer want. You'll be asked to confirm first. If a source keeps failing, the content may not be readable as-is. For a scanned PDF, retype the key parts as a [Text source](/knowledge-base/training-with-text) instead. ## The live training banner Open the [Playground](/agents/playground) while sources are training and you'll see a live banner at the top. It updates on its own – amber while training is in progress, green when it finishes, and red if any source failed. The banner links straight back to the **Sources** tab so you can check or retry. ## The training-complete email You don't have to sit and watch. When a batch of sources finishes training, Chatref sends you **one email** so you know it's ready. Add ten files at once and you still get a single email – not ten. The email comes in one of three flavors: | Outcome | What the email says | | -------------- | ------------------------------------------------------------------------- | | All trained | Your bot is trained and ready – with a link to test it in the Playground. | | Mostly trained | It's ready, but a few sources need attention so you can retry them. | | All failed | It couldn't finish training – with a link back to your **Sources** tab. | A later batch sends its own email. So if you train your site today and upload a file next week, you get one email each time – one per batch that finishes. Got the "a few sources need attention" email? Open the **Sources** tab and **Retry** the failed sources. Once they show **Trained**, your bot can answer from them too. ## Next steps Ask a question about your newly trained content in the Playground. Train with websites, files, or text from the Knowledge Base. # Training with Files Source: https://docs.chatref.ai/knowledge-base/training-with-files Upload documents like PDFs and spreadsheets so your bot can answer from them. Have your answers in documents already? Upload them and Chatref reads the text, so your bot can answer from it. This is great for manuals, price lists, and policies you keep as files. ## Supported file types Upload any of these: | Type | Formats | | ------------ | ------------------- | | Documents | `.pdf` `.docx` | | Spreadsheets | `.csv` `.xlsx` | | Text | `.txt` `.md` `.mdx` | Each file can be up to **50 MB**. If a document is larger, split it into smaller files before uploading. ## How to upload files Open your agent and go to the **Sources** tab. From the add menu, pick **Upload Files**. Drag your documents in, or click to browse. You can add several at once. Each file is queued and read in the background. Watch the status until it shows **Trained**. ## When to use it File training fits content you keep as documents: * **A coffee store** – upload a wholesale price list spreadsheet. * **A SaaS app** – upload your onboarding manual as a PDF. * **A dental clinic** – upload your new-patient and insurance policies. Text-based PDFs work best. A PDF that is really a scanned image of text (like a photo of a printed page) may not extract – if you can highlight the words in the file, your bot can read them too. If a scan won't train, retype the key parts as a [Text source](/knowledge-base/training-with-text) instead. ## Next steps Crawl your site instead of uploading every page. Paste a quick answer that isn't in a file. See when each file finishes and retry any that fail. Ask about something in your uploaded files. # Training with Text Source: https://docs.chatref.ai/knowledge-base/training-with-text Paste a title and content to teach your bot a quick FAQ, policy, or fact. Sometimes the answer isn't on your site or in a file yet. Text training lets you type it straight in. You give it a **Title** and **Content**, and your bot can answer from it right away. It's perfect for a quick FAQ, a policy, or anything you haven't published. ## How to add text Open your agent and go to the **Sources** tab. From the add menu, pick **Add Text**. Give it a clear **Title** (like "Refund policy") and paste your **Content** below. Write it the way you'd explain it to a customer. Add **tags** as a comma-separated list to help you organize sources – for example, `refunds, policy, shipping`. Save it. Chatref trains on the text in the background. Watch the status until it shows **Trained**. ## Example: a refund policy A coffee store could add a source like this: **Title:** Refund policy **Content:** We accept returns within 30 days of purchase. Items must be unopened and in their original packaging. To start a return, email [orders@example.com](mailto:orders@example.com) with your order number. Refunds go back to your original payment method within 5 business days. **Tags:** refunds, returns, policy Now when a visitor asks "Can I get my money back?", your bot answers from this text instead of saying it doesn't know. Keep each source focused on one topic. A short, clear "Refund policy" source is easier for your bot to match than one long page covering ten different things. ## Next steps Crawl content you've already published. Upload manuals, price lists, and policies. See when your text finishes training. Ask the question your new text answers. # Training with Websites Source: https://docs.chatref.ai/knowledge-base/training-with-websites Paste a URL and let Chatref crawl your site to train your bot on its content. If the answers are already on your website, this is the fastest way to train your bot. Paste a URL and Chatref crawls every page on that domain and learns the text. Want just one page? Paste that specific page's URL instead. Your website is already crawled once for you during signup, when you enter it on the **"What's your website?"** screen. You only need to add a site here if you want to train on another one – or crawl the same site again after big changes. ## How to crawl a website Open your agent and go to the **Sources** tab. From the add menu, pick **Crawl Website**. Enter the address you want to learn from. It must start with `http://` or `https://` – for example, `https://example.com`. A homepage URL crawls the whole domain; a deep link like `https://example.com/pricing` crawls just that page. Submit it. The source is queued and a background worker reads each page. Watch the status until it shows **Trained**. ## When to use it Website training is best when your site already has the answers: * **A SaaS app** – crawl your docs, pricing, and feature pages so the bot can explain how the product works. * **A dental clinic** – crawl your services and hours pages so visitors get details without calling. * **A travel agency** – crawl your destination and FAQ pages in one go. Start with your homepage URL to capture the whole site at once. If you only want the bot to learn one thing – say, a single policy page – paste that page's exact URL instead. ## Next steps Upload documents your website doesn't cover. Paste an answer that isn't on your site yet. See when the crawl finishes and retry if it fails. Ask your bot a question in the Playground. # Quickstart Source: https://docs.chatref.ai/quickstart Go from sign-up to a live AI bot on your website in a few minutes. This guide takes you from a new account to a working bot on your site. Chatref does most of the heavy lifting – you paste your website, it builds and trains your bot, and you add one line of code to go live. The website-first setup does most of the website step and the Playground test for you. When you give Chatref your URL, it builds your bot and starts learning your whole site automatically – so you may only need to test and deploy. ## Build your first bot Sign up for Chatref. You start with **\$50 of free trial credit**, so you can build and test your bot before paying anything. On your first login, Chatref asks **"What's your website?"** Paste your URL and submit. Chatref reads your homepage and auto-builds your bot – its name, personality, welcome message, and suggested questions – then starts learning your whole site in the background. You land in the **Playground**, a live chat that uses your real settings. Type a question – like "What are your opening hours?" – and watch your bot answer. Tweak the personality or AI **Model** on the left if you like, then click **Deploy** to save. In **Settings**, set your brand colors, edit the welcome message, and add quick-action buttons – for example, a coffee store might add a **Track my order** button. Skip this for now if you're in a hurry. Open the **Deploy** tab and copy the one-line script. Paste it into your site's HTML, just before the closing `` tag. ```html theme={null} ``` Your bot now appears on every page of your site. Read real conversations in the **Inbox** and track performance in **Insights** – including what your bot answered and what it couldn't, so you know what to add to your Knowledge Base next. ## Next steps Learn the words behind Chatref – agent, Knowledge Base, widget, balance, and more. Set up more bots, one per website or use-case, and explore each tab. # Widget Appearance Source: https://docs.chatref.ai/widget/appearance Customize how your chat widget looks so it matches your brand and fits your website. The widget is the chat bubble visitors see on your site. You control how it looks under **Settings → Appearance**. Every change auto-saves, and you can see it live in the **Playground** preview. ## Appearance options | Setting | What it does | Default | | -------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------ | | **Action color** | The accent color for buttons and highlights. | Blue | | **Background color** | The color of the chat panel. Text contrast adjusts automatically so it stays readable. | Light | | **Home wallpaper** | A background pattern for the home screen, with its own color and opacity. | None | | **Widget icon** | The glyph on the launcher bubble – pick from 8 styles (chat, bot, headphones, and more). | Default | | **Widget position** | Which side of the screen the launcher sits on – **Left** or **Right**. | Right | | **Custom logo** | Your own logo, shown in the chat header in place of the default. | None | | **Custom footer** | A small markdown link at the bottom of the panel, up to 200 characters. | "Powered by [Chatref](https://chatref.ai)" | | **Language** | The language for the widget's built-in text (buttons, placeholders). | English | ## Customize the look Go to your agent's dashboard and open **Settings → Appearance**. Pick an **Action color** for buttons, then a **Background color** for the panel. Text contrast is handled for you, so light or dark both stay readable. Pick one of the 8 **Widget icons** for the launcher bubble, then set its **Widget position** to **Left** or **Right**. Upload a **Custom logo** for the header, and add a **Custom footer** link if you want – for example, an online coffee store might use `Powered by [Bean & Co](https://example.com)`. Turn on a **Home wallpaper** pattern, then tune its color and opacity to taste. Pick an **Action color** that stands out against your site so visitors notice the chat bubble. Keep the footer short – it is meant for a single credit or link. ## Light or dark mode Dark mode is **not** an Appearance setting. It lives in **Settings → General** as the **Dark Mode** toggle. New bots start in **light mode**. If you want a dark widget, open **Settings → General** and turn **Dark Mode** on. See [Agent Settings](/agents/agent-settings) for the full General tab. Dark mode switches the whole widget to a dark color theme. It is off by default for every new bot – you opt in. ## Next steps Add up to 4 shortcut buttons – call, email, or a link – to the chat header. Find the Dark Mode toggle, language, and other general settings. # Display Rules Source: https://docs.chatref.ai/widget/display-rules Control which pages of your site show the chat widget, using simple URL patterns. Display rules decide **where** your chat widget appears. By default the widget shows on every page. With display rules you can limit it to certain pages – or hide it on others – by matching the page's URL. You set them up under **Settings → Display Rules**. ## How display rules work * A master **on / off** switch turns rules on for the whole agent. * You can add up to **10** rules. * Each rule has a **type** and a **pattern**: | Type | What it matches | Example | | --------------- | ---------------------------------------------- | -------------------------------------------------- | | **Contains** | Any URL that includes the text you type. | `/pricing` matches `/pricing` and `/pricing/teams` | | **Exact match** | Only the URL that matches the pattern exactly. | `/support` matches `/support` and nothing else | When rules are on, the widget shows only on pages that match a rule. ## Set up display rules Go to your agent's dashboard and open **Settings → Display Rules**. Flip the master switch to turn display rules on for this agent. Add a rule, choose its **type** – **Contains** or **Exact match** – and type the **pattern**, e.g. `/support`. Repeat for each page or section, up to 10 rules. For example, a travel agency that only wants the widget on its help page would turn rules on and add one **Exact match** rule for `/support`. Display rules also decide **which agent** appears on which page when you run more than one bot from a single embed code. See [Multi-Agent Routing](/deploy/multi-agent-routing) to set that up. ## Next steps Show different bots on different pages from one embed code. Set colors, icon, position, and branding for the widget. # Help Menu Source: https://docs.chatref.ai/widget/help-menu Add a menu of useful links inside your chat widget so visitors can find resources fast. The Help Menu is a list of handy links inside your chat widget – things like your docs, contact page, or pricing. Visitors can open it any time to find resources without leaving the chat. You can add up to **10** links. ## What each item has Every help menu item has three parts: * **Name** – the text the visitor sees, e.g. "Docs". * **URL** – the page that opens when they tap it. * **On / off** – show or hide the item without deleting it. You can also **reorder** items so the most useful ones sit at the top. ## Add and reorder items Go to your agent's dashboard and open the **Help Menu**. Add a new item, then enter its **Name** and **URL** – for example, **Docs**, **Contact**, or **Pricing**. Repeat for each link you want. Ten is the maximum. Use the arrows to reorder items. Turn any item **off** to hide it for now without losing it. Keep it focused – a SaaS app might list just **Docs**, **Pricing**, and **Contact**. A short, well-chosen menu is more useful than a long one. ## Next steps Add call, email, or link buttons to the chat header. Choose which pages of your site show the widget. # Quick Actions Source: https://docs.chatref.ai/widget/quick-actions Add up to 4 shortcut buttons in the chat header so visitors can call, email, or open a link. Quick actions are buttons in the **header** of your chat widget. They give visitors a fast way to reach you or jump to an important page, without typing a single message. You can add up to **4**. ## What each button has Every quick action has three parts: * **Label** – the text on the button, e.g. "Call us". * **Type** – what happens when it is tapped: **Phone**, **Email**, or **Link**. * **Icon** – a small glyph that matches the action. | Type | What it does | Example label | | --------- | -------------------------------------------------- | --------------- | | **Phone** | Opens the visitor's phone app to call your number. | "Call us" | | **Email** | Opens the visitor's email app addressed to you. | "Email support" | | **Link** | Opens a web page in a new tab. | "Visit shop" | ## Add a quick action Go to your agent's dashboard and open **Settings → Actions**. Click to add a new quick action. You can add up to 4 in total. Type a clear **Label**, choose a **Type** – Phone, Email, or Link – then pick an **Icon**. For a Phone action, enter your number; for Email, your address; for Link, the URL. Open the **Playground** to see the buttons in the live widget header. You have room for 4 buttons, but the most useful 2 – 3 work best. A dental clinic might keep just "Call us" and "Book online" so visitors aren't overwhelmed. ## Next steps Add starter prompts that help visitors begin a conversation. Add a menu of useful links – docs, contact, pricing – inside the widget. # Suggested Messages Source: https://docs.chatref.ai/widget/suggested-messages Give visitors clickable starter prompts so they know what to ask, and control the greeting bubble timing. Suggested messages are clickable chips that help a visitor start a conversation. Instead of staring at an empty box, they tap a prompt like "Track my order" and your bot replies right away. You set them up in **Settings → Messages**. ## How suggested messages work * Each suggestion is a short, clickable **chip**. * Tapping one sends that text to your bot as the visitor's first message. * Turn on **In-Chat Suggestions** to also show the chips inside the open chat, not just on the greeting screen. ## Add suggested messages Go to your agent's dashboard and open **Settings → Messages**. Add a suggested message and type the chip text, e.g. "What are your hours?" Repeat to add the prompts you want. Drag to reorder – the first chip shows first. Turn on **In-Chat Suggestions** if you want the chips to appear inside the open chat as well as on the greeting screen. Write 3 – 5 clear starters in your visitors' own words, like "Track my order" or "Book a cleaning". This is guidance, not a hard limit – but a short, focused list is easier to act on than a long one. ## Greeting bubble timing The greeting bubble is the little message that pops up near the launcher to invite a chat. You control how long it stays: | Option | What it does | Default | | -------------------------------- | ---------------------------------------------------------------------------- | --------- | | **Keep visible until dismissed** | The bubble stays until the visitor closes it. | Off | | **Hide after** | The bubble disappears on its own after a set time, from **2 to 60 seconds**. | 6 seconds | Pick **Keep visible until dismissed** for a gentle, always-there nudge, or use **Hide after** for a brief greeting that fades on its own. ## Next steps Add call, email, or link buttons to the chat header. Set colors, icon, position, and branding for the widget.