Zavu 2.0: un dashboard ordenado por lo que haces, y la API v2

TL;DR

• El dashboard se ordena por lo que haces: siete filas, con tus canales y números en una sola área, Canales.
• Las cuentas creadas desde el 19 de octubre de 2026 entran a la 2.0. Las anteriores pueden cambiar desde la barra superior y volver cuando quieran.
• La API v2 envía desde una dirección. Pasas from o respondes con conversationId, y cada 202 dice cómo se enrutó.
• La API v1 sigue funcionando, con la misma key, los mismos datos y sin fecha límite para migrar.
• Los SDKs todavía llaman a la v1, así que por ahora la v2 se llama por HTTP.

Hoy lanzamos Zavu 2.0: un dashboard nuevo y una segunda versión de nuestra API de mensajería multicanal. El motor de abajo es el mismo que ya usas. Lo que cambia es cómo te mueves por él y cómo le habla tu código.

En este post: qué cambió en el dashboard, quién lo recibe, en qué se diferencia la API v2 de la v1 con un request lado a lado, y por dónde empezar si esta semana vas a construir algo.

Qué cambió en el dashboard

No partimos de un diseño. Partimos de cómo se usaba el anterior. Entre julio y septiembre, las filas más abiertas del menú lateral fueron Inicio, Inbox, Accounts, Phone Numbers y Senders. Y Accounts, Senders y Phone Numbers se abrían una detrás de otra, en loop, por gente que buscaba lo mismo: dónde está mi canal y por qué no puede enviar.

Por eso la 2.0 se ordena por lo que haces y no por cómo está construida la API. Siete filas:

• Inicio, Conversaciones y Contactos: el trabajo del día.
• Bajo Construir: Campañas, Agentes, Canales y Desarrolladores.

Cada pantalla que existía sigue estando, dentro del área a la que pertenece. No se borró nada para que el menú quedara más corto.

Los canales, en un solo lugar

Accounts, Senders y Phone Numbers ahora son una sola área: Canales. Se agrupa bajo tres títulos:

• Conectar: conectar WhatsApp, ver tus canales conectados, enviar invitaciones a clientes y gestionar números de teléfono. WhatsApp tiene su propia pantalla de conexión, que lista los requisitos antes de que se abra el registro de Meta.
• Probar: el Playground y el Sandbox, justo debajo de los números desde los que sale un mensaje. Cuando un canal queda activo, ahí lo pruebas.
• Cumplimiento: límites y verificación en una sola pantalla, para ver tus topes diarios antes de que un envío choque con ellos y no después.

Los senders dejaron de ser una pantalla. Conectar un canal crea lo que hace falta. El ID que todavía usa la API v1 vive en Desarrolladores → Sender IDs, marcado como API v1.

Inicio parte de tu objetivo

Lo primero que pregunta Inicio es qué quieres lograr: hablar con tus clientes, notificar desde tu app, enviar una campaña o, si eres agencia, conectar los canales de tus clientes. Cada objetivo dice qué recomienda y por qué. Para hablar con clientes, por ejemplo, avisa que Telegram se conecta en minutos y que WhatsApp necesita una cuenta de Meta Business.

Después Inicio muestra los pasos que faltan para ese objetivo y marca cada uno cuando de verdad ocurre: un canal conectado, una respuesta enviada desde Conversaciones, un agente respondiendo. Tu API key y un primer request están ahí, listos para copiar.

Asistente Zavu

En la interfaz anterior el asistente tenía tres nombres. En la 2.0 tiene uno, Asistente Zavu, en la barra superior y en Inicio. Recibe el objetivo que elegiste, así que una pregunta parte desde donde estás y no desde cero. También puedes escribirle tu objetivo directamente desde Inicio.

Las demás pantallas dicen qué falta

Buena parte de la 2.0 son pantallas que se explican solas:

• Conversaciones muestra en el propio mensaje por qué falló, y te deja elegir el canal por el que respondes.
• Campañas dice qué necesita cada canal antes de que lo elijas, muestra el costo estimado y tu saldo antes de enviar, y te deja mandarte una prueba. La prueba es un mensaje real y se cobra como cualquier otro.
• Agentes te dice por qué un agente no respondió y cómo arreglarlo.
• Desarrolladores reúne API keys, Sender IDs, webhooks, logs e integraciones. Los ejemplos de código usan la API v2, y cada uno se puede cambiar a v1.

Quién recibe Zavu 2.0

• Las cuentas creadas desde el 19 de octubre de 2026 entran a la 2.0.
• Las cuentas anteriores siguen con la interfaz anterior y ven una invitación. Puedes cambiar desde la barra superior y volver por el mismo lugar.
• La elección es tuya, no del workspace: el resto de tu equipo sigue en la suya.

Las dos versiones muestran la misma cuenta. Tus datos, tu facturación y tu integración con la API v1 son los mismos uses la que uses.

La API v2

La API v2 corre sobre el mismo motor que la v1: las mismas API keys, los mismos límites de envío, precios y revisiones. Lo que cambia es la forma.

• Sin objeto sender. Envías desde una dirección, escrita como la ve quien recibe: un número de teléfono, un email, el @nombre de un bot.
• Sin header Zavu-Sender. Pasas from, o respondes dentro de un hilo con conversationId.
• Cada envío dice cómo se enrutó. El 202 trae routing: el canal, la dirección desde la que salió, el motivo y estimatedCost.
• Un solo webhook por proyecto. PUT /v2/webhook recibe todos los eventos de todas tus direcciones. El secret se devuelve una sola vez, en el 201 que lo crea.
• Una sola forma de error. {code, message, details} en la raíz de cada error.
• Una sola respuesta para "no hay con qué enviar". 409 no_channel, con details.connect listando qué puedes conectar para llegar a ese destinatario y el request exacto de cada opción.

Antes y después

El mismo SMS, en la v1 y en la v2:

terminal
# v1: la identidad de envío es un sender id, en un header
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Zavu-Sender: kd7abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"to": "+525598765432", "channel": "sms", "text": "Tu código es 123456."}'

terminal
# v2: la identidad de envío es una dirección, en el body
curl -X POST https://api.zavu.dev/v2/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "+525512345678", "to": "+525598765432", "channel": "sms", "text": "Tu código es 123456."}'

La respuesta de la v2, resumida, nombra direcciones, nunca un sender id, y te dice qué pasó:

JSON
{
  "message": {
    "id": "jd7x2k3m4n5p6q7r8s9t0",
    "to": "+525598765432",
    "from": "+525512345678",
    "channel": "sms",
    "status": "queued"
  },
  "routing": {
    "channel": "sms",
    "from": "+525512345678",
    "reason": "explicit",
    "estimatedCost": 0.0213
  }
}

reason es la primera regla que aplicó: explicit cuando nombraste channel, recipient_type cuando to es un email, message_type cuando el tipo de mensaje solo existe en WhatsApp, conversation en una respuesta, sandbox con una key de prueba, y auto_order en el resto: el primer transporte activo, que para un número es WhatsApp, después SMS y después SMS de una vía. Ese orden no compara precios. estimatedCost es lo que un SMS descontó de tu saldo al aceptarse, y null donde el precio no se conoce al enviar. El monto de arriba es ilustrativo.

Conectar un canal desde código

POST /v2/channels conecta lo que no requiere compra ni registro en Meta: un email en un dominio verificado, un bot de Telegram a partir de su token, o SMS de una vía. El SMS bidireccional y la voz vienen con un número propio (POST /v2/numbers lo compra y activa el SMS en una sola llamada). WhatsApp, Instagram y Messenger se conectan a través de Meta, desde Canales en el dashboard.

Si envías antes de que algo pueda llegar al destinatario, no recibes un 400 vago. Recibes esto (resumido):

JSON
{
  "code": "no_channel",
  "message": "This project has no channel that can send to +525598765432 yet.",
  "details": {
    "connect": [
      { "type": "sms", "request": { "method": "POST", "path": "/v2/numbers" }, "available": true },
      { "type": "whatsapp", "request": null, "available": true }
    ]
  }
}

request: null significa que ese canal se conecta desde el dashboard. Las formas completas están en la introducción a la API v2, en direcciones y canales y en errores.

La v1 sigue funcionando

La API v1 está congelada, no retirada. Sus endpoints, payloads y webhooks siguen funcionando exactamente como hoy, y no hay fecha límite para migrar.

Puedes migrar una llamada a la vez. Las dos versiones usan la misma API key y comparten los mismos datos: un mensaje, una conversación, un contacto, una campaña o un agente creado con una se lee con la otra con el mismo ID. Cada entrada de GET /v2/channels trae v1SenderId, el valor que sigues mandando como Zavu-Sender en las llamadas que todavía no moviste.

Los webhooks se mueven igual. Después de crear el webhook de la v2, los webhooks por sender de la v1 siguen recibiendo eventos, así que cada evento llega a los dos. Cuando tu receptor ya maneja el payload de la v2, un PUT /v2/webhook con "disableSenderWebhooks": true apaga los de la v1 y conserva su configuración. Detalles en Webhook.

Algunas áreas todavía no tienen endpoint en la v2 y siguen en la v1 con la misma key: el código y los despliegues de funciones, las llamadas de voz, el registro 10DLC, los documentos regulatorios, las tools y bases de conocimiento de los agentes, la memoria, y endpoints de cuenta como saldo y subcuentas. La lista completa, y todo lo que responde distinto en la v2, está en Migrar desde la v1.

Los SDKs siguen llamando a la v1

@zavudev/sdk en npm, zavudev en PyPI y los demás SDKs llaman hoy a la v1. La v2 se llama por HTTP: curl, fetch, requests, el cliente que uses. Los ejemplos de código del dashboard muestran la v2 por defecto, y la pestaña del SDK avisa que llama a la v1.

Por dónde empezar

Cinco tutoriales, todos construidos sobre la API v2 desde el primer request:

• Recordatorios de citas por WhatsApp: recordatorios que una clínica envía con una plantilla aprobada, y confirmaciones que vuelven como respuesta.
• Códigos de verificación OTP por API: generar un código, enviarlo por el canal que llega a la persona y verificarlo de tu lado.
• Chatbot con IA para tu tienda online: un agente que responde a tus clientes en el canal que conectes, con Conversaciones para cuando una persona tiene que entrar.
• Notificaciones de pedidos para e-commerce: confirmaciones y avisos de envío que salen de tu backend cuando un pedido cambia de estado.
• Leads de inmobiliaria por WhatsApp: captar un lead, responderle dentro de la hora y tener todas las conversaciones en un solo lugar.

Si recién llegas a Zavu, primeros pasos con la API de Zavu cubre lo básico, y la guía de la API de WhatsApp para desarrolladores explica qué pide Meta. Si ya tienes una integración con la v1, hoy no se rompe nada. Migra cuando te sirva, una llamada a la vez.