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.
O que muda no modelo
Seção intitulada “O que muda no modelo”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 |
Manter o número
Seção intitulada “Manter o número”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.
Autenticação
Seção intitulada “Autenticação”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 comconnection_idno corpo; - chave de conexão (
mjc_…): vale só para uma conexão e dispensa oconnection_id. É a mais próxima de “um token por instância”.
Veja Tipos de chave.
Operações lado a lado
Seção intitulada “Operações lado a lado”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.
Formato do destinatário
Seção intitulada “Formato do destinatário”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.
Webhooks
Seção intitulada “Webhooks”| 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.
O que não tem equivalente ou funciona diferente
Seção intitulada “O que não tem equivalente ou funciona diferente”- 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.
Checklist de virada
Seção intitulada “Checklist de virada”- 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
Authorizatione 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.