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.

Permissions: the AI agent actions need AI agent. The knowledge-document, website and API-tool actions need Content sources instead, because knowledge and API tools belong to the brand, not to the agent. An app connected by browser login also needs the Chatbot area ticked on the login screen.
A brand has at most one AI agent, and the knowledge belongs to the brand, not to the agent. A document added here lands in the brand's knowledge, which the brand's chat AI, its phone agents and its AI social posting all read from. In the dashboard it appears on Brand → Knowledge.

Actions

ActionLevelWhat it does
ai_agent.diagnose_answerReadExplains 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.createChangeCreates 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.updateChangeRenames 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_documentChangeAdds a text document to the brand's knowledge so the AI can answer from it. Needs Content sources. Uses AI credits.
knowledge.update_documentChangeRenames a knowledge document or replaces its text; the AI uses the new version straight away. Needs Content sources. Uses AI credits.
knowledge.list_website_pagesReadShows 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_partChangeSwitches 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_pagesChangeTurns automatic learning of a website's new pages on or off. Needs Content sources. Uses AI credits.
knowledge.set_product_pages_modeChangeChooses 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.createChangeGives 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.updateChangeChanges 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.deleteDelete or sendDeletes 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 allowAgentRequest on; 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. Until agentRequestButton is set, the button follows allowAgentRequest.
    • 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. Default false.
  • Answers on (channels) — the switches of the same name on Brand → AI agent → General: widget (the website chat), facebook (Messenger), instagram and email, each true or false. On a channel set to false, 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.
The handoff sentence is not settable. The line a visitor reads when they are handed to a person — "A team member will join this chat.", shown only while someone from your team is available — is one of Yaplet's own texts, said in whatever language the visitor is reading. There is nothing to reword, here or in the dashboard.

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_state lists a brand's websites with their ids.
  • The map. knowledge.list_website_pages with 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 confirmCost only if you agree. This applies to knowledge.switch_website_part and knowledge.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_mode is 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_messages first, 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 with knowledge.update_document, and a behavior problem with ai_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_id or insta_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 to Yaplet.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 Signature header 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.delete must 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 with api_tools.update instead.
  • 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, so retryCount applies only to read tools.
    • identifiedOnly — true limits 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.
API tool or workflow? An API tool is right when a visitor can ask in one sentence ("where is order 1234?") and the AI should answer in its own words. When the questions must come in a fixed order, the result must be shown word for word, or a call changes something and needs a Yes first, a workflow fits better — see Workflow Tools.

What an AI Cannot Do Here

  • Give a brand a second AI agent. ai_agent.create is 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.update refuses 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."

© 2026 Yaplet. All rights reserved.