Meta Proxy

O meta-proxy é um relay autenticado: você faz a chamada com seu channel_token, e o Coexy injeta o token de acesso Meta real antes de encaminhar para a API da Meta. Seus tokens Meta nunca ficam expostos no seu código.

A regra de ouro

Para qualquer chamada à Meta Graph API, substitua apenas dois elementos:

Original	Via Coexy
`https://graph.facebook.com/v23.0/`	`https://api.coexy.com.br/functions/v1/meta-proxy/`
`Authorization: Bearer <meta-access-token>`	`Authorization: Bearer <channel_token>`

O restante — método HTTP, path, query params, body e campos — segue exatamente a documentação oficial da Meta.

Autenticação

Base URL: https://api.coexy.com.br/functions/v1/meta-proxy
Header:   Authorization: Bearer <channel_token>

O channel_token identifica um canal específico. Encontre-o em Painel Coexy → Canais → detalhe do canal, ou no campo channel_token da resposta de GET /api/channels.

O channel_token é diferente da COEXY_API_KEY. Não os misture.

Exemplos

Listar templates

curl "https://api.coexy.com.br/functions/v1/meta-proxy/{waba_id}/message_templates?fields=name,status,category,language,components" \
  -H "Authorization: Bearer <channel_token>"

Enviar mensagem de texto

curl -X POST "https://api.coexy.com.br/functions/v1/meta-proxy/{phone_number_id}/messages" \
  -H "Authorization: Bearer <channel_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "Olá! Como posso ajudar?" }
  }'

Enviar template com variável

curl -X POST "https://api.coexy.com.br/functions/v1/meta-proxy/{phone_number_id}/messages" \
  -H "Authorization: Bearer <channel_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "nome_do_template",
      "language": { "code": "pt_BR" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "João Silva" }
          ]
        }
      ]
    }
  }'

O waba_id e o phone_number_id do canal estão disponíveis nos campos correspondentes da resposta de GET /api/channels/:id.

Idempotência no envio

Para evitar envios duplicados em caso de retry, inclua idempotency_key no body:

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "text",
  "text": { "body": "Confirmação do pedido #42" },
  "idempotency_key": "pedido-42-confirmacao"
}

O Coexy remove o campo antes de encaminhar para a Meta e garante que a mesma mensagem não seja enviada duas vezes com a mesma chave.

Segurança — nunca chame o meta-proxy direto do frontend

Se você usa Lovable, Bolt, Cursor ou qualquer plataforma que gera código React, nunca chame o meta-proxy diretamente do frontend. O channel_token ficaria visível no browser para qualquer usuário.

❌ Frontend React  →  https://api.coexy.com.br/functions/v1/meta-proxy/...
✅ Frontend React  →  Supabase Edge Function  →  https://api.coexy.com.br/functions/v1/meta-proxy/...

Crie uma Edge Function no Supabase para cada operação (ex: send-whatsapp-message). O frontend chama sua Edge Function via supabase.functions.invoke(), e a Edge Function usa o secret para chamar o Coexy. As credenciais nunca chegam ao browser.

Exemplos em Python

Enviar mensagem de texto

import httpx

response = httpx.post(
    f"https://api.coexy.com.br/functions/v1/meta-proxy/{phone_number_id}/messages",
    headers={
        "Authorization": f"Bearer {channel_token}",
        "Content-Type": "application/json",
    },
    json={
        "messaging_product": "whatsapp",
        "to": "5511999999999",
        "type": "text",
        "text": {"body": "Olá! Como posso ajudar?"},
    },
)
print(response.json())

Erros

Status	`error`	Causa	O que fazer
`401`	`Authorization header required`	Header `Authorization` ausente	Adicionar `Authorization: Bearer <channel_token>`
`401`	`Invalid channel token`	Token inválido ou canal não existe	Verificar o `channel_token` no painel ou via `GET /api/channels`
`403`	`Channel is not active`	Canal desconectado ou suspenso	Verificar status do canal; se `disconnected`, reconectar via `connect_url`
`429`	`Rate limit exceeded`	Limite de 100 req/min por canal	Aguardar o tempo indicado no header `Retry-After`
`503`	`CHANNEL_DISCONNECTED`	Token Meta foi revogado (ex: mudança de senha, remoção de permissão)	Não recrie o canal. Acesse o `connect_url` para reconectar. Webhooks e configurações são preservados.

Sobre o erro 503: Em operação normal, o Coexy renova tokens automaticamente e você nunca verá esse erro. Ele só ocorre quando a Meta revoga o acesso por motivos externos (ex: o dono do número removeu a permissão do app).

Introdução

Configurar (Canais & Webhooks)

Enviar Mensagens

Receber Eventos

A regra de ouro

Autenticação

Exemplos

Listar templates

Enviar mensagem de texto

Enviar template com variável

Idempotência no envio

Segurança — nunca chame o meta-proxy direto do frontend

Exemplos em Python

Enviar mensagem de texto

Erros

​A regra de ouro

​Autenticação

​Exemplos

​Listar templates

​Enviar mensagem de texto

​Enviar template com variável

​Idempotência no envio

​Segurança — nunca chame o meta-proxy direto do frontend

​Exemplos em Python

​Enviar mensagem de texto

​Erros

A regra de ouro

Autenticação

Exemplos

Listar templates

Enviar mensagem de texto

Enviar template com variável

Idempotência no envio

Segurança — nunca chame o meta-proxy direto do frontend

Exemplos em Python

Enviar mensagem de texto

Erros