#An AI agent on Instagram

To answer Instagram DMs with an AI agent in Vatio, you describe the agent in one vatio.yml, push it, and talk to it from your own Instagram account through a shared preview account, before connecting anything. When it answers well, you publish it and connect your professional account through Meta’s consent screen from Vatio’s inbox; from then on, your live agent answers every DM sent to that account. It is the same agent that answers on WhatsApp and your website, it reads the screenshots and voice notes people send, and anyone on your team can take a conversation over from the inbox.

This guide covers the conversations Instagram brings in, testing them, and connecting the account.

#One agent, every channel

There is no separate Instagram agent. A workspace runs one agent, and the channel only changes how its replies are delivered, so an agent already on WhatsApp or your website is ready for Instagram. If you have none yet, 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 marlow-home

An agent for a furniture and decor shop that sells mostly through its Instagram:

workspace: marlow-home
agent:
  name: Marlow Home
  personality: Friendly and quick. Short messages, the way people write in DMs.
  instructions: |
    You answer customers of Marlow Home, a furniture and decor shop that
    sells online and from its showroom at 88 Harbor Road.

    Every product has a code like MH-0412, on the image and in the caption
    of each post. When someone asks about a product, look for the code in
    their message or screenshot and call find_products with it. Without a
    code, search by what they describe or what the image shows, and ask
    which one they mean if several match. Give the price, whether it is in
    stock and the product link the tool returned.

    If they send something you cannot see, such as a video, ask for the
    product code or a screenshot. For shipping, returns and the showroom,
    search knowledge_lookup first.

    Never invent a price, a stock level or a delivery date.
  tools: [find_products, knowledge_lookup]
  knowledge: [shop]
  handoff:
    when:
      - a damaged delivery or a complaint
      - a custom order or a trade discount

#What people send on Instagram

Instagram DMs are short: “price?”, “info”, “still available?”, “do you ship to Denver?”, often with a screenshot, because the person wrote from the feed. A typical exchange:

Customer: price? (screenshot of a post)

Agent: That’s the Linden oak side table, MH-0412: $189, and it’s in stock. https://marlow-home.example/p/mh-0412

Customer: do you ship to denver

Agent: We do. Furniture ships for $35 per order and takes 5 to 7 working days to Colorado. You can also pick it up at the showroom for free.

Behind those replies, the agent read “MH-0412” in the screenshot, called find_products with it and looked up shipping in the knowledge base. The link came back from the tool, which is what allows the agent to send it. Three habits make this work:

• Put a code on every post, on the image and in the caption. The agent reads images, so a screenshot with a code in a corner becomes a lookup by code instead of a guess about which oak table it was.
• Answer before asking. “price?” deserves a price; questions come after.
• Prices and stock come from a tool, and everything that changes slowly from knowledge.

Store the API address and key as secrets:

vatio secrets set SHOP_API https://api.marlow-home.example
vatio secrets set SHOP_API_KEY sk_live_...

tools/find_products.yml:

description: Search the catalog by product code or by description.
when_to_use: The customer asks about a product, its price or stock, by code, by description or with a screenshot.
parameters:
  type: object
  properties:
    code: { type: string, description: "Product code, e.g. MH-0412" }
    query: { type: string, description: "What the customer describes or the image shows, e.g. oak side table" }
access: public
request:
  method: GET
  base_url: "$env.SHOP_API"
  path: /products/search
  headers:
    Authorization: "Bearer $env.SHOP_API_KEY"
  query:
    code: "$params.code"
    q: "$params.query"
respond:
  data:
    products: "$.products"
  message:
    when_empty: No product matches that code or description.
    default: "Found {{count}} matching products."

Have the endpoint return each product’s name, price, stock and page URL, and nothing you would not put on a post: whatever a tool returns, the model can repeat.

Shipping, returns and the showroom go in a knowledge base, one entry per topic:

vatio kb create shop
vatio kb write shop shipping shipping.md
vatio kb write shop returns returns.md
vatio kb write shop showroom showroom.md

# Shipping

## Cost and delivery times
Small items ship for $9 and furniture for $35 per order. Delivery takes
3 to 5 working days on the East Coast and 5 to 7 elsewhere in the
continental US. Pickup at the showroom is free.

Vatio does not read websites, and a caption the agent was never sent is not something it knows: put what matters in an entry or behind the tool.

#Test it on the shared preview account

vatio push
vatio chat "how much is MH-0412?"
vatio chat "the lamp I ordered arrived broken"
vatio chat show

The second message is a damaged delivery, so it should be handed over; chat show tells you whether it was. vatio chat sends text and replies instantly, so screenshots and pacing need Instagram itself, on Vatio’s preview account. It all happens in the Instagram tab of the Test page in the inbox:

1. Open Test → Instagram. An account you already verified on another workspace is listed under You already verified these accounts, and Use on preview connects it in one click, with no code.
2. Otherwise, under Connect your account, scan the QR code with your phone: it opens the DM with Vatio’s preview account. From the account you will test from, send it the code the page shows; on a computer, DM the account the page names and send the code. That DM proves the account is yours: Vatio answers right away with “Your account is verified ✅”, and the page updates by itself.
3. Keep talking to the agent in that DM, and read the conversation under Conversations, in the same inbox.

Instagram does not let Vatio write first, so your account sends the code instead of receiving one. A code lasts 15 minutes and works once, and the one on the page renews itself. An account routes to one workspace at a time; sending another workspace’s code from it, or choosing Use on … in another workspace, moves it there.

A workspace can have up to five test accounts: Add another account, under the list, shows a new code. Each reaches preview, so a change can be tried on Instagram before it is published. It never reaches live: live is your own account.

Then write the way your followers do: a screenshot with “price?”, three short messages in a row, a voice note about delivery.

#Connect your professional account

When the preview is right, publish it:

vatio publish

Then, in the inbox, open Channels → Instagram on live, choose Connect Instagram and complete Meta’s consent 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 Instagram from there too. It has to be a professional account, and the consent asks to read its profile and manage its messages.

There is no switch to turn on afterwards: as soon as the account is connected, your live deployment answers its DMs, which is why you publish first. The same modal says whether the account is receiving DMs (Live — answering DMs when it is), and Verify runs that check again.

A workspace connects one account, and an account connects to one workspace; to change accounts, delete the integration first. Vatio refreshes the access token automatically, and if it ever expires, Reconnect the same account.

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

#How an Instagram conversation behaves

• A conversation lasts until eight hours of silence. After the customer’s last message is more than eight hours old, the next one starts a new chat.
• Fragments become one question. Vatio groups messages that arrive together, waits for a quiet moment and for media still being processed, then answers once. Fluid conversations explains why.
• Edits and unsends follow the customer. An edited DM shows its new text in the inbox, marked as edited, and the agent reads it from then on; an unsent one disappears from both. Neither is a new message, so the agent does not answer it.
• Images, voice notes and PDFs are read. Supported files up to 8 MB each reach the agent, and audio is transcribed. Anything else, such as a video or a shared reel, stays available to supervisors, and the agent is told it cannot read it.
• Replies are text, paced like a person typing: short plain-text messages with typing indicators. The agent cannot send images or files, so the product page carries the photos and the link is what it sends.
• Links are allowlisted. The agent only sends URLs it was given, in links, its instructions or a tool’s result. Any other URL is stripped.

#Who the agent is talking to

An Instagram contact starts out anonymous to your backend: there is no page where it can sign a token saying who they are, so until they sign in only public tools run. A customer’s own orders or account belong behind a login, in a tool marked access: private. With sign_in_url in auth:, that tool sends the customer a Sign in button that opens your site; your page redirects back with the same token you put on the widget, Vatio asks them to confirm the @handle being connected, and the conversation picks up where it left off (On WhatsApp and Instagram). An AI chat for your website shows how to sign the token.

A DM carries no phone number either. On WhatsApp the agent already has the customer’s number; on Instagram it has one only if the customer types it. A tool that needs a phone or an email, say to book a showroom visit, takes it as a parameter, and your backend validates it. To check an order for someone who has not signed in, take the order number plus a second detail, such as the email on it, and have your backend verify that they match. The model fills parameters, so that check belongs in code, never in the prompt.

#When a person takes over

Supervisors you invite from Team in the inbox see every Instagram conversation in the inbox, with each tool call next to the reply it produced.

• Replying in the inbox is a takeover. It pauses the agent on that conversation. Hand back to agent releases it, or the takeover expires 8 hours after the customer’s last message; every human reply restarts that clock.
• The agent can ask for a person. The handoff block above passes on complaints and custom orders, and a customer who asks for a person always gets one. 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.
• Nobody is notified yet. A handed-off conversation shows as waiting in the inbox, so someone has to watch it.

When a reply was wrong, choose Report this reply on it and write what should have happened. Your coding agent fixes the cause from those notes; see Improve your agent.

#What Vatio does not do on Instagram

The agent only answers DMs people send it. Vatio sends no outbound DMs, broadcasts, campaigns or follow-ups, and Instagram only lets a business reply to someone who wrote first. It works in direct messages, not in the comments under your posts. There are no voice calls, and the agent never generates images or files.

WhatsApp works the same way, with a shared preview number and your own business number; see An AI agent on WhatsApp. Every option on the Channels page is in the Instagram docs.

Updated: October 11, 2026