Pular para o conteúdo

Migrar

Migrar de outro provedor

O que muda ao trazer sua integração de outro provedor para o Messajo.

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.

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_...
Janela do terminal
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_id vai no caminho. Ele aparece na página da conexão.
  • O cabeçalho D360-API-KEY sai; entra Authorization: Bearer com uma chave de API com permissão send.
  • 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 meta no destino para receber o mesmo value que a Meta manda, dentro do envelope do Messajo. Veja Eventos.

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 …/messages pede send; message_templates e nós de template pedem templates; outros GET, read; outras alterações, admin. Chave presa a algumas conexões só alcança essas.
  • Bloqueados com 403 mirror_path_blocked, porque derrubam a conexão: register, deregister, request_code, verify_code, smb_app_data, DELETE …/subscribed_apps e POST …/subscribed_apps com override_callback_uri.
  • Envio: POST …/messages passa pelo mesmo limite por número da camada simples (Envio por número), grava a mensagem nos logs, emite message.sent e devolve o id do Messajo no cabeçalho X-Messajo-Message-Id. O Messajo não repete o envio quando a Meta falha.
  • Resposta: status, corpo e content-type da Meta, mais X-Request-Id. O Authorization que você manda nunca segue para a Meta.

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.

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.

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.
  • 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.