Enviar mensagens e mídia

O Coexy não tem API própria de envio. O meta-proxy é um relay da WhatsApp Cloud API: método, path, query e body seguem a documentação da Meta. Só duas coisas mudam:

Direto na Meta	Pelo Coexy
`https://graph.facebook.com/v23.0/`	`https://api.coexy.com.br/functions/v1/meta-proxy/`
`Authorization: Bearer <token-da-meta>`	`Authorization: Bearer <channel_token>`

O channel_token, o phone_number_id e o waba_id vêm em GET /api/channels. O proxy usa a versão v23.0 da Graph API; não coloque a versão na URL.

Chame o meta-proxy só do seu backend. O channel_token dá acesso ao canal e não pode ir para o navegador. Ele é diferente da COEXY_API_KEY; não os misture.Se você usa Lovable, Bolt, Cursor ou outra plataforma que gera código React, crie uma Edge Function no Supabase para cada operação (ex.: send-whatsapp-message). O frontend chama a função com supabase.functions.invoke() e a função chama o Coexy com o token guardado nos secrets.

Enviar mensagem

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?" }
  }'

Templates, botões, listas, CTA com URL e os demais tipos usam o mesmo endpoint, com o body da documentação da Meta. Mensagens que não são template só podem ser enviadas dentro da janela de 24 horas aberta pelo contato. Para evitar envio duplicado em retentativas, inclua idempotency_key no body. O Coexy remove o campo antes de repassar à Meta. A chave vale por canal, por 7 dias a partir do envio aceito:

mesma chave e mesmo body: devolve a resposta original (com o wamid) sem reenviar;
mesma chave com body diferente: 422 idempotency_key_reused, nada é enviado;
mesma chave enquanto o primeiro envio ainda está em andamento: o Coexy espera até 10 s e devolve o mesmo resultado; se passar disso, 409 idempotency_in_progress (repita a chamada sem mudar nada);
se a Meta recusar o envio, a chave é liberada e pode ser usada na retentativa.

Python

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}"},
    json={
        "messaging_product": "whatsapp",
        "to": "5511999999999",
        "type": "text",
        "text": {"body": "Olá! Como posso ajudar?"},
        "idempotency_key": "pedido-42-confirmacao",  # opcional
    },
)
print(response.json())

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>"

Template com imagem, vídeo ou documento no cabeçalho

O arquivo do cabeçalho é enviado em cada mensagem: cada cliente pode receber o próprio PDF, imagem ou vídeo com o mesmo template aprovado. Use link (URL pública) ou o id de uma mídia enviada antes (seção abaixo).

curl -X POST "https://api.coexy.com.br/functions/v1/meta-proxy/{phone_number_id}/messages" \n  -H "Authorization: Bearer <channel_token>" \n  -H "Content-Type: application/json" \n  -d '{
    "messaging_product": "whatsapp",
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "segunda_via_boleto",
      "language": { "code": "pt_BR" },
      "components": [
        {
          "type": "header",
          "parameters": [
            { "type": "document", "document": { "link": "https://seusite.com/boletos/123.pdf", "filename": "boleto.pdf" } }
          ]
        },
        {
          "type": "body",
          "parameters": [{ "type": "text", "text": "Ana" }]
        }
      ]
    }
  }'

Para imagem e vídeo, troque por { "type": "image", "image": { "link": "..." } } ou { "type": "video", "video": { "link": "..." } }. O arquivo de exemplo enviado ao criar o template no painel serve só para a revisão da Meta.

Enviar mídia (upload)

Mesmo endpoint da Meta, em multipart/form-data. Não defina o Content-Type manualmente; deixe a biblioteca HTTP gerar o boundary.

curl -X POST "https://api.coexy.com.br/functions/v1/meta-proxy/{phone_number_id}/media" \
  -H "Authorization: Bearer <channel_token>" \
  -F "messaging_product=whatsapp" \
  -F "type=image/jpeg" \
  -F "file=@foto.jpg"

O id retornado vai no envio da mensagem, por exemplo "image": { "id": "<media_id>" }.

Baixar mídia recebida

O webhook traz só o id da mídia (ex.: message.audio.id). O download segue os dois passos da Meta:

GET /meta-proxy/{media_id} devolve url, mime_type, sha256 e file_size. A url já aponta para o Coexy (https://api.coexy.com.br/functions/v1/meta-proxy/lookaside/...).
GET <url> com o mesmo Authorization: Bearer <channel_token> devolve o arquivo.

const headers = { Authorization: `Bearer ${channelToken}` }
const base = 'https://api.coexy.com.br/functions/v1/meta-proxy'

const media = await fetch(`${base}/${mediaId}`, { headers }).then(r => r.json())
const file = await fetch(media.url, { headers })
const bytes = new Uint8Array(await file.arrayBuffer()) // tipo em media.mime_type

A url expira em cerca de 5 minutos: baixe logo após obtê-la e, se expirar, repita o passo 1. Use a url exatamente como veio; acessar lookaside.fbsbx.com direto falha, porque exige o token da Meta.

Sincronizar contatos e histórico (coexistência)

Em números conectados pelo app WhatsApp Business, peça a sincronização em até 24 horas depois da conexão (veja coexistence.sync_deadline em GET /api/channels). Cada tipo só pode ser pedido uma vez. Se você já tinha um webhook assinando smb_app_state_sync ou history quando o canal conectou, o Coexy já pediu por você.

curl -X POST "https://api.coexy.com.br/functions/v1/meta-proxy/{phone_number_id}/smb_app_data" \
  -H "Authorization: Bearer <channel_token>" \
  -H "Content-Type: application/json" \
  -d '{ "messaging_product": "whatsapp", "sync_type": "smb_app_state_sync" }'
# depois, o mesmo com "sync_type": "history"

Os dados chegam nos eventos de webhook smb_app_state_sync e history. Veja Webhooks.

Erros

Status	`error`	O que fazer
`401`	`Authorization header required` / `Invalid channel token`	Conferir o `channel_token`
`401`	`Channel token expired` (`code: token_expired`)	O `channel_token` passou da validade (`channel_token_expires_at`). Gere outro com `POST /channels/:id/rotate-token` ou no painel
`402`	`subscription_blocked`	Assinatura bloqueada por falta de pagamento: nenhuma chamada passa pelo proxy até o pagamento. Regularize em coexy.com.br, na página Plano
`402`	`subscription_canceled`	Assinatura cancelada: nenhuma chamada passa pelo proxy. Assine um plano na página Plano para voltar
`403`	`Channel is not active`	Canal desconectado ou suspenso; reconectar pelo `connect_url`
`403`	`This endpoint is managed by Coexy` (`code: managed_by_coexy`)	Registro do número (`register`, `deregister`, `request_code`, `verify_code`), PIN de duas etapas, webhooks (`subscribed_apps`, `webhook_configuration`) e tokens são gerenciados pelo Coexy e não passam pelo proxy
`429`	`Rate limit exceeded`	Limite de 100 envios por minuto por canal; aguardar o `Retry-After`
`503`	`CHANNEL_DISCONNECTED`	O token da Meta foi revogado. Não recrie o canal: reconecte pelo `connect_url`

Demais erros vêm da Meta, no formato da Cloud API.

Introdução

Configurar (Canais & Webhooks)