Zavu 2.0: um dashboard organizado pelo que você faz, e a API v2

TL;DR

• O dashboard se organiza pelo que você faz: sete linhas, com seus canais e números numa única área, Canais.
• Contas criadas a partir de 19 de outubro de 2026 entram na 2.0. As anteriores podem trocar pela barra superior e voltar quando quiserem.
• A API v2 envia a partir de um endereço. Você passa from ou responde com conversationId, e cada 202 diz como foi roteado.
• A API v1 continua funcionando, com a mesma key, os mesmos dados e sem prazo para migrar.
• Os SDKs ainda chamam a v1, então por enquanto a v2 é chamada por HTTP.

Hoje lançamos o Zavu 2.0: um dashboard novo e uma segunda versão da nossa API de mensagens multicanal. O motor por baixo é o mesmo que você já usa. O que muda é como você se orienta nele e como o seu código conversa com ele.

Neste post: o que mudou no dashboard, quem recebe, como a API v2 se diferencia da v1 com um request lado a lado, e por onde começar se você vai construir algo esta semana.

O que mudou no dashboard

Não partimos de um design. Partimos de como o anterior era usado. Entre julho e setembro, as linhas mais abertas do menu lateral foram Início, Inbox, Accounts, Phone Numbers e Senders. E Accounts, Senders e Phone Numbers eram abertas uma atrás da outra, em loop, por quem procurava a mesma coisa: onde está o meu canal e por que ele não consegue enviar.

Por isso a 2.0 se organiza pelo que você faz, e não por como a API é construída. Sete linhas:

• Início, Conversas e Contatos: o trabalho do dia.
• Em Criar: Campanhas, Agentes, Canais e Desenvolvedores.

Toda tela que existia continua lá, dentro da área a que pertence. Nada foi apagado para o menu ficar mais curto.

Os canais num só lugar

Accounts, Senders e Phone Numbers agora são uma área só: Canais. Ela é agrupada em três títulos:

• Conectar: conectar o WhatsApp, ver seus canais conectados, enviar convites para clientes e gerenciar números de telefone. O WhatsApp tem a própria tela de conexão, que lista os requisitos antes de o cadastro da Meta abrir.
• Testar: o Playground e o Sandbox, logo abaixo dos números de onde uma mensagem sai. Quando um canal fica ativo, é ali que você testa.
• Conformidade: limites e verificação numa só tela, para ver seus tetos diários antes de um envio esbarrar neles, e não depois.

Os senders deixaram de ser uma tela. Conectar um canal cria o que for preciso. O ID que a API v1 ainda usa fica em Desenvolvedores → Sender IDs, marcado como API v1.

O Início começa pelo seu objetivo

A primeira coisa que o Início pergunta é o que você quer fazer: falar com seus clientes, notificar a partir do seu app, enviar uma campanha ou, se você é agência, conectar os canais dos seus clientes. Cada objetivo diz o que recomenda e por quê. Para falar com clientes, por exemplo, ele avisa que o Telegram se conecta em minutos e que o WhatsApp precisa de uma conta Meta Business.

Depois o Início mostra os passos que faltam para esse objetivo e marca cada um quando ele acontece de verdade: um canal conectado, uma resposta enviada por Conversas, um agente respondendo. Sua API key e um primeiro request ficam ali, prontos para copiar.

Assistente Zavu

Na interface anterior o assistente tinha três nomes. Na 2.0 tem um, Assistente Zavu, na barra superior e no Início. Ele recebe o objetivo que você escolheu, então uma pergunta começa de onde você está, e não do zero. Você também pode escrever seu objetivo para ele direto do Início.

As outras telas dizem o que falta

Boa parte da 2.0 são telas que se explicam:

• Conversas mostra na própria mensagem por que ela falhou e deixa você escolher o canal da resposta.
• Campanhas diz o que cada canal precisa antes de você escolher, mostra o custo estimado e seu saldo antes do envio, e deixa você mandar um teste para si mesmo. O teste é uma mensagem real e é cobrado como qualquer outra.
• Agentes diz por que um agente não respondeu e como resolver.
• Desenvolvedores reúne API keys, Sender IDs, webhooks, logs e integrações. Os exemplos de código usam a API v2, e cada um pode ser trocado para a v1.

Quem recebe o Zavu 2.0

• Contas criadas a partir de 19 de outubro de 2026 entram na 2.0.
• Contas anteriores continuam na interface anterior e veem um convite. Você troca pela barra superior e volta pelo mesmo lugar.
• A escolha é sua, não do workspace: o resto da equipe continua na dela.

As duas versões mostram a mesma conta. Seus dados, seu faturamento e sua integração com a API v1 são os mesmos, seja qual for a versão.

A API v2

A API v2 roda no mesmo motor da v1: as mesmas API keys, os mesmos limites de envio, preços e revisões. O que muda é o formato.

• Sem objeto sender. Você envia a partir de um endereço, escrito como o destinatário o vê: um número de telefone, um e-mail, o @nome de um bot.
• Sem header Zavu-Sender. Você passa from, ou responde dentro de uma conversa com conversationId.
• Cada envio diz como foi roteado. O 202 traz routing: o canal, o endereço de onde saiu, o motivo e estimatedCost.
• Um webhook por projeto. PUT /v2/webhook recebe todos os eventos de todos os seus endereços. O secret é devolvido uma única vez, no 201 que o cria.
• Um único formato de erro. {code, message, details} na raiz de todo erro.
• Uma única resposta para "não há como enviar". 409 no_channel, com details.connect listando o que você pode conectar para alcançar aquele destinatário e o request exato de cada opção.

Antes e depois

O mesmo SMS, na v1 e na v2:

terminal
# v1: a identidade de envio é um sender id, num 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": "+5511987654321", "channel": "sms", "text": "Seu código é 123456."}'

terminal
# v2: a identidade de envio é um endereço, no body
curl -X POST https://api.zavu.dev/v2/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "+5511912345678", "to": "+5511987654321", "channel": "sms", "text": "Seu código é 123456."}'

A resposta da v2, resumida, nomeia endereços, nunca um sender id, e diz o que aconteceu:

JSON
{
  "message": {
    "id": "jd7x2k3m4n5p6q7r8s9t0",
    "to": "+5511987654321",
    "from": "+5511912345678",
    "channel": "sms",
    "status": "queued"
  },
  "routing": {
    "channel": "sms",
    "from": "+5511912345678",
    "reason": "explicit",
    "estimatedCost": 0.0391
  }
}

reason é a primeira regra que se aplicou: explicit quando você informou channel, recipient_type quando to é um e-mail, message_type quando o tipo de mensagem só existe no WhatsApp, conversation numa resposta, sandbox com uma key de teste, e auto_order no resto: o primeiro transporte ativo, que para um número é WhatsApp, depois SMS e depois SMS unidirecional. Essa ordem não compara preços. estimatedCost é o que um SMS descontou do seu saldo ao ser aceito, e null onde o preço não é conhecido no envio. O valor acima é ilustrativo.

Conectar um canal pelo código

POST /v2/channels conecta o que não exige compra nem cadastro na Meta: um e-mail num domínio verificado, um bot do Telegram a partir do token, ou SMS unidirecional. SMS bidirecional e voz vêm com um número próprio (POST /v2/numbers compra o número e ativa o SMS numa só chamada). WhatsApp, Instagram e Messenger se conectam pela Meta, em Canais no dashboard.

Se você envia antes de existir algo que alcance o destinatário, não recebe um 400 vago. Recebe isto (resumido):

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

request: null significa que aquele canal se conecta pelo dashboard. Os formatos completos estão na visão geral da API v2, em endereços e canais e em erros.

A v1 continua funcionando

A API v1 está congelada, não aposentada. Endpoints, payloads e webhooks continuam funcionando exatamente como hoje, e não há prazo para migrar.

Você pode migrar uma chamada de cada vez. As duas versões usam a mesma API key e compartilham os mesmos dados: uma mensagem, conversa, contato, campanha ou agente criado por uma é lido pela outra com o mesmo ID. Cada entrada de GET /v2/channels traz v1SenderId, o valor que você continua mandando como Zavu-Sender nas chamadas que ainda não migrou.

Os webhooks migram do mesmo jeito. Depois que você cria o webhook da v2, os webhooks por sender da v1 continuam recebendo eventos, então cada evento chega aos dois. Quando o seu receptor já trata o payload da v2, um PUT /v2/webhook com "disableSenderWebhooks": true desliga os da v1 e mantém a configuração deles. Detalhes em Webhook.

Algumas áreas ainda não têm endpoint na v2 e continuam na v1 com a mesma key: código e deploys de funções, chamadas de voz, registro 10DLC, documentos regulatórios, tools e bases de conhecimento dos agentes, memória, e endpoints de conta como saldo e subcontas. A lista completa, e tudo o que responde diferente na v2, está em Migrar da v1.

Os SDKs continuam chamando a v1

@zavudev/sdk no npm, zavudev no PyPI e os outros SDKs chamam a v1 hoje. A v2 é chamada por HTTP: curl, fetch, requests, o cliente que você usar. Os exemplos de código do dashboard mostram a v2 por padrão, e a aba do SDK avisa que ela chama a v1.

Por onde começar

Cinco tutoriais, todos construídos sobre a API v2 desde o primeiro request:

• Lembretes de consulta pelo WhatsApp: lembretes que um consultório envia com um modelo aprovado, e confirmações que voltam como resposta.
• Códigos de verificação OTP por API: gerar um código, enviá-lo pelo canal que alcança a pessoa e verificá-lo do seu lado.
• Chatbot com IA para loja virtual: um agente que responde seus clientes no canal que você conectar, com Conversas para quando uma pessoa precisa entrar.
• Notificações de pedidos para e-commerce: confirmações e avisos de envio que saem do seu backend quando um pedido muda de status.
• Leads de imobiliária pelo WhatsApp: captar um lead, responder em menos de uma hora e manter todas as conversas num só lugar.

Se você está chegando agora ao Zavu, primeiros passos com a API do Zavu cobre o básico, e o guia de APIs de mensagens compara os canais. Se você já tem uma integração com a v1, nada quebra hoje. Migre quando fizer sentido, uma chamada de cada vez.