Chatbot Tools

Overview

Through Copilot or a connected AI app, an AI can set up the brand's AI agent — the one the dashboard calls Vex — teach it with text documents, 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 catalogue actions belong to this same area and have their own page: Product Tools.

Actions

How the AI Agent Actions Work

The agent's settings

• A new agent starts switched off, declines questions it has no knowledge for, and hands over to a person after 6 messages.
• When the AI finds no knowledge, it either politely says it doesn't know (the safe default) or offers to connect the visitor with a person through a Yes/No question, only while someone is online. Offering a person needs the handoff switched on; while the handoff is off, the setting is saved as "decline".
• Handoff: whether the AI may hand the conversation to a person at all, and after how many messages it does so on its own (1–20).
• Answer instructions — the same field as Answer instructions on Brand → Vex → Personality — 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 Copilot, 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.
• Yaplet's own safety rules always come after the answer instructions and win. 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.
• On the free plan documents count toward the 250 indexed pieces your account can hold, and an add or update that would go over is refused with "Free plan content limit reached".

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.
• Answers given before Yaplet started linking AI events to messages cannot be analyzed this way. The AI then gives you the link to the brand's Vex → 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.
• 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.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 on the Danger Zone tab of Brand → Vex → Personality, and a document on the Sources tab of Brand → Knowledge.
• Add files, website pages or Q&A pairs. The AI adds text documents only; everything else is added under Other sources 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."