---
title: "WhatsMCP AI agents — documentation"
description: "Run an AI agent on your WhatsApp number — bring your own LLM key, give it office hours and rules, ground it in a knowledge base, and hand any chat to a person. Setup, handover, knowledge and limits."
url: "https://whatsmcp.com/docs/agents"
---

# 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](https://whatsmcp.com/docs/mcp)), 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](https://console.whatsmcp.com) — 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](#about-this-service) — 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](https://whatsmcp.com/plans).

## 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](#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](#put-an-agent-on-a-number)).
-   **Knowledge** — the knowledge bases it reads (see [Knowledge bases](#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](https://whatsmcp.com/plans) |
| 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.