Migrar da Meta

Se você já tem uma integração rodando contra o Graph, a migração é uma troca de duas strings. O resto deste guia é sobre o que fazer em volta dela.

Da Meta Cloud API direta

1. Conecte o número

O número precisa sair da sua Business Manager e entrar na nossa. No painel, em Conectar número, o Embedded Signup faz isso — o cliente autoriza pela janela do Facebook.

Enquanto o número não é migrado, sua integração antiga segue funcionando normalmente.

2. Troque domínio e token

- https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages
+ https://api.joinotify.com/v1/{PHONE_NUMBER_ID}/messages

- Authorization: Bearer EAAG...
+ Authorization: Bearer sk_live_xxx

O phone_number_id muda na migração. Pegue o novo em GET /me ou no painel.

Se o seu código passa o token como ?access_token=, isso precisa mudar: no Joinotify o token vai sempre no header. Veja Compatibilidade com a Meta.

3. Aponte os webhooks

Você não configura mais callback na Meta. Cadastre o seu endpoint aqui:

curl -X POST https://api.joinotify.com/webhook-endpoints \
  -H 'Authorization: Bearer sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "producao", "url": "https://seu-servidor.com/webhooks", "events": [] }'

O corpo entregue é o mesmo envelope da Meta, então o seu handler não muda. O que muda é a validação de assinatura:

- X-Hub-Signature-256: sha256=<hmac do corpo com o App Secret>
+ X-Joinotify-Signature-256: sha256=<hmac de "{timestamp}.{corpo}" com o whsec_>

O passo a passo está em Verificar assinatura.

4. Sincronize os templates

Templates criados na sua WABA antiga não vêm junto. Recrie-os e espere a aprovação antes de virar a chave — é o item que mais atrasa migração.

curl https://api.joinotify.com/templates \
  -H 'Authorization: Bearer sk_live_xxx'

5. Vire a chave

Com o número migrado, os templates aprovados e o webhook cadastrado, troque a URL base em produção. O phone_number_id novo precisa entrar junto.

De outro provedor (BSP)

O caminho é o mesmo, com um detalhe a mais: o número precisa ser liberado pelo provedor atual antes de entrar na nossa Business Manager. Alguns cobram ou impõem carência — confira o contrato antes de marcar data.

Se o provedor atual expõe uma API proprietária em vez do contrato da Meta, o seu código de envio precisa ser reescrito. O espelho /v1 do Joinotify segue a Meta, não o provedor.

O que não migra

Item	Situação
Histórico de conversas	Não migra. Em coexistência, dá para sincronizar do celular.
Templates	Precisam ser recriados e reaprovados.
Qualidade do número	Recomeça do zero.
Limite de mensagens em 24h	Recomeça no tier inicial e sobe com o uso.
phone_number_id e waba_id	Mudam. Atualize onde estiverem gravados.

Checklist

• Número conectado no painel do Joinotify
• phone_number_id e waba_id novos anotados
• Chave de API criada e guardada em cofre de segredos
• Token movido para o header Authorization (nada de ?access_token=)
• URL base trocada para https://api.joinotify.com/v1/
• Templates recriados e aprovados
• Endpoint de webhook cadastrado e testado com POST /webhook-endpoints/{id}/test
• Validação de assinatura trocada para X-Joinotify-Signature-256
• Tratamento de 429 com Retry-After implementado
• Integração antiga desligada só depois da primeira mensagem entregue pela nova