#An AI agent on WhatsApp

WhatsApp is an added channel for the agent that already serves your app. You ask for it, talk to the agent from your own phone on a shared preview number (no Meta account needed), and when it answers well you publish it and connect your own number. This guide is the task path: what to ask for, what you will see, how to try it and what to check before going live. Every option of the channel is in the WhatsApp reference.

#Start from your app's agent

WhatsApp is not a separate agent. It is one more channel for the agent your app's users already reach in the web widget or the mobile SDKs, and the app is the starting point.

Fastest, from any chat. Add the remote MCP server https://vatio.ai/mcp as a connector in Claude, ChatGPT or Cursor, sign in with a Vatio account and ask for the agent. It is created in a preview to try; nothing reaches users until you publish (Vatio in Claude and ChatGPT).
To build the agent into your app's code. In the project run npx @vatio-ai/skills, then /vatio-init, and /vatio-improve daily. See Build an AI agent for your app.

Then ask your coding agent or chat to add WhatsApp. WhatsApp messages are short, so ask for:

short messages, the way people write on WhatsApp;
the cases a person should handle, through the tool the agent uses to ask for one (Handoff);
sign-in and lookups for people's own data (Authentication).

A trimmed vatio.yml for an app where customers book and follow bike repairs, for you to review:

workspace: northside-bikes
agent:
  name: Northside Bikes
  personality: Friendly and brief. Short messages, the way people write on WhatsApp.
  instructions: |
    You answer customers of Northside Bikes, a bike shop and repair
    workshop at 214 Lake Street. A standard tune-up takes two working days.

    If you do not know something, say so and offer to pass the question
    to the team. Never invent a price, a stock level or a pickup date.
  tools: [ask_for_a_person]

tools/ask_for_a_person.yml calls your backend with a link to the conversation, and your backend alerts whoever should answer:

description: Tell the shop that this conversation needs a person.
when_to_use: >
  A complaint about a repair or a charge, a quote for a custom build, or
  the customer asks to talk to a person.
parameters:
  type: object
  properties:
    reason: { type: string, description: "Why it needs a person, in one line" }
  required: [reason]
access: public
request:
  method: POST
  base_url: "$env.SHOP_API"
  path: /vatio/ask-for-a-person
  requires: [chat.url]
  headers:
    Authorization: "Bearer $env.SHOP_API_KEY"
  body:
    reason:
    chat_url: "$chat.url"
    name: "$contact.name"
    phone: "$contact.phone_number"
respond:
  message: >
    The shop was told. Tell the customer plainly that you are checking this
    with a colleague, who will answer here.

Opening hours go in the instructions, next to the address. When the facts outgrow the instructions, move prices and services into Knowledge. The agent then pushes the change to preview and tries it:

vatio push
vatio chat "hi, are you open saturday?"
vatio chat "the gears you fixed last week are worse than before"
vatio chat show

The second message is a complaint, so it should call ask_for_a_person; chat show says whether it did, with every tool call. vatio chat tests what the agent says, not how WhatsApp delivers it. For that you need a phone.

#Test it on the shared preview number

You do not need a Meta account. Open Try the agent → WhatsApp in the inbox, scan the QR code with your phone and send the message it writes; that proves the phone is yours. Then write to the agent and read the conversation under Tests in Conversations. Under each reply is what the agent did: the tools it called and the knowledge it read. The steps, the limit of five test phones, /new and how codes work are in Test with the shared preview.

A test phone reaches preview, never live. Write the way customers do: three short messages in a row, a voice note, a photo. That is the test vatio chat cannot run.

#Connect your own number

When the preview is right, publishing is your decision: ask to publish (vatio publish). The Free plan includes the owner's own number; see Pricing.

Then open WhatsApp in the inbox on live, choose Connect WhatsApp and complete Meta's signup. A newly connected number is paused: it keeps working as before until you switch Live on. Verify checks that Meta is delivering the number's messages. If the number belongs to a client or partner, invite them from the same page; When your client has the number has the flow.

Before you switch Live on, check:

the preview answered the cases you care about, including the one that asks for a person;
you want it to answer everyone who writes to the number: it answers all of them, and switching Live off stops it;
you know what Meta charges the business for the number's messages: What Meta charges.

From then on each version you approve for publication changes what the number answers with, and vatio rollback restores the previous one.

#Keep the WhatsApp Business app

The connection supports keeping the app on your phone, and the two work together:

A reply from the app is a takeover: it pauses the agent on that conversation.
Hand it back from the inbox with Hand back to agent, or the takeover expires 8 hours after the last reply from your team.
The agent can ask for a person too. It calls ask_for_a_person and your backend decides whom to tell (a WhatsApp, a Slack channel, an email). Until someone answers, the agent keeps helping and says it is checking with a colleague. Calling the tool is the model's decision, so try it on the preview number.

See Handoff for takeovers.

When a reply was wrong, choose Report this reply on it in the inbox and write what should have happened. /vatio-improve fixes the cause, pushes preview and tests the reported cases; you approve publication. See Improve.

#How a WhatsApp conversation behaves

A conversation lasts until eight hours of silence. The next message after that starts a new chat.
Fragments become one question. Vatio groups messages that arrive together and waits for a quiet moment before answering, including for a voice note or photo still being processed.
Edits and deletes follow the contact. An edit rewrites the message in place and is not a new message; a message deleted for everyone leaves the inbox and the agent's history.
Voice notes, images, PDFs and videos are read. Audio is transcribed, supported images and PDFs up to 8 MB per file reach the agent, and a video up to 14 MB is watched once. Anything unsupported or larger stays available to supervisors, and the agent is told it cannot read it.
Replies are text, paced like a person typing. With send_image the agent also sends photos your tools returned, such as a product from your catalog, right after its reply. It never sends files or audio, and never generates an image.
Links are allowlisted. The agent only sends URLs it was given, in links, in its instructions or in a tool's result. Any other URL is stripped.
The agent answers the rating. Ratings shows how to ask a happy contact for a review.

#Who the agent is talking to

A WhatsApp contact starts out anonymous to your backend. Public tools run for anyone. A tool marked access: private, one that reads a person's records behind a login, needs them signed in: with auth.sign_in_url set Vatio sends a Sign in button that opens your site, and the conversation carries on once they are back. With auth.identify_url set, Vatio asks your backend who the number is first. See On WhatsApp and Instagram.

For customers who never signed up, the usual pattern is a public tool that takes a reference plus a second factor, with your backend checking that they match. The model fills a tool's parameters, so that check lives in your backend, which answers 404 when they do not match, never in the prompt. Your agent stores the API address and key as secrets:

vatio secrets set SHOP_API https://api.northside-bikes.example
vatio secrets set SHOP_API_KEY sk_live_...

tools/check_repair.yml:

description: Look up the status of a bike repair.
when_to_use: The customer asks whether their bike is ready or how a repair is going.
parameters:
  type: object
  properties:
    ticket: { type: string, description: "Repair ticket number, e.g. R-2041" }
    phone_last4: { type: string, description: "Last four digits of the phone number on the ticket" }
  required: [ticket, phone_last4]
access: public
request:
  method: GET
  base_url: "$env.SHOP_API"
  path: /repairs/status
  headers:
    Authorization: "Bearer $env.SHOP_API_KEY"
  query:
    ticket:
    phone_last4:
respond:
  data:
    repair: "$.repair"

A tool that needs the customer's own phone number, for example to book a call back, reads $contact.phone_number with contact.phone_number under requires, and has no phone parameter for the model to fill. If a customer hides their number behind a WhatsApp username, Vatio sends a one-tap button to share it the first time the tool runs. The number says how to reach the customer, not who they are, so check_repair keeps its second factor.

More on tools and signed-in users: Tools and Authentication.

#What Vatio does not do on WhatsApp

The agent never decides on its own to write first. When your backend needs to (a reminder, an order update, a campaign list), it asks through the Messages API, one request per contact: within 24 hours of the person's last message it sends your text or has the agent write it from a brief, and after that WhatsApp only delivers an approved template. See Send from your backend. Vatio has no campaign dashboard to upload lists, segment them or schedule sends: that logic lives in your backend. There are no voice calls, and the agent never generates images or files: the only photos it sends are ones your tools returned.

#Instagram is the same agent

Instagram DMs work the same way, with a shared preview account and your own professional account connected from Instagram in the inbox. See An AI agent on Instagram.

#Frequently asked questions

#Do I need a Meta account to test an AI agent on WhatsApp?

No. Vatio has a shared preview number. You add up to five phones as test numbers in Try the agent in the inbox, connect each by scanning a QR code and sending the message it writes, and message the agent from them. You only go through Meta's signup when you connect your own number for live traffic.

#Can I keep using the WhatsApp Business app after connecting an AI agent?

Yes. A reply sent from the app takes that conversation over and pauses the agent there; hand it back from the inbox, or the takeover expires 8 hours after the last reply from your team.

#Can the agent send WhatsApp campaigns or reminders?

Yes, from your backend, through the Messages API once per contact. Within 24 hours of the person's last message it sends your text or has the agent write it from a brief; after that WhatsApp only delivers an approved template. Vatio has no campaign dashboard: your backend picks who and when.

#Does the agent understand voice notes and photos on WhatsApp?

Yes. Voice notes are transcribed, supported images and PDFs up to 8 MB per file are passed to the agent, and a video up to 14 MB is watched once. Its replies are text, and with send_image it can also send a photo one of your tools returned.

#Can the agent look up a customer's account on WhatsApp?

Yes, once the customer signs in. Public tools run for anyone, and a tool marked access: private runs for a signed-in contact. For customers without an account, use a public tool that takes a reference number plus a second factor, checked by your backend.

#How long does a WhatsApp conversation with the agent last?

Until the customer's last message is more than eight hours old. The next message after that starts a new chat.

An AI agent on Instagram: The same agent on Instagram DMs.
Build an AI agent for your app: The two-step entry, from a chat or in your app's project, and trying the preview before publishing.
How the agent runs: What happens on each turn.

Latest CLI version: 0.114.0 · Changelog · The whole contract as Markdown: /docs/docs.md · or vatio docs