Configure an AI agent

Open AI agents in the main menu and click Edit on an agent, or create one (see Create an AI agent). The editor lists its sections on the left, the form in the middle, and two tabs on the right: Testing, where you try the agent, and Assistant, where Improve my agent helps you rewrite it.

SavingCopy Anchor Link

Only Name and Mission are required. If you leave the editor without saving, the browser keeps your edits and offers Restore unsaved changes? the next time you open the agent.

Agent identityCopy Anchor Link

Knowledge baseCopy Anchor Link

What the agent knows. It answers from this, and says it does not know when the knowledge does not cover the question. An agent with no knowledge answers only from its mission and instructions.

• Files. Click Add data source or drop a file: PDF, TXT, Markdown, CSV or DOCX, up to 25 MB each. Whatsable reads the text, and each file shows Processing, Ready or Failed with the reason. A PDF that is only images has no text to read.
• Written knowledge. Under Anything the files do not cover?, type short facts: opening hours, a delivery price, a promise you never make.
• Websites. The agent can learn from your website pages. See below.

WebsitesCopy Anchor Link

Add up to 5 websites per agent. Whatsable reads the pages, keeps the facts it finds in a document per website, and the agent answers from that document like a file.

Use https addresses only, and tick I own this website or have permission to use its content before you click Add websites.

Open a website's document to read exactly what the agent knows. You can correct a fact and save it, publish or discard an update, restore an earlier version, and exclude a page. Once you edit a document, later updates wait for your review, so a website change never overwrites your correction. Email me a weekly summary of website changes sends a Monday email when a document changed, an update waits for review, or a check failed.

Whatsable reads only public pages that your site's robots.txt allows. If a check fails, the website row says why, for example that the page needs a login or the site's security check blocked it.

Files it can sendCopy Anchor Link

Knowledge is what the agent knows. Files are what it can send: a price list, a menu, a brochure, sent as they are. The agent never reads these files. It picks one only from the sentence you write about it.

• What the file you are adding is for: required. Say when a customer should receive it. Up to 1,000 characters.
• What to call the file you are adding: optional. The file name is used when you leave it empty.
• The agent may send this file: turn it off to keep the file without letting the agent send it.

An agent holds up to 10 files. A file with no description cannot be chosen until you write one.

Custom instructionsCopy Anchor Link

Optional rules for every reply, one per line: what never to discuss, what to ask before booking, what to do when it does not know. To make the agent add a label, name the label exactly as it appears under Labels, and say when to add or remove it.

Always ask for the order number before discussing a refund.
Never mention competitor prices.
If you do not know, say so. Never invent a price.
Add Hot lead when they ask to reserve stock.

Response settingsCopy Anchor Link

With The agent resumes after a set time, choose how many minutes it waits. A reply from the Whatsable inbox or from the WhatsApp Business mobile app pauses the agent and starts the timer. A second reply does not restart it. When the time is up, the agent resumes only if the customer has written since your last message.

LabelsCopy Anchor Link

The agent can tag conversations with your labels. It sees the name and the description of every label it may use.

Create labels under Settings, Labels first. If the agent may add labels but you picked none, the editor warns you.

HandoffCopy Anchor Link

When a customer wants a person, the agent steps back, can tell them someone is coming, and pauses in that conversation so a teammate can take it.

• Tell the team when a customer asks for a person: on by default. Your team gets a notification when this agent hands a conversation over. The in-app notice also needs AI handoffs turned on in notification settings.
• Which words mean they want a person?: up to 25 words or short phrases, such as "agent", "human" or "speak to someone". Capitals do not matter.
• Describe those situations: plain sentences for what a keyword misses, such as an angry customer, a refund, or a price you do not publish. This is a rule the agent reads, never a message the customer receives.

The message the agent writes when it hands over is always sent, even when it holds a figure that is not in its knowledge. The figure is flagged instead. See Unverified figures.

Agent settingsCopy Anchor Link

Times are local to sets the agent's time zone. Message times, quiet hours and quiet days are read in it. A new agent usually starts with the time zone of your first connected number. Pick the one your customers live in.

Follow-upsCopy Anchor Link

Turn on Follow up when a conversation goes quiet to let the agent write again when a customer stops replying after a message from the agent or from your team. It never interrupts a live back-and-forth, and when the customer replies, the remaining follow-ups for that stretch are cancelled.

A follow-up that would land in quiet hours or on a quiet day is skipped, not moved. Enter durations in days, hours and minutes; they add up.

A follow-up that cannot be written, because the AI model did not answer or sent back an answer Whatsable cannot use, is skipped too, and the next follow-up still goes out at its time. When the model refuses to write a follow-up, the follow-ups for that quiet stretch stop.

What to say in a follow-up is read only when the agent writes a follow-up: what to offer, what never to promise, and not to repeat the last message.

To stop follow-ups for one person, turn off Follow up in that contact's details in the inbox.

ReviewCopy Anchor Link

Review lists what is set and what is missing: name, mission, knowledge, handoff words and follow-ups. The Readiness card beside the form says Ready to go live. or what is still needed. Click Copy what I filled in to edit the text in another AI.

Test your agentCopy Anchor Link

The Testing tab tries the agent with your unsaved changes. Nothing goes to WhatsApp. Save the agent once before you test it.

• Test chat. Write as the customer, the AI agent or a teammate, to set up any moment you want to test. With Reply automatically on, the agent answers each customer message; off, add several messages and click AI reply. Skip to next follow-up moves the simulated time ahead and runs the next follow-up. Edit, delete or rewind any message, or rerun from it.
• Customer details. Give the test customer a name and labels, as the agent sees for a real contact.
• Scenario library. Generate test scenarios writes conversations a real customer could start, optionally from a description such as "angry, wants a refund". Import from a conversation copies a real chat from your inbox up to the message you pick, without changing the inbox. Keep as a scenario saves a test for your whole team, and Examples holds common situations ready to use.

Each answer in the test shows what the agent decided and why, for example Replied or Handed over to a person.

Ratings and suggested changesCopy Anchor Link

Rate any decision of the agent with the thumbs, in the inbox or in the test panel. A thumbs-down asks What was wrong?. Write what the agent should have done and click Improve my Bot.

For the owner and Admins, Whatsable then looks for a change to the agent's settings and shows a Suggested change: each edit to a field, with what it changes to. It may first ask one question. A Member's rating is saved, and an Admin can turn it into a change later.

• In the test panel or the editor, keep the edits you want and click Apply the suggestion, then save the agent.
• In the inbox, click Save changes to apply the kept edits to the agent at once, with Undo afterwards, or Open in editor to review them in the form.

A suggestion is never applied without a person. It never changes the agent's name, its status or the handoff notification. An edit that copies a customer's words, or adds a number, price or date that is in neither your comment nor the agent's settings, is flagged so you check it first.

Decision feedback, the last section of the editor, lists every rating of this agent, newest first. Filter by thumbs up or down and by where it was given, open the conversation, load it in the test panel, or ask for a suggested change.

Edit an agent from an AI assistant or the APICopy Anchor Link

You can change an agent without opening the editor: ask an AI assistant connected through the MCP server, such as Claude or ChatGPT, or call the API v1 from your own integration. Both read and change the agent's settings. Typical requests: "add our holiday opening hours to the Sales agent's knowledge", "add a rule to its instructions: never offer a discount over 10%", or "check what the knowledge says about returns and fix the refund period".

Add to the knowledge or the instructions without rewriting them. The assistant sends only the new text, and Whatsable adds it to the end of the written knowledge or the custom instructions, after a blank line. Nothing already there changes, so this works on a knowledge base of any length, and the assistant does not have to read it first. Two additions made at the same moment never overwrite each other. In the MCP server this is the knowledge_append or instructions_append field of the update_ai_bot tool; in the API it is the same field of Change an AI bot.

Read long texts in full. The get_ai_bot tool shows every setting of the agent. A text up to 2,000 characters is shown whole. A longer one, such as a large knowledge base, shows its length and its start, and the read_ai_bot_text tool reads it whole, page by page. The API route is Read an AI bot's long text in pages (GET /v1/ai-bots/{id}/text/{field}). It reads the mission, the custom instructions, the written knowledge, the handoff instructions, the label instructions and the follow-up instructions. When the assistant passes the version it read, as the MCP server asks it to, a save made while it is reading makes the next page refused and the assistant starts again, so it never mixes two versions. To change something inside a long text, the assistant reads it whole, then sends the whole new text with the version it read, so the change is refused if the agent was saved in between. The MCP server always sends that version; through the API, send it as the If-Match header.

Limits. The written knowledge holds at most 200,000 characters and the custom instructions at most 80,000. An addition that would go past the limit is refused with the error ai_bot_text_too_long, and nothing is saved. The assistant can then add a shorter text, or read the field, remove what the agent no longer needs, and save the shorter text. An emoji counts as two characters.

An addition or any other change applies to the agent's next reply, as a save in the editor does. Uploaded knowledge files are listed by the list_knowledge_files tool, but their text cannot be read through the API or the MCP server.

When a reply failsCopy Anchor Link

The inbox shows every failed AI reply with its cause, in the decision row of the conversation:

• Trying again: a temporary problem on our side or at WhatsApp. Whatsable keeps trying for up to 15 minutes. Click Cancel to stop it; the agent then answers the customer's next message.
• Reply failed: the row names the reason. Some reasons need you, such as a paused number, a number to connect again, or a subscription that is not active. The customer got no reply, so the conversation goes to a person and your team gets the handoff notification, as for any handoff. If the customer writes again before that, the agent answers the new message instead.
• Reply not confirmed: WhatsApp did not confirm delivery. The reply may have reached the customer, so the agent keeps the conversation.
• Handed to a person with the reason the agent's answer was cut off or could not be read: the AI model sent back an answer that Whatsable could not use. Whatsable asks the model again, for up to 15 minutes, while the row shows Trying again. If no usable answer comes, the conversation goes to a person, and your team gets the handoff notification. The customer gets no message from the agent. When the model refuses to answer, the conversation goes to a person at once.
• Part of the knowledge was left out: the agent's knowledge is larger than it can read at once, so it answered without part of it. Click Open the agent settings and shorten the knowledge or remove documents you no longer need.

Unverified figuresCopy Anchor Link

The agent is told never to state a price, a discount, a date or a quantity that nothing it was given supports. Before each message goes out, Whatsable also checks every figure in it. A figure that the check cannot find is flagged: the message is still sent to the customer, and the inbox shows a warning under it so your team can check the figure.

A flag never stops a message. The customer always gets the agent's answer, and the agent never hands a conversation to a person only because of a figure.

What counts as knownCopy Anchor Link

A figure is known when it appears, written the same way, in any of these:

• The agent's knowledge: its files, written knowledge, the description of each file it can send, and website documents your team has opened, published or edited.
• The agent's mission, custom instructions and handoff instructions, and its follow-up instructions for a follow-up.
• A message the customer sent in the part of the conversation the agent read.

A figure the agent or your team wrote earlier in the conversation does not count, because the agent may have made it up the first time.

Why a figure gets flaggedCopy Anchor Link

Most flagged figures are correct. The usual reasons:

• The agent calculated it. A total, such as two items from your price list added together, is not written anywhere.
• It came from an image, a document the customer sent, or an earlier message from your business.
• It is written in another format. "$1,500" in your knowledge and "$1.500" in the reply, or a date written differently.
• It is a number that is not a commitment, such as a street number or "24/7".
• The agent made it up. This is rare, and it is the case the warning exists for.

What your team seesCopy Anchor Link

In the inbox, the message shows a warning that names each figure, for example "$41.400 is not in the agent's knowledge or this conversation". The conversation carries a Figure to check badge in the list, and the Figures to check filter lists every conversation with a figure nobody has checked yet.

Check the figure. If it is wrong, write to the customer with the right one. Then click Mark as checked. The warning becomes one line, "Figure checked by" your teammate's name and the time, and the badge goes away. Anyone on your team who can open the conversation can mark it, whatever the 24-hour window says.

Why am I seeing this? under the warning opens a short explanation in place: what was checked, why a correct figure can still be flagged, and what marking it checked records.

Stop flagging figures from one agentCopy Anchor Link

If an agent's figures are flagged often and your team trusts them, you can stop that agent's flags. The agent keeps answering exactly as before; its future messages are simply sent without a warning, even when they state a figure nothing in its sources contains. Every other agent keeps flagging.

There are two places to do it, and both are for Admins and Owners only:

• From the inbox. On a flagged message, tick Stop flagging figures from the agent's name, then click Mark as checked. The figure is marked checked and flagging stops for that agent in the same step. Other team members see the box greyed out, with a line saying only admins and owners can change it.
• From the agent's settings. In the agent's Handoff section, turn off Flag unverified figures and save.

Once it is off, a flagged message from that agent says "Flagging is off for" the agent. To turn it back on, switch Flag unverified figures on again in the agent's settings. Flags that were already raised stay until someone marks them checked, because those messages were sent and still deserve a look.

Whatsable still records, internally, which figures each reply held, so turning flagging back on later starts from a full picture.

Make flags rarerCopy Anchor Link

• Write the prices, fees and dates your customers ask about into the knowledge, in the format you want the agent to use.
• If the agent often quotes totals, add the common totals, or tell it in its instructions to quote unit prices and let your team confirm a total.
• A flag that keeps coming back for the same figure is a sign that figure belongs in the knowledge.

Through the API and the MCP serverCopy Anchor Link

Every message returned by the API v1 carries unverified_figures, the flagged figures (empty for other messages), and figures_checked_at, when a teammate marked them checked (null until then). An AI assistant connected through the MCP server sees the same in the messages it reads. Marking figures as checked is done in the inbox; it is not available through the API yet.

The AI agent object carries flag_unverified_figures (true by default). Read it with the get AI agent endpoint, and set it to false or true with the update AI agent endpoint to stop or restart an agent's flags; the get_ai_bot and update_ai_bot tools of the MCP server do the same. Messages already flagged keep their flags.

A follow-up template the agent proposes to Meta is different: it is reused for many customers and cannot be corrected once approved, so a proposal with a figure that is not in the agent's knowledge is not proposed. A figure the customer wrote does not count there.

Next stepsCopy Anchor Link