Compatibilidade com a Meta

O Joinotify expõe a Meta Cloud API inteira sob o prefixo /v1. Se você já tem código escrito contra o Graph, a migração é uma troca de duas strings.

A substituição

De	Para
https://graph.facebook.com/v21.0/	https://api.joinotify.com/v1/
Authorization: Bearer <META_TOKEN>	Authorization: Bearer sk_live_xxx

Nada mais muda. Paths, corpos de requisição, respostas, códigos de status e mensagens de erro continuam idênticos — nós repassamos a resposta da Meta byte a byte.

Antes — chamando a Meta diretamente

curl -X POST https://graph.facebook.com/v21.0/106540352242922/messages \
  -H 'Authorization: Bearer EAAG...' \
  -H 'Content-Type: application/json' \
  -d '{ "messaging_product": "whatsapp", "to": "5541987111527", "type": "text", "text": { "body": "Olá!" } }'

Depois — via Joinotify

curl -X POST https://api.joinotify.com/v1/106540352242922/messages \
  -H 'Authorization: Bearer sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{ "messaging_product": "whatsapp", "to": "5541987111527", "type": "text", "text": { "body": "Olá!" } }'

Onde encontrar os IDs

O espelho exige os mesmos identificadores da Meta: phone_number_id, waba_id e, para alguns endpoints, business_id. Se você só tem o token do Joinotify, descubra os valores com:

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

O token vai sempre no header

Os exemplos da Meta frequentemente passam o token como ?access_token= na URL. No espelho isso não é aceito. O token deve estar sempre em Authorization.

# Correto
curl 'https://api.joinotify.com/v1/{WABA_ID}?fields=analytics' \
  -H 'Authorization: Bearer sk_live_xxx'

# Não funciona
curl 'https://api.joinotify.com/v1/{WABA_ID}?fields=analytics&access_token=sk_live_xxx'

Internamente, cada endpoint da Meta espera o token de um jeito diferente — o proxy resolve isso por você. A sua credencial real da Meta nunca chega ao seu código.

Endpoints bloqueados

Alguns caminhos alterariam a configuração da nossa integração com a Meta e afetariam outros clientes. Eles retornam 403 com type: forbidden_endpoint:

Segmento no path	Por que é bloqueado
subscribed_apps	Reassinar o app quebraria o roteamento de webhooks.
register · deregister	Registro do número é feito pelo painel, no onboarding.
request_code · verify_code	Verificação por SMS/voz pertence ao fluxo de conexão.
assigned_users · system_users	Gestão de usuários do nosso Business Manager.
debug_token · oauth	Exporiam metadados da credencial real.
uploads	Upload retomável; use POST /v1/{phone_number_id}/media.

Também é bloqueado o POST direto no ID de um número (POST /v1/{phone_number_id} sem sub-recurso).

403 Forbidden

{
  "error": {
    "message": "This endpoint is not available through the Joinotify proxy.",
    "type": "forbidden_endpoint"
  }
}

Propriedade dos recursos

O primeiro segmento depois de /v1/ precisa ser um phone_number_id ou waba_id que pertença à sua conta. Se não for, a resposta é 403 forbidden — a checagem acontece antes de qualquer chamada à Meta.

A exceção são IDs de mídia (GET /v1/{media_id}), que não são associáveis antecipadamente: nesse caso a Meta é quem julga a propriedade.

Erros do proxy

Quando a Meta responde, você recebe a resposta dela — inclusive os erros, no formato dela. O envelope do Joinotify só aparece nas falhas que acontecem antes de chegar lá:

HTTP	type	Situação
400	invalid_request	Nenhum ID de recurso depois de /v1/.
403	forbidden_endpoint	Caminho na lista de bloqueio.
403	forbidden	Recurso não pertence à sua conta.
502	upstream_error	Não foi possível alcançar a Meta.
504	upstream_error	A Meta demorou mais que 30 segundos.

E os webhooks?

Você não configura callback na Meta — nós recebemos os eventos e repassamos para os endpoints que você cadastrar, no mesmo envelope ({ object, entry[].changes[].value }). Handlers escritos para a Meta funcionam sem alteração; só a validação de assinatura muda, de X-Hub-Signature-256 para X-Joinotify-Signature-256.

Detalhes em Webhooks.

Endpoints não listados

A referência cobre os endpoints mais usados. Para qualquer outro, consulte a documentação oficial da Meta e aplique a substituição do topo desta página.