#An AI agent on WhatsApp

To put an AI agent on WhatsApp with Vatio, you describe it in one vatio.yml, push it, and talk to it from your own phone on a shared preview number, with no Meta account. When it answers well, you connect your business number through Meta’s signup from Vatio’s inbox and switch Live on. The agent answers what people send, voice notes, photos and PDFs included, and anyone on your team can take a conversation over from the inbox or from the WhatsApp Business app.

This guide goes from an empty folder to your own number, and covers what the agent can and cannot do once it is there.

#Start with a minimal agent

You need Node.js 20 or newer. vatio init asks for no account; the first vatio push opens your browser to sign in with email, Google or GitHub, and that creates one.

npx @vatio-ai/skills
npm install -g @vatio-ai/cli@latest
vatio init northside-bikes

Replace the starter vatio.yml with something this small:

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. We are open Monday to Friday 9:00-18:00
    and Saturday 10:00-14:00. 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.
  handoff:
    when:
      - a complaint about a repair or a charge
      - the customer wants a quote for a custom build

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 be handed over; chat show tells you whether it was, with every tool call. When the facts outgrow the instructions, prices and services move into a knowledge base; Build an AI agent covers that step.

vatio chat replies the moment an answer is ready, so it tests what the agent says, not how WhatsApp delivers it. For that you need a phone.

#Test it on the shared preview number

The preview number belongs to Vatio, so you can test on real WhatsApp before touching Meta. It all happens in the WhatsApp tab of the Test page in the inbox:

1. Open Test → WhatsApp. A phone you already verified on another workspace you own is listed under You already verified these numbers, and Use on preview connects it in one click, with no code.
2. Otherwise, under Connect your phone, scan the QR code with your phone. WhatsApp opens on the shared preview number with a message already written, carrying a 6-character code: send it. With no camera at hand, send that code to the preview number yourself; the page shows both. That message is what proves the phone is yours. Vatio replies right away with “Your phone is verified ✅”, and the page updates by itself.
3. Write to the agent from that phone, and read the conversation under Conversations, in the same inbox. Under each of the agent’s replies is what it did: the tools it called and what they returned, and the knowledge it read. It is the same inbox your team answers from once the agent is live.

You can register up to five test phones per workspace, so the shop owner and a colleague can try it too: Add another number, under the list, shows a new QR code. A code lasts 15 minutes and works once, and the QR code on the page renews itself. A verified phone routes to one workspace at a time; sending another workspace’s code from it, or choosing Use on … in another workspace, moves it to that one.

Each test phone reaches preview, so a change can be tried on WhatsApp before it is published. It never reaches live: live is your own number.

Now write the way customers do: three short messages in a row, a voice note, a photo of a bent wheel. That is the test vatio chat cannot run.

#Connect your own business number

When the preview is right, publish it:

vatio publish

Then, in the inbox, open Channels → WhatsApp on live, choose Connect WhatsApp and complete Meta’s signup in the window that opens. Publishing from the inbox instead, with Publish to live on the Test page, runs your tests first; after the agent’s first publish, Published. Next: put it in your app connects WhatsApp from there too.

A newly connected number is paused. It keeps working exactly as before until you switch Live on, which is what starts replies from your live deployment. That leaves time to check the connection: the same modal says whether Meta is delivering the number’s messages, and Verify runs that check again. Switching Live off pauses replies without disconnecting anything. To change numbers, delete the integration first and connect the new one.

If the number is your client’s, you do not need their Facebook login. Under Does your client have the number? in the same modal, invite whoever has it by email. They join as a supervisor, connect the number from a page of their own, and you get an email once it is in. Meanwhile the modal shows the step each person you invited has reached, from opening the invite to Meta’s signup, so you know whether to wait or help. Switching Live on stays with you.

From then on, vatio publish changes what the number answers with, and vatio rollback restores the previous version.

#Keep the WhatsApp Business app

You do not have to give up the app on the shop’s phone. The connection supports keeping it, and the two work together:

• A reply from the app is a takeover. It reaches Vatio and pauses the agent on that conversation, exactly like a reply from the inbox.
• Hand it back from the inbox when the agent should resume, with Hand back to agent on the conversation. Or leave it: a takeover expires 8 hours after the customer’s last message, and every human reply restarts that clock.
• The agent can ask for a person too. The handoff block above lets it pass on complaints, and a customer who asks for a person in plain words always gets handed over. Inside the business hours, set on the inbox’s Business page, the agent then goes quiet; outside them it keeps helping. A handoff nobody picks up within an hour goes back to the agent.

Vatio does not notify anyone of a handoff yet. The conversation shows as waiting in the inbox, so someone has to be watching it.

#How a WhatsApp conversation behaves

• A conversation lasts until eight hours of silence. Vatio continues the latest conversation until the customer’s last message is more than eight hours old; the next message starts a new chat.
• Fragments become one question. Vatio groups messages that arrive together and waits for a quiet moment before answering, and it waits for a voice note or photo that is still being processed. Fluid conversations explains why that matters.
• An edit rewrites the message. When the customer edits a message within WhatsApp’s 15 minutes, or you edit a reply from the WhatsApp Business app, the inbox shows the new text marked as edited and the agent reads it from then on. An edit is not a new message: the agent does not answer it, and it does not take over the conversation.
• A deleted message is gone. When the customer deletes a message for everyone, within WhatsApp’s two days, or you delete one from the app, it disappears from the inbox and from what the agent reads.
• Voice notes, images and PDFs are read. Audio is transcribed, and supported images and PDFs up to 8 MB per file reach the agent. 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. On WhatsApp a reply arrives as short plain-text messages with pauses and typing indicators, not one long block. The agent cannot send images, files or audio.
• 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 from the reply.

#Who the agent is talking to

A WhatsApp contact starts out anonymous to your backend: there is no page where it can sign a token saying who they are. Public tools run for anyone. A tool marked access: private, one that reads a person’s records behind a login, needs them signed in, so Vatio sends them to your site to do it. Add your sign-in page to auth:, next to the public key that verifies your tokens:

auth:
  public_key: identity.pub
  sign_in_url: https://northside-bikes.example/vatio/sign-in

When a private tool runs for a contact who is not signed in, Vatio sends them a Sign in button. It opens your page with a one-time code; your page signs them in the way your site already does and redirects to https://vatio.ai/connect/<code>?token=<jwt>, with the same JWT you put on the web widget. Vatio asks them to confirm the WhatsApp number, a step it skips when the token’s phone_number claim matches, and the conversation picks up where it left off: the agent runs the tool it was waiting on. The token stays with the contact until its exp. With the vatio-sdk gem, the page is one redirect to Vatio::Identity.sign_in_redirect_url; On WhatsApp and Instagram in the docs has the details.

Not every lookup needs an account. 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. Store the API address and key as secrets first:

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
  requires: [params.ticket, params.phone_last4]
  headers:
    Authorization: "Bearer $env.SHOP_API_KEY"
  query:
    ticket: "$params.ticket"
    phone_last4: "$params.phone_last4"
respond:
  data:
    repair: "$.repair"

The model fills a tool’s parameters, so the check that the ticket goes with those digits lives in your backend, which answers 404 when they do not match. Never leave it to the prompt.

Sometimes a tool needs the customer’s own phone number, for example to book a call back. On WhatsApp the agent already has it: request_callback is a POST whose body carries $contact.phone_number, with contact.phone_number listed under requires and no phone parameter for the model to fill. If a customer hides their number behind a WhatsApp username, Vatio sends them a one-tap button to share it the first time the tool runs; the number arrives with their next message, and the tool can run then. There is nothing to enable and nothing for the agent to ask. The number says how to reach the customer, not who they are, so check_repair keeps its second factor:

agent:
  instructions: |
    ...
    Repair status: ask for the ticket number and the last four digits of
    the phone number on the ticket, then call check_repair.
    Call backs: call request_callback. It already has their number.
  tools: [check_repair, request_callback]

Connect your backend goes further into tools and signed-in visitors.

#What Vatio does not do on WhatsApp

The agent never decides on its own to write first. When your business needs to, whether it is a reminder, an order update or everyone on a campaign list, your backend asks for it through the Messages API, one request per contact and up to 60 a minute per key: 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 a template Meta approved, which the inbox lists under Outreach → Templates. The agent handles the replies knowing what the message was about, and opt-outs and conversations a person has taken over are respected. What Vatio does not have is a campaign dashboard to upload lists, segment them or schedule sends: that logic lives in your backend. There are no voice calls either, and the agent never generates images or files.

#Instagram is the same agent

Instagram DMs work the same way: a shared preview account with up to five test accounts, then your own professional account connected from Channels in the inbox. It is the same agent, with the same inbox and the same sign-in, except that the confirmation shows the @handle instead of a number, and is always shown. See the Instagram docs, and the WhatsApp docs for every option on the Channels page.

Updated: October 11, 2026