AI agents documentation

Quick start

1. Create a workspace     →  https://console.whatsmcp.com/register
2. Link a WhatsApp number →  Console → Pair device (scan the QR)
3. Add your LLM key       →  Console → AI agents → Settings → Add a key
4. Build an agent         →  Console → AI agents → New agent → write its Instructions → Publish
5. Put it on the number   →  the agent's Channels tab → add the number, tick the acknowledgement

An AI agent answers your incoming WhatsApp messages with a large language model you own. It runs in WhatsMCP’s cloud on a number you’ve linked (pair one the usual way — see the MCP server docs), reads each message, and replies in your agent’s voice, with its hours, rules and knowledge applied. You build and run it in the console — no code, and nothing to host.

Agents work on both kinds of WhatsApp number: an official Business (Cloud API) number, and a regular Personal number linked as a device. A Personal number is unofficial and can be banned — you acknowledge that before an agent goes on one.

Agents need a plan that includes AI agents, and the workspace’s agents switch must be on. Prices and what each plan includes are on the plans page.

How it works

Every inbound message is recorded with a decision — whether the agent answers, and if not, why. When it does answer, the reply is paced by a short delay, written with your model, and sent through WhatsApp in at most three parts with the AI disclosure first. Each reply counts against the number’s monthly cap and is billed to your own LLM key.

  inbound WhatsApp message
    → decide: answer?  (hours · rules · opt-out · country · who it is)
    → read knowledge   (if the agent uses it)
    → write a reply with YOUR LLM key
    → send: AI disclosure first, then up to 3 parts

The agent answers only while the workspace’s agents switch is on and the number’s plan still has replies left for the month. A reply you type on the phone pauses the agent in that chat — see Handover to a person.

Bring your own LLM key

An agent replies with your model, on your key — WhatsMCP never charges you for tokens. Add keys in Console → AI agents → Settings:


Providers	Anthropic, and any OpenAI-compatible endpoint — OpenAI, xAI, Gemini, DeepSeek, Mistral, OpenRouter, Groq, or your own
On save	the key is verified with one small test call, then stored encrypted and write-only — only its last four characters are shown again
Scope	keys belong to the workspace; every agent in it can use them
Rotate / delete	replace a key in place, or delete it — agents that answered with it stop until another is set

Choose an API plan that does not train on your data: the conversations your agents handle are your customers’.

Build and publish an agent

Open Console → AI agents → New agent. An agent is edited as a draft and goes live when you Publish it; each publish is an immutable version you can restore, and you can pause or resume a live agent at any time. The editor has these tabs:

Instructions & model — the agent’s instructions (up to 32,000 characters) and which of your keys and models it answers with. The AI disclosure is required: a short line (≤ 300 characters) added to the agent’s first message so the person knows they’re talking to a bot. Here you also set the words that hand a chat straight to a person, and how long a handover lasts.
Rules — office hours per day; outside them, send an away message or answer anyway. An allow list / block list by number, prefix (+4420*) or label (label:vip), a country filter, and opt-out words (STOP is always on and can’t be removed). Per-day reply caps come from the number’s plan.
Channels — the numbers the agent runs on (see below).
Knowledge — the knowledge bases it reads (see Knowledge bases).
Test — a playground that runs the draft (or live) version against a message you type, as a new, known or blocked contact, on WhatsApp or WhatsApp Business. Nothing is sent and nothing is counted.

Put an agent on a number

On the agent’s Channels tab, add one of your linked numbers. Before it starts you confirm how the number may be used:

Personal number — tick the acknowledgement that WhatsApp’s terms don’t allow automated messaging from a personal account, so WhatsApp may restrict or ban it.
Business (official) number — tick the confirmation that it’s used within Meta’s rules.

One agent can run on several numbers, and you can Pause here / Resume here on a single number without pausing the whole agent. The Activity tab shows every conversation and the decision behind it — answered, not answered, away, handed over or opted out.

Knowledge bases

Ground an agent in your own content so it answers from fact instead of guessing. A knowledge base holds three kinds of source:

Source	Formats	Size
Files	PDF (with a text layer), Word, HTML, Markdown, CSV, plain text	20 MB each
Text	pasted straight in	64 KB each
Questions & answers	one or more Q&A pairs	64 KB each

Add them on the agent’s Knowledge tab (create a base first if you have none). Files upload straight to storage and are indexed in the background — cut into passages under their headings and searchable by keyword right away. Each base shows its size and document count against your plan’s MB and document limits; knowledge bases belong to the workspace, so any agent can read them.

Search by meaning (optional)

By default knowledge is searched by keywords. Add one of your OpenAI keys in Settings → Embeddings and every passage is also embedded (text-embedding-3-small), so search works by meaning and keyword together — billed to that key. Anthropic and xAI keys can’t embed; if embedding stops, search falls back to keywords until you retry the key.

How the agent uses it

On the Knowledge tab, choose which bases the agent reads and how:

Before every reply — the best passages are added automatically. Fast and predictable.
When the agent decides — it searches only when it needs to. Better for a large library.

Set passages per reply (1–10, default 5), and use Try a search to preview what a question would retrieve.

An agent with no knowledge base answers from the model alone and can state things that aren’t true of your business. Give it a knowledge base — even a few questions and answers — before you put it in front of customers.

Handover to a person

An agent never traps a customer with a bot:

Reply from your phone and the agent steps back from that chat. It gives the chat back after the time you set — 1 hour, 4 hours, 24 hours, or never (resume by hand) — and the Activity tab shows the chat as Paused · you replied, with a Give back to agent button.
Handover words (set on Instructions & model) hand a chat to a person straight away; on a Business number the agent can send a handover contact.
A customer’s opt-out word (STOP) stops the agent for that person until they opt back in.

Limits and troubleshooting

Symptom	Cause / fix
Agent doesn’t answer at all	The workspace’s agents switch is off, or the number isn’t on a plan with AI agents
One chat gets no replies	You replied from the phone — it’s paused; use Give back to agent on Activity, or wait out the handover window
Replies stopped this month	The number hit its plan’s monthly reply cap
A key shows Rejected	The provider refused it — Rotate / replace it in Settings; agents resume once a valid key is set
Replies outside office hours	The agent sends your away message, or answers anyway — set on Rules
Knowledge tab says the plan doesn’t include it	The number’s plan has no knowledge bases — see the plans page
Knowledge “searched by keywords only”	No OpenAI embedding key, or embedding stopped — set or retry it in Settings → Embeddings
A message was skipped	Activity shows the reason — away, opted out, blocked, or a country / allow-list rule

About this service

An agent on a Business (official) number runs on Meta’s WhatsApp Cloud API and stays within Meta’s rules.

An agent on a Personal number uses a regular WhatsApp account linked as a device. That is unofficial, not affiliated with or endorsed by Meta, and outside WhatsApp’s terms — automated messaging from a personal account can get the number restricted or banned. The console makes you acknowledge this before an agent goes on a Personal number; weigh it before putting a number you depend on behind one.

Agents answer with your LLM key, so conversations go to the provider you chose — pick an API plan that doesn’t train on your data. WhatsMCP mirrors a number’s chats only to run its agent, and keeps them only for a limited time.