WhatsApp connection | Automata docs

Connect data sources

New to the idea of a WhatsApp MCP? Start with the WhatsApp MCP overview for what it does and how per-chat permissions work. This page covers setup.

Automata provisions one Evolution API instance per WhatsApp connection. Pairing, chat listing, and sending use Evolution; message reading and search query its PostgreSQL datastore directly, because the Evolution API cannot search or page history efficiently.

Use a spare number for testing

Pairing binds a real WhatsApp account. Repeated pair and unpair cycles or unsolicited messages can cause rate limits or a ban. Do not experiment with a primary phone number.

What you need

Evolution API v2.3.7, Redis, and PostgreSQL
A generated EVOLUTION_API_KEY
A matching NUXT_EVOLUTION_ADMIN_KEY on the web service
NUXT_EVOLUTION_DATABASE_URL for message reads and search
A webhook URL reachable from Evolution

The Evolution database URL can be the owner URL. Message reads only run fixed, parameterized SELECT statements in read-only sessions. A dedicated SELECT-only role is optional hardening:

CREATE ROLE wamcp_search LOGIN PASSWORD '<strong-password>';
GRANT CONNECT ON DATABASE evolution TO wamcp_search;
GRANT USAGE ON SCHEMA public TO wamcp_search;
GRANT SELECT ON "Message" TO wamcp_search;

Start the WhatsApp stack

pnpm services:up:whatsapp
pnpm dev

Confirm Evolution at http://localhost:8080 and the app at http://localhost:3000. For a deployed stack, use the whatsapp profile in Docker Compose or the Evolution service in Railway.

Pair an account

Create a WhatsApp account connection, continue to the QR code, then scan it from WhatsApp → Settings → Linked devices → Link a device.

Wait for the dashboard to report the connection as open before creating a token. A scoped send is refused when Automata cannot verify a recipient because the account is disconnected.

Message history

read-messages and search-messages require NUXT_EVOLUTION_DATABASE_URL. Without it, pairing, chat listing, and sending still work, but read tools return a missing-prerequisite response.

Full history is offered only while a device is linked. Before scanning, keep DATABASE_SAVE_DATA_HISTORIC=true; Automata creates new instances with full-history sync enabled. To import history for an older connection, use Import full history, then rescan the QR code. The phone still decides the ultimate history depth.

Things to expect from the stored history:

Group conversations are included alongside private chats.
Media is not downloaded; messages carry their text or caption.
Reactions are omitted unless a tool is called with includeReactions: true.
The dashboard counts conversations reported during pairing, while list-chats counts conversations that have stored messages, so the numbers can differ.

Protect the session volume

Never use docker compose down -v for a routine restart. Deleting the evolution_instances volume unpairs every WhatsApp account and forces new QR scans.

Bring your own Evolution

Select Use my own Evolution API server and provide both the server origin and its global key. Automata never fills a missing half from the deployment default, and it never sends one server key to another server.

A bring-your-own connection also needs a database URL for that Evolution server before message read tools can work. Automata validates that the database contains a readable "Message" table before saving it. Without a database URL, read tools return an explicit error instead of empty results.

View source