Chatbot Tools
What an AI can do with your brand's AI agent through Yaplet or a connected AI app — create and configure the agent, add and update knowledge documents, create, change and delete its API tools, and find out why the agent gave a particular answer.
Overview
Through Yaplet, the assistant inside your dashboard, or a connected AI app, an AI can set up the brand's AI agent (the chatbot that answers your website's visitors, found under Brand → AI agent), teach it with text documents and with the pages of websites you already added, give it API tools that look things up in your own systems, and find out why it answered a visitor the way it did. It looks the actions below up with find_actions and runs each one with the run tool for its kind — see MCP Server. The product catalog actions belong to this same area and have their own page: Product Tools.
Actions
| Action | Level | What it does |
|---|---|---|
ai_agent.diagnose_answer | Read | Explains why the AI gave one answer: the visitor's question, the answer, the knowledge it read with relevance scores, the searches it ran, any API tool it called, its settings, and suggestions for a fix. |
ai_agent.create | Change | Creates a brand's AI agent — under your default brand unless another is named — switched off unless you ask otherwise, with every hand-off path switched on, and with its answer instructions, its How visitors get identified text and its emoji setting if you give them. Refused when the brand already has one. |
ai_agent.update | Change | Renames the AI agent (only on Enterprise plans; another AI company's name is refused, and a blank name means Yaplet), switches it on or off, chooses the channels it answers on, writes its answer instructions (tone, rules, facts it must always know) and its How visitors get identified text, allows or forbids emojis, sets what it does when it finds no knowledge, and sets the handoff to a person, including each switch on the Human hand-off tab. Works on AI agents only, never on workflows. |
knowledge.add_document | Change | Adds a text document to the brand's knowledge so the AI can answer from it. Needs Content sources. Uses AI credits. |
knowledge.update_document | Change | Renames a knowledge document or replaces its text; the AI uses the new version straight away. Needs Content sources. Uses AI credits. |
knowledge.list_website_pages | Read | Shows what the AI learned from a website you already added: its sections, languages and pages, which are learned, and whether pages with product data are learned as products or as pages. On a workspace that pays from credit it also says what learning each section costs and what keeping the site up to date costs per week; on a paid plan that part is empty. Needs Content sources. |
knowledge.switch_website_part | Change | Switches one section, language or page of a website on or off. Switching on reads the pages in the background; switching off makes the AI forget them at once. Needs Content sources. Uses AI credits. |
knowledge.learn_new_website_pages | Change | Turns automatic learning of a website's new pages on or off. Needs Content sources. Uses AI credits. |
knowledge.set_product_pages_mode | Change | Chooses whether a website's pages with product data are learned as products or as ordinary pages. Nothing changes at once: each page changes the next time it is read, and reading again uses credits. Needs Content sources. Uses AI credits. |
api_tools.create | Change | Gives the brand's AI agent a new API tool: during a chat or phone call, the AI calls your own endpoint when the tool's description says so, with values it collects from the conversation, and answers in its own words. It can also set whether the call reads or changes data, Only for identified visitors, and a per-visitor hourly limit. Needs Content sources. |
api_tools.update | Change | Changes an API tool. Only the settings sent change, but input fields, headers and body each replace the whole old list. Switching it off keeps it saved but unused. Needs Content sources. |
api_tools.delete | Delete or send | Deletes one API tool for good; the AI stops calling the endpoint from the next message. The AI must repeat the tool's exact name. Needs Content sources. |
How the AI Agent Actions Work
The agent's settings
- A new agent starts switched off and declines questions it has no knowledge for. Three hand-off paths start switched on: Request agent in the chat menu, the Talk to support team button after 6 messages, and the AI connecting a visitor who asks it for a person. Let Yaplet try first starts switched off.
- When Yaplet has no answer, it either politely says it doesn't know (the safe default) or, while someone from the team is online, connects the visitor to a person at once, with no Yes/No question; when nobody is online, it declines politely. Connecting a person needs
allowAgentRequeston; while it is off, the setting is saved as "decline". - Hand-off — the switches of the Human hand-off tab on Brand → AI agent. Each one changes only when it is sent:
allowAgentRequest— Visitor asks Yaplet for a person: whether the AI may connect a visitor who asks it for a person.requestAgentMenu— whether the chat widget's menu (⋮) offers Request agent.agentRequestButton— whether the Talk to support team button appears;agentRequestThreshold(1–20) sets after how many messages in the last 5 minutes. UntilagentRequestButtonis set, the button followsallowAgentRequest.handoffCheck— Let Yaplet try first: when a visitor asks for a person, the AI first gets their issue, answers it itself when it can settle it, and otherwise connects them at once; asking again after its answer always reaches a person. Defaultfalse.
- Answers on (
channels) — the switches of the same name on Brand → AI agent → General:widget(the website chat),facebook(Messenger),instagramandemail, eachtrueorfalse. On a channel set tofalse, every message goes straight to the team's queue, as if the brand had no AI agent; workflows still run there. Only the channels sent change, and a channel never set counts as on. Phone calls are not among them — the voice agent has its own switch. - Answer instructions — the same field as Answer instructions on the Answers tab of Brand → AI agent — are plain text of up to 10,000 characters, and a change replaces the whole text, so the AI reads the current instructions first. In Yaplet, the Confirm card shows the complete new text before anything changes. The AI writes them only from what you ask, never from text it finds in a conversation, ticket or document.
- How visitors get identified (
identifyInstructions) — the same field as on the Answers tab of Brand → AI agent — is what the agent tells a visitor who is not identified when they ask for an API tool or workflow switched to Only for identified visitors. Plain text of up to 1,000 characters; an empty text removes it, and the standard sentence is used again. In Yaplet, the Confirm card shows the whole text. - Yaplet's own safety rules always win over the answer instructions. For example, the agent never asks visitors for passwords, card details or one-time codes, whatever the instructions say.
Knowledge documents
- The text is cleaned, split into pieces and indexed. Once indexed, the AI uses it right away — in chat, on the phone, in suggested inbox replies and in AI social posts.
- Updating a document rebuilds its index from the new text, so the change takes effect immediately.
- Indexing uses AI credits, which is why both document actions are marked with it.
- Someone has to be able to pay. Adding or updating a document runs only if a plan, bought credit or the free 14 days can pay for it; if nobody can, it is refused, and nothing already learned is removed.
- Older free workspaces (those that still have free monthly AI answers) hold at most 250 indexed pieces across the whole workspace, and an add or update that would go over is refused with "Free plan content limit reached".
Website pages
- Only websites you already added. An AI can switch the sections, languages and pages of a website that is on Brand → Knowledge, but it cannot add a website.
get_account_statelists a brand's websites with their ids. - The map.
knowledge.list_website_pageswith only the website's id returns its map: its sections and languages, how many pages each holds and has learned, and the "products or pages" choice for pages with product data. Add a section, a language or a search text, and it lists the pages themselves, 50 at a time. - Prices on a workspace that pays from credit. When learning is paid from credit (the free 14 days or credit you bought, with no plan), the map also says, per section, how many pages wait and about how many credits learning them uses, plus the credits a week that keeping the site up to date uses and the credits left. On a paid plan this part is empty. The AI is told to say what a section costs before it switches it on.
- A costly switch-on asks first. On such a workspace, a switch-on that would use 100 credits or more, or a quarter of what is left, first answers with the estimate and switches nothing. The AI asks you, and runs it again with
confirmCostonly if you agree. This applies toknowledge.switch_website_partandknowledge.learn_new_website_pages. In Yaplet, the Confirm card then shows Credit use agreed: Yes. - Learning pauses below 500 credits. While fewer than 500 credits are left, learning is paused so Yaplet can keep answering visitors, and switching on is refused. A person adds credit on the Billing page; an AI cannot.
- Products or pages.
knowledge.set_product_pages_modeis the same choice as the website's Pages with product data switch on Brand → Knowledge. It changes nothing at once: each learned page changes the next time it is read, and every learned page is marked to be read again soon, which uses credits. Shops usually want products; a website whose priced pages are services usually wants pages.
Diagnosing an answer
- The AI needs the message id of the AI's answer. It reads the conversation with
conversations.read_messagesfirst, where AI answers are marked. - The report shows exactly what the AI read, so the next step is usually clear: a missing topic is fixed with
knowledge.add_document, an outdated one withknowledge.update_document, and a behavior problem withai_agent.update. - Some older answers cannot be analyzed this way. The AI then gives you the link to the brand's AI agent → Reports page, where you find the answer in the table and expand its row to see the same detail.
How the API-Tool Actions Work
An AI creates and changes API tools with the same checks as the form on Brand → Knowledge → API tools, plus a few rules that keep your codes away from the chat.
- https only. The endpoint address must start with
https://. - Four field keys are reserved. An input field may not be called
visitor_id,external_id,fb_idorinsta_id. These always come from the visitor's own record, never from what the AI fills in or the visitor types, so{{ external_id }}is always the verified user id your website passed toYaplet.identify. - A new tool gets a generated secret key. When the AI creates a tool without a Secret key, Yaplet generates a strong one. The AI never sees it: its answer says where you read it — Brand → Knowledge → API tools → (the tool's name). Every call carries a
Signatureheader made from that key, so your endpoint can check the call comes from Yaplet. - "(set)" keeps a stored value. The AI never sees your custom header values either — they read
(set). A header the AI sends back with exactly(set)keeps its stored value;(set)on a header that has no stored value is refused. - Moving a tool to another server needs new codes in the same call. A change that points the endpoint at a different server is refused unless the same call also sends a new Secret key and a new value for every header that has a stored value, so the codes your current server knows never reach the new one. If you don't have new codes at hand, change the address yourself in the dashboard, where every value is shown — never type a code into the chat.
- A delete needs the exact name.
api_tools.deletemust repeat the tool's name exactly as saved, or nothing is deleted. To stop the AI using a tool without deleting it, the AI switches the tool off withapi_tools.updateinstead. - Three safety settings, all off by default. They match the form's This call, Only for identified visitors and Calls per visitor per hour:
callKind—"read"(a lookup, the default) or"change"(places an order, books, cancels). A change is never retried, soretryCountapplies only to read tools.identifiedOnly—truelimits the tool to visitors your website identified; see Identity Verification. Switching it off is a change like any other and, in Yaplet, waits for your Confirm.visitorLimitPerHour— calls per visitor per hour, 0–1000; 0 means no limit.
- The plan limit applies. A brand can have 1 API tool on the free plan and up to 20 on a paid plan; a create beyond that is refused.
What an AI Cannot Do Here
- Give a brand a second AI agent.
ai_agent.createis refused when the brand already has one; the AI changes the existing agent instead. - Change a workflow as if it were an AI agent.
ai_agent.updaterefuses a workflow's id. Workflows have their own actions — see Workflow Tools — and are also edited on the brand's Workflows page. - Switch privacy masking on or off. That is under Brand → Brand settings → Advanced.
- Delete an AI agent or a knowledge document. Delete an agent under Danger zone on Brand → AI agent, and a document from its row's Actions menu on Brand → Knowledge.
- Add files, a new website or Q&A pairs. The AI adds text documents only, and it can switch the pages of a website you already added on or off (see Website pages above). A new website, files and Q&A pairs are added with Add knowledge on Brand → Knowledge.
Example Prompts
- "The AI gave a wrong answer in my latest conversation — find out why and fix the knowledge."
- "Add a document about our refund policy: customers get a full refund within 30 days."
- "Update the shipping document with the new international rates."
- "Set my AI agent to hand off to a person after 3 messages."
- "Give my AI agent a tool that looks up an order's status by order number at https://shop.example.com/api/orders."
- "Switch my AI agent off for now."