#Un agente de IA en WhatsApp

Para poner un agente de IA en WhatsApp con Vatio, lo describes en un archivo vatio.yml, haces push y hablas con él desde tu propio teléfono en un número de preview compartido, sin cuenta de Meta. Cuando responde bien, conectas tu número de negocio con el registro de Meta desde el inbox de Vatio y activas En vivo. El agente responde lo que la gente envía, audios, fotos y PDF incluidos, y cualquier persona de tu equipo puede tomar una conversación desde el inbox o desde la app de WhatsApp Business.

Esta guía va de una carpeta vacía a tu propio número, y explica lo que el agente puede y no puede hacer una vez ahí.

#Empieza con un agente mínimo

Necesitas Node.js 20 o superior. vatio init no pide cuenta; el primer vatio push abre tu navegador para iniciar sesión con correo, Google o GitHub, y eso la crea.

npx @vatio-ai/skills
npm install -g @vatio-ai/cli@latest
vatio init bicicletas-cerro-alegre

Reemplaza el vatio.yml inicial por algo así de breve:

workspace: bicicletas-cerro-alegre
agent:
  name: Bicicletas Cerro Alegre
  personality: Cercano y breve. Mensajes cortos, como escribe la gente por WhatsApp.
  instructions: |
    Atiendes a los clientes de Bicicletas Cerro Alegre, una tienda y taller
    de bicicletas en Valparaíso. Abrimos de lunes a viernes de 9:00 a 18:00
    y los sábados de 10:00 a 14:00. Una mantención estándar tarda dos días
    hábiles.

    Si no sabes algo, dilo y ofrece pasarle la pregunta al equipo. Nunca
    inventes un precio, un stock ni una fecha de retiro.
  handoff:
    when:
      - un reclamo por una reparación o un cobro
      - el cliente quiere cotizar una bicicleta armada a medida

vatio push
vatio chat "hola, ¿abren el sábado?"
vatio chat "los cambios que me arreglaron la semana pasada andan peor que antes"
vatio chat show

El segundo mensaje es un reclamo, así que debería derivarse; chat show te dice si lo hizo, con cada llamada a tools. Cuando los datos ya no caben en las instrucciones, los precios y servicios pasan a una base de conocimiento; Construir un agente de IA cubre ese paso.

vatio chat responde apenas la respuesta está lista, así que prueba lo que el agente dice, no cómo lo entrega WhatsApp. Para eso necesitas un teléfono.

#Pruébalo en el número de preview compartido

El número de preview es de Vatio, así que puedes probar en WhatsApp real antes de tocar Meta. Todo se hace en la pestaña WhatsApp de la página Probar del inbox:

1. Abre Probar → WhatsApp. Un teléfono que ya verificaste en otro workspace tuyo aparece en Ya verificaste estos números, y Usar en preview lo conecta con un clic, sin código.
2. Si no, en Conecta tu celular, escanea el código QR con tu teléfono. WhatsApp se abre en el número de preview compartido con un mensaje ya escrito que lleva un código de 6 caracteres: envíalo. Si no tienes una cámara a la mano, envía tú ese código al número de preview; la página muestra los dos. Ese mensaje es lo que demuestra que el teléfono es tuyo. Vatio te responde de inmediato con “Verificamos tu celular ✅”, y la página se actualiza sola.
3. Escríbele al agente desde ese teléfono y lee la conversación en Conversaciones, en el mismo inbox. Debajo de cada respuesta del agente está lo que hizo: las tools que llamó y lo que devolvieron, y el conocimiento que leyó. Es el mismo inbox desde el que tu equipo responde cuando el agente ya está en vivo.

Puedes registrar hasta cinco teléfonos de prueba por workspace, así que el dueño del taller y alguien más del equipo también pueden probarlo: Agregar otro número, debajo de la lista, muestra un código QR nuevo. Un código dura 15 minutos y sirve una vez, y el código QR de la página se renueva solo. Un teléfono verificado enruta a un solo workspace a la vez; enviar desde él el código de otro workspace, o elegir Usar en … en otro workspace, lo mueve a ese.

Cada teléfono de prueba llega a preview, así que pruebas un cambio en WhatsApp antes de publicarlo. Nunca llega a live: live es tu propio número.

Ahora escribe como escriben los clientes: tres mensajes cortos seguidos, un audio, una foto de una rueda doblada. Esa es la prueba que vatio chat no puede hacer.

#Conecta tu propio número de negocio

Cuando el preview está bien, publícalo:

vatio publish

Después, en el inbox, abre Canales → WhatsApp en live, elige Conectar WhatsApp y completa el registro de Meta en la ventana que se abre. Si publicas desde el inbox, con Publicar a live en la página Probar, primero corren tus pruebas; después de la primera publicación, Publicado. Ahora: ponlo en tu app también conecta WhatsApp desde ahí.

Un número recién conectado queda en pausa. Sigue funcionando exactamente como antes hasta que activas En vivo, que es lo que arranca las respuestas de tu deployment live. Eso te da tiempo para revisar la conexión: el mismo modal dice si Meta está entregando los mensajes del número, y Verificar vuelve a correr esa revisión. Desactivar En vivo pausa las respuestas sin desconectar nada. Para cambiar de número, elimina primero la integración y conecta el nuevo.

Si el número es de tu cliente, no necesitas su acceso a Facebook. En ¿El número lo tiene tu cliente?, en el mismo modal, invita por correo a quien lo tenga. Entra como supervisor, conecta el número desde una página propia y te llega un correo cuando queda conectado. Mientras tanto, el modal muestra en qué paso va cada persona que invitaste, desde que abre la invitación hasta el registro de Meta, así sabes si esperar o darle una mano. Activar En vivo sigue siendo cosa tuya.

Desde ahí, vatio publish cambia lo que responde el número, y vatio rollback restaura la versión anterior.

#Sigue usando la app de WhatsApp Business

No tienes que dejar la app en el teléfono del taller. La conexión permite conservarla, y las dos cosas funcionan juntas:

• Responder desde la app es tomar la conversación. La respuesta llega a Vatio y pausa al agente en esa conversación, igual que una respuesta desde el inbox.
• Devuélvela desde el inbox cuando el agente deba retomar, con Devolver al agente en la conversación. O déjala: el traspaso vence 8 horas después del último mensaje del cliente, y cada respuesta humana reinicia ese reloj.
• El agente también puede pedir una persona. El bloque handoff de arriba le permite derivar los reclamos, y un cliente que pide hablar con una persona con esas palabras siempre es derivado. Dentro del horario de atención, que se configura en la página Negocio del inbox (lunes a viernes de 9:00 a 18:00 y sábado de 10:00 a 14:00), el agente se queda en silencio; fuera de él sigue ayudando. Una derivación que nadie toma en una hora vuelve al agente.

Vatio todavía no notifica a nadie de una derivación. La conversación aparece como en espera en el inbox, así que alguien tiene que estar mirándolo.

#Cómo se comporta una conversación de WhatsApp

• Una conversación dura hasta ocho horas de silencio. Vatio continúa la última conversación hasta que el último mensaje del cliente tiene más de ocho horas; el siguiente mensaje empieza un chat nuevo.
• Los fragmentos se vuelven una sola pregunta. Vatio agrupa los mensajes que llegan juntos y espera un momento de silencio antes de responder, y también espera un audio o una foto que todavía se está procesando. Conversaciones fluidas explica por qué eso importa.
• Una edición reescribe el mensaje. Cuando el cliente edita un mensaje dentro de los 15 minutos que permite WhatsApp, o tú editas una respuesta desde la app de WhatsApp Business, el inbox muestra el texto nuevo marcado como editado y el agente lo lee desde ese momento. Una edición no es un mensaje nuevo: el agente no la responde y no toma la conversación.
• Un mensaje eliminado desaparece. Cuando el cliente elimina un mensaje para todos, dentro de los dos días que permite WhatsApp, o tú eliminas uno desde la app, desaparece del inbox y de lo que lee el agente.
• Lee audios, imágenes y PDF. El audio se transcribe, y las imágenes y los PDF compatibles de hasta 8 MB por archivo le llegan al agente. Lo que no es compatible o pesa más queda disponible para los supervisores, y el agente recibe un aviso de que no puede leerlo.
• Las respuestas son texto, al ritmo de alguien que escribe. En WhatsApp una respuesta llega como mensajes cortos de texto plano, con pausas e indicadores de escritura, no como un solo bloque largo. El agente no puede enviar imágenes, archivos ni audios.
• Los links están en una lista permitida. El agente solo envía URL que se le dieron, en links, en sus instrucciones o en el resultado de una tool. Cualquier otra URL se quita de la respuesta.

#Con quién está hablando el agente

Para tu backend, un contacto de WhatsApp empieza siendo anónimo: no hay una página donde pueda firmar un token que diga quién es. Las tools públicas corren para cualquiera. Una tool marcada access: private, la que lee los datos de una persona detrás de un login, necesita que inicie sesión, así que Vatio la envía a tu sitio a hacerlo. Agrega tu página de inicio de sesión a auth:, junto a la llave pública que verifica tus tokens:

auth:
  public_key: identity.pub
  sign_in_url: https://bicicletas-cerro-alegre.example/vatio/sign-in

Cuando corre una tool privada para un contacto que no ha iniciado sesión, Vatio le envía un botón Iniciar sesión. Abre tu página con un code de un solo uso; tu página inicia su sesión como tu sitio ya lo hace y redirige a https://vatio.ai/connect/<code>?token=<jwt>, con el mismo JWT que le pones al widget web. Vatio le pide confirmar el número de WhatsApp, un paso que se salta cuando el claim phone_number del token coincide, y la conversación sigue donde quedó: el agente corre la tool que estaba esperando. El token queda en el contacto hasta su exp. Con la gema vatio-sdk, la página es un solo redirect a Vatio::Identity.sign_in_redirect_url; En WhatsApp e Instagram en la documentación tiene los detalles.

No toda consulta necesita una cuenta. Para clientes que nunca se registraron, lo habitual es una tool pública que pide una referencia más un segundo dato, y tu backend verifica que coincidan. Primero guarda la dirección y la llave de la API como secrets:

vatio secrets set TALLER_API https://api.bicicletas-cerro-alegre.example
vatio secrets set TALLER_API_KEY sk_live_...

tools/estado_reparacion.yml:

description: Consulta el estado de una reparación.
when_to_use: El cliente pregunta si su bicicleta está lista o cómo va una reparación.
parameters:
  type: object
  properties:
    orden: { type: string, description: "Número de orden de trabajo, por ejemplo OT-2041" }
    ultimos4: { type: string, description: "Últimos cuatro dígitos del teléfono de la orden" }
  required: [orden, ultimos4]
access: public
request:
  method: GET
  base_url: "$env.TALLER_API"
  path: /reparaciones/estado
  requires: [params.orden, params.ultimos4]
  headers:
    Authorization: "Bearer $env.TALLER_API_KEY"
  query:
    orden: "$params.orden"
    ultimos4: "$params.ultimos4"
respond:
  data:
    reparacion: "$.reparacion"

Los parámetros de una tool los llena el modelo, así que la verificación de que la orden corresponde a esos dígitos vive en tu backend, que responde 404 cuando no coinciden. Nunca la dejes en el prompt.

A veces una tool necesita el teléfono del propio cliente, por ejemplo para agendar una llamada. En WhatsApp el agente ya lo tiene: pedir_llamada es un POST cuyo body lleva $contact.phone_number, con contact.phone_number en requires y sin un parámetro de teléfono que llene el modelo. Si un cliente oculta su número detrás de un nombre de usuario de WhatsApp, Vatio le envía un botón para compartirlo con un toque la primera vez que corre la tool; el número llega con su siguiente mensaje, y la tool puede correr entonces. No hay nada que activar ni nada que el agente tenga que preguntar. El número dice cómo contactar al cliente, no quién es, así que estado_reparacion mantiene su segundo dato:

agent:
  instructions: |
    ...
    Estado de una reparación: pide el número de orden y los últimos cuatro
    dígitos del teléfono de la orden, y llama a estado_reparacion.
    Llamadas: llama a pedir_llamada. La tool ya tiene su número.
  tools: [estado_reparacion, pedir_llamada]

Conectar tu backend profundiza en las tools y en los visitantes autenticados.

#Lo que Vatio no hace en WhatsApp

El agente nunca decide por su cuenta escribir primero. Cuando tu negocio lo necesita, ya sea un recordatorio, un aviso de pedido o cada persona de una lista de campaña, tu backend lo pide con la Messages API, una solicitud por contacto y hasta 60 por minuto por clave: dentro de las 24 horas desde el último mensaje de la persona envía tu texto o hace que el agente lo escriba a partir de un brief, y después de eso WhatsApp solo entrega una plantilla que Meta aprobó, que el inbox muestra en Mensajes salientes → Plantillas. El agente atiende las respuestas sabiendo de qué trataba el mensaje, y se respeta a quien pidió no recibir mensajes y las conversaciones que tomó una persona. Lo que Vatio no tiene es un panel de campañas para subir listas, segmentarlas o programar envíos: esa lógica vive en tu backend. Tampoco hay llamadas de voz, y el agente nunca genera imágenes ni archivos.

#Instagram es el mismo agente

Los DM de Instagram funcionan igual: una cuenta de preview compartida con hasta cinco cuentas de prueba, y después tu propia cuenta profesional conectada desde Canales en el inbox. Es el mismo agente, con el mismo inbox y el mismo inicio de sesión, salvo que la confirmación muestra el @usuario en lugar de un número, y siempre aparece. Mira la documentación de Instagram, y la de WhatsApp para cada opción de la página Canales.

Actualizado: 11 de octubre de 2026