Pular para o conteúdo

Migrar

Migrar da Z-API

Como trocar a Z-API pelo Messajo e manter o número.

Esta página mostra o que muda ao sair da Z-API e como cada operação dela vira uma chamada do Messajo. As tabelas gerais de qualquer provedor (Cloud API, 360dialog, Twilio e APIs não oficiais) estão em Migrar de outro provedor; aqui ficam só os pontos da Z-API.

A Z-API pareia um telefone, como o WhatsApp Web. O Messajo usa a API oficial da Meta. Na prática:

Na Z-API No Messajo
Ler o QR code Cadastro oficial da Meta (Embedded Signup), pelo painel
Instância Conexão (conn_…)
Mensagem livre a qualquer hora Mensagem livre só dentro de 24 h do último contato da pessoa; fora disso, um template aprovado
Contato que nunca falou com você Exige opt-in: a pessoa precisa ter aceitado receber mensagens
Sem cobrança por mensagem da Meta A Meta cobra por mensagem de template, direto de você. Veja Custos da Meta
Número pareado Número oficial, com qualidade e limites medidos pela Meta

Para não perder o atendimento no celular, conecte em coexistência: o app do WhatsApp Business continua funcionando e o Messajo importa os contatos e até 6 meses de histórico, uma única vez, na hora de conectar.

  • Exige o app WhatsApp Business 2.24.17 ou mais novo, com confirmação por QR code no app.
  • A vazão fica fixa em 20 mensagens por segundo.
  • Grupos não sincronizam na coexistência. Se você depende de grupos, veja Grupos: eles pedem o modo só API.
  • Para volume maior ou para um número novo, use o modo só API.

O passo a passo está em Conectar o WhatsApp; se algo travar, veja Problemas na coexistência.

A Z-API identifica a instância pelo ID e pelo token dela, que aparecem no painel da Z-API. No Messajo, toda chamada leva Authorization: Bearer <chave>:

  • chave de organização (mj_…): enviada com connection_id no corpo;
  • chave de conexão (mjc_…): vale só para uma conexão e dispensa o connection_id. É a mais próxima de “um token por instância”.

Veja Tipos de chave.

Os caminhos da Z-API não estão aqui: confira-os na documentação da Z-API. A coluna da esquerda nomeia a operação.

Operação na Z-API No Messajo
Enviar texto POST /v1/messages com type: "text". Veja Enviar texto
Enviar imagem type: "image". Veja Enviar imagem
Enviar vídeo type: "video". Veja Enviar vídeo
Enviar áudio type: "audio". Veja Enviar áudio
Enviar documento type: "document". Veja Enviar documento
Enviar sticker type: "sticker". Veja Enviar figurinha
Enviar localização type: "location". Veja Enviar e pedir localização
Enviar contato type: "contacts". Veja Enviar contato
Enviar botões type: "interactive", botões de resposta. Veja Enviar botões
Enviar lista de opções type: "interactive", lista. Veja Enviar lista
Reagir a uma mensagem type: "reaction". Veja Enviar reação
Responder citando uma mensagem reply_to no corpo do envio
Marcar como lida POST /v1/messages/{id}/read. Veja Marcar como lida
Enviar arquivo por URL link (URL pública) ou media_id, obtido com POST /v1/media (multipart)

O texto da Z-API usa os campos phone e message (Enviar texto simples). No Messajo eles viram to e text.body.

O Messajo aceita o telefone com DDI, só dígitos (por exemplo 5511999999999), ou um contato ctc_…. Sufixos como @c.us não existem; qualquer caractere que não seja dígito é descartado.

Na Z-API No Messajo
Retorno de mensagem recebida Evento message.received
Retorno de status da mensagem (enviada, entregue, lida) Evento message.status
Retorno de estado da instância Eventos connection.*
Retorno do QR code Sem equivalente: a conexão é feita pelo painel

Você cadastra um destino de eventos e o Messajo assina cada entrega com Messajo-Signature (HMAC-SHA256). Verifique a assinatura no seu servidor, como em Verificar a assinatura. Na coexistência, as mensagens enviadas pelo app do celular chegam como message.echo.

  • Enviar a qualquer pessoa, a qualquer hora. No Messajo vale a janela de 24 h e, fora dela, só template aprovado. Veja Limites.
  • Grupos. Na coexistência não sincronizam; para usar grupos, o modo é só API. Veja Grupos.
  • Conexão criada (coexistência ou só API) e Ativa no painel.
  • Templates criados e aprovados para as mensagens que você manda fora da janela.
  • Destinos de eventos criados, com a assinatura verificada no seu servidor.
  • Uma chave de API por integração, com só as permissões e conexões necessárias.
  • Teste de ponta a ponta com um número seu: enviar, receber, status e template.
  • Integração trocada de Authorization e de formato de corpo, e o destinatário sem sufixos.
  • Instância da Z-API desligada só depois de a conexão oficial estar ativa e testada, e o aparelho pareado por QR code desconectado dela.