Migrar
Migrar da Evolution API
Como trocar a Evolution API pelo Messajo e manter o número.
Esta página mostra o que muda ao sair da Evolution API e como cada rota dela vira uma chamada do Messajo. As tabelas gerais de qualquer provedor estão em Migrar de outro provedor; aqui ficam só os pontos da Evolution API.
O que muda no modelo
Seção intitulada “O que muda no modelo”A Evolution API pareia um telefone, como o WhatsApp Web. O Messajo usa a API oficial da Meta. Na prática:
| Na Evolution 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 Evolution API autentica com o cabeçalho apikey (global ou da instância) e identifica a instância pelo nome no caminho. 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 “uma chave por instância”.
Veja Tipos de chave.
Rotas lado a lado
Seção intitulada “Rotas lado a lado”Os caminhos da Evolution API vêm da documentação da Evolution Foundation; todos recebem o nome da instância no final.
| Rota na Evolution API | No Messajo |
|---|---|
POST /message/sendText/{instanceName} |
POST /v1/messages com type: "text". Veja Enviar texto |
POST /message/sendMedia/{instanceName} (imagem, vídeo, documento e áudio) |
type: "image", "video", "document" ou "audio". Veja Enviar imagem, vídeo, documento e áudio |
| Enviar sticker (sem rota na documentação consultada) | type: "sticker". Veja Enviar figurinha |
POST /message/sendLocation/{instanceName} |
type: "location". Veja Enviar e pedir localização |
POST /message/sendContact/{instanceName} |
type: "contacts". Veja Enviar contato |
POST /message/sendButtons/{instanceName} |
type: "interactive", botões de resposta. Veja Enviar botões |
POST /message/sendList/{instanceName} |
type: "interactive", lista. Veja Enviar lista |
POST /message/sendReaction/{instanceName} |
type: "reaction". Veja Enviar reação |
Opção de citar uma mensagem (quoted) |
reply_to no corpo do envio |
POST /chat/markMessageAsRead/{instanceName} |
POST /v1/messages/{id}/read. Veja Marcar como lida |
| Mídia por URL | link (URL pública) ou media_id, obtido com POST /v1/media (multipart) |
Exemplo: enviar um texto
Seção intitulada “Exemplo: enviar um texto”O corpo do texto varia entre versões da Evolution API (text direto ou dentro de textMessage); confira o da sua instalação.
curl https://SEU-SERVIDOR/message/sendText/minha-instancia \ -H "apikey: $EVOLUTION_APIKEY" \ -H "Content-Type: application/json" \ -d '{ "number": "5511999999999", "text": "Olá! Seu pedido saiu para entrega." }'curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "text", "text": { "body": "Olá! Seu pedido saiu para entrega." } }'import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "text", text: { body: "Olá! Seu pedido saiu para entrega." },});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 @s.whatsapp.net não existem; qualquer caractere que não seja dígito é descartado.
Webhooks
Seção intitulada “Webhooks”| Na Evolution API | No Messajo |
|---|---|
| Evento de mensagem recebida | Evento message.received |
| Evento de atualização de status da mensagem | Evento message.status |
| Evento de estado da conexão da instância | Eventos connection.* |
| Evento de 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
apikeyparaAuthorizatione de formato de corpo, e o destinatário sem sufixos. - Instância da Evolution API desligada só depois de a conexão oficial estar ativa e testada, e o aparelho pareado por QR code desconectado dela.