Migrar
Migrar de outro provedor
O que muda ao trazer sua integração de outro provedor para o Messajo.
Quanto muda
Seção intitulada “Quanto muda”O esforço depende de onde você vem. Quem já usa a API oficial troca pouco; quem vem de uma API não oficial troca o modelo.
| Você vem de | Envio | Webhooks | Esforço |
|---|---|---|---|
| Cloud API direto | Mesmo corpo na camada espelho; troca a URL base e o token | Formato meta: o mesmo value que você já trata |
Pequeno |
| 360dialog | Mesmo corpo na camada espelho; troca a URL, o D360-API-KEY e põe o phone_number_id no caminho |
Formato meta |
Pequeno |
| Twilio | Reescrever: camada simples ou espelho | Status viram message.status |
Médio |
| Evolution, WAHA, Z-API, uazapi | Reescrever e adotar as regras da Meta (janela, templates, opt-in) | Formato normalized ou meta |
Grande |
As duas camadas da API (espelho da Meta e simples) usam a mesma chave. Veja Conceitos.
Vindo da Cloud API ou da 360dialog
Seção intitulada “Vindo da Cloud API ou da 360dialog”A camada espelho recebe o mesmo corpo da Meta, campo por campo. O código que monta a mensagem fica igual; mudam a URL e a autenticação.
| Antes | No Messajo | |
|---|---|---|
| Cloud API | POST https://graph.facebook.com/<versão>/{phone_number_id}/messages |
POST https://api.messajo.com/v1/whatsapp/{phone_number_id}/messages |
| 360dialog | POST https://waba-v2.360dialog.io/messages |
POST https://api.messajo.com/v1/whatsapp/{phone_number_id}/messages |
| Autenticação | Authorization: Bearer <token da Meta> ou D360-API-KEY: <chave> |
Authorization: Bearer mj_... |
curl -X POST "https://api.messajo.com/v1/whatsapp/$PHONE_NUMBER_ID/messages" \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "messaging_product": "whatsapp", "to": "5511999999999", "type": "text", "text": { "body": "Olá do Messajo" } }'- Na 360dialog a chave já diz qual é o número. No Messajo a chave vale para a organização, então o
phone_number_idvai no caminho. Ele aparece na página da conexão. - O cabeçalho
D360-API-KEYsai; entraAuthorization: Bearercom uma chave de API com permissãosend. - O token da Meta não fica mais no seu código: o Messajo guarda o token da conexão, cifrado.
- A resposta e os erros da Meta voltam como vieram, com o mesmo corpo
{ "error": { "code", … } }que o seu código já trata. Só os erros do próprio Messajo (chave, permissão, limite) usam o formato único. - Nos webhooks, escolha o formato
metano destino para receber o mesmovalueque a Meta manda, dentro do envelope do Messajo. Veja Eventos.
O que o espelho aceita
Seção intitulada “O que o espelho aceita”O caminho é /v1/whatsapp/{id}/<resto do caminho da Meta>, com o método, a query e o corpo da Meta. A versão da Graph API é a do servidor.
{id} |
Vai para | Exemplo |
|---|---|---|
phone_number_id de uma conexão sua |
o número | POST /v1/whatsapp/{phone_number_id}/messages, GET …/whatsapp_business_profile, POST …/media |
waba_id (conta de mensagens) de uma conexão sua |
a conta | GET /v1/whatsapp/{waba_id}/message_templates |
phone_number_id + nodes/{node_id} |
um nó avulso da Meta | GET /v1/whatsapp/{phone_number_id}/nodes/{media_id}, DELETE …/nodes/{template_id} |
O waba_id aparece na página da conexão, em Conta de mensagens (WABA). Nós avulsos (mídia, template por id) passam pelo número, para o Messajo saber de qual conexão é o pedido.
- Permissão da chave:
POST …/messagespedesend;message_templatese nós de template pedemtemplates; outrosGET,read; outras alterações,admin. Chave presa a algumas conexões só alcança essas. - Bloqueados com
403mirror_path_blocked, porque derrubam a conexão:register,deregister,request_code,verify_code,smb_app_data,DELETE …/subscribed_appsePOST …/subscribed_appscomoverride_callback_uri. - Envio:
POST …/messagespassa pelo mesmo limite por número da camada simples (Envio por número), grava a mensagem nos logs, emitemessage.sente devolve o id do Messajo no cabeçalhoX-Messajo-Message-Id. O Messajo não repete o envio quando a Meta falha. - Resposta: status, corpo e
content-typeda Meta, maisX-Request-Id. OAuthorizationque você manda nunca segue para a Meta.
Vindo do Twilio
Seção intitulada “Vindo do Twilio”O Twilio tem formato próprio (From, To e Body com o prefixo whatsapp:, em formulário), então a chamada de envio é reescrita:
- camada simples (
POST /v1/messages), para texto, mídia, template e botões com o mesmo formato nos 3 canais; - camada espelho, para usar qualquer recurso da Meta com o corpo dela.
Os status do Twilio (queued, sent, delivered, read, failed) chegam como o evento message.status, e as mensagens recebidas como message.received. Troque o StatusCallback e o webhook de entrada por um destino de eventos e passe a verificar a assinatura do Messajo no lugar da X-Twilio-Signature. Os templates aprovados ficam na sua conta da Meta: sincronize ou recrie no Messajo.
Vindo de API não oficial
Seção intitulada “Vindo de API não oficial”Evolution, WAHA, Z-API e uazapi simulam um celular. O Messajo usa a API oficial da Meta, e isso muda o modelo:
| Na API não oficial | No Messajo |
|---|---|
| Ler o QR code | Cadastro oficial da Meta (Embedded Signup), pelo painel |
| Instância | Conexão |
| Mandar qualquer mensagem a qualquer hora | Fora da janela de 24 h, só template aprovado |
| Lista comprada ou contato que nunca falou com você | Opt-in: a pessoa precisa ter aceitado receber mensagens |
| Sem custo por mensagem | A Meta cobra por mensagem de template, direto de você |
| Risco de bloqueio do número | Número oficial, com qualidade e limite 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 traz os contatos e até 6 meses de histórico, uma única vez, na hora de conectar. Grupos não sincronizam na coexistência. Veja Conectar o WhatsApp.
Desligue a API antiga só depois que a conexão oficial estiver ativa e testada, e desconecte dela o aparelho pareado pelo QR code.
O número já está em outro parceiro
Seção intitulada “O número já está em outro parceiro”Depende do modo:
- Só API: no novo modelo de conta da Meta, o número pode ter vários parceiros ao mesmo tempo. Conecte pelo Messajo sem tirar do parceiro atual, migre aos poucos e desligue o antigo quando terminar. Veja o guia da Meta sobre o novo modelo de conta.
- Coexistência: um parceiro por vez. Desconecte no app do celular e conecte de novo pelo Messajo, como em Trocar de parceiro na coexistência.
Checklist de virada
Seção intitulada “Checklist de virada”- Templates sincronizados ou recriados no Messajo, e aprovados.
- 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.
- Um teste de ponta a ponta com um número seu: enviar, receber, status e template.
- Integração antiga desligada só depois do teste, e o número desconectado do provedor antigo, se for o caso.