Referência da API
Envie mensagens e templates pelo seu número oficial da Meta, baixe mídias recebidas e receba eventos em tempo real no seu servidor. A chave de API pertence a um número (agente): ela só acessa o WhatsApp conectado a esse agente.
URL base: https://app.conext.click
1. Autenticação
- Conecte o número em Números.
- Abra API e templates, escolha o número e gere uma chave (formato
cxk_…). - A chave completa aparece uma única vez. Guarde em local seguro.
Envie a chave no cabeçalho em todas as chamadas:
Authorization: Bearer cxk_sua_chave_aquiTambém é aceito ?api_key=… na URL, mas evite: a chave pode ficar registrada em logs.
2. Mensagens
/api/v1/messagesEnviar mensagem
O corpo segue o formato da Cloud API da Meta; o Conext só acrescenta messaging_product e usa o número da chave. O campo to é obrigatório (com DDI, só dígitos).
Texto livre só pode ser enviado dentro da janela de 24h depois da última mensagem do cliente. Fora dela, use um template aprovado.
curl -X POST https://app.conext.click/api/v1/messages \
-H "Authorization: Bearer cxk_sua_chave" \
-H "Content-Type: application/json" \
-d '{
"to": "5511999999999",
"type": "text",
"text": { "body": "Seu pedido saiu para entrega!" }
}'Template (com variáveis):
{
"to": "5511999999999",
"type": "template",
"template": {
"name": "pedido_confirmado",
"language": { "code": "pt_BR" },
"components": [
{ "type": "body", "parameters": [
{ "type": "text", "text": "Maria" },
{ "type": "text", "text": "#1042" }
] }
]
}
}Resposta de sucesso:
{ "success": true, "messages": [{ "id": "wamid.HBg..." }], "contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }] }Erros: 401 chave inválida ou inativa · 400 número sem WhatsApp conectado, JSON inválido ou to ausente · demais códigos repassam o erro da Meta em details.
/api/v1/media/:idBaixar mídia recebida
Quando o cliente envia imagem, áudio, documento ou vídeo, o webhook traz um id de mídia. Use este endpoint para baixar o arquivo: o Conext resolve a URL temporária na Meta e devolve o binário com o Content-Type correto (limite de 25 MB, sem cache).
curl -H "Authorization: Bearer cxk_sua_chave" \
https://app.conext.click/api/v1/media/1234567890123456 -o arquivo3. Templates
Necessários para iniciar conversas fora da janela de 24h. Também podem ser criados pelo painel, em API e templates.
/api/v1/templatesListar templates
curl -H "Authorization: Bearer cxk_sua_chave" https://app.conext.click/api/v1/templatesRetorna { "templates": [{ "id", "name", "status", "category", "language", "components" }] }. Status: APPROVED, PENDING, REJECTED, PAUSED.
/api/v1/templatesCriar template (envia para aprovação da Meta)
Campos obrigatórios: name (minúsculas, números e _), category (UTILITY, MARKETING ou AUTHENTICATION), language e components. A análise leva de algumas horas a 72h, e a Meta pode reclassificar a categoria.
curl -X POST https://app.conext.click/api/v1/templates \
-H "Authorization: Bearer cxk_sua_chave" \
-H "Content-Type: application/json" \
-d '{
"name": "pedido_confirmado",
"category": "UTILITY",
"language": "pt_BR",
"components": [
{ "type": "BODY",
"text": "Olá {{1}}, seu pedido {{2}} foi confirmado.",
"example": { "body_text": [["Maria", "#1042"]] } }
]
}'Resposta: 201 com { "success": true, "id": "…", "status": "PENDING" }.
/api/v1/templates?name=NOMEExcluir template
Remove o template pelo nome (todas as línguas). Não pode ser desfeito.
4. Webhooks (eventos para o seu servidor)
Cadastre uma URL de webhook na chave (em API e templates). Toda notificação que a Meta enviar para o seu número (mensagens recebidas, status de entrega, leitura) é repassada para essa URL por POST, com o payload original da Meta.
Se você definiu um segredo, cada chamada traz o cabeçalho X-Conext-Signature: sha256=<hmac>, que é o HMAC-SHA256 (hex) do corpo bruto usando o segredo. Valide antes de processar:
import crypto from "crypto";
function assinaturaValida(rawBody, header, segredo) {
const esperado = "sha256=" + crypto.createHmac("sha256", segredo).update(rawBody).digest("hex");
const a = Buffer.from(esperado), b = Buffer.from(header || "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Exemplo de mensagem recebida (resumo):
{
"object": "whatsapp_business_account",
"entry": [{ "changes": [{ "field": "messages", "value": {
"metadata": { "phone_number_id": "1301817689688572" },
"contacts": [{ "profile": { "name": "Maria" }, "wa_id": "5511999999999" }],
"messages": [{ "id": "wamid...", "from": "5511999999999", "type": "text", "text": { "body": "Oi" } }]
} }] }]
}Responda 2xx rápido e processe em segundo plano. O Conext não reenvia a notificação se a sua URL falhar.
5. Chat do site (webchat)
/api/v1/webchatConversar com o agente de IA pelo site
Não usa chave. Envie o botId do agente, a message e, opcionalmente, um sessionId para manter o histórico. Parâmetros utm_* e de anúncio são aceitos para atribuição. Histórico: GET /api/v1/webchat/history.
curl -X POST https://app.conext.click/api/v1/webchat \
-H "Content-Type: application/json" \
-d '{ "botId": "ID_DO_AGENTE", "message": "Olá", "sessionId": "visitante-123" }'6. Gerenciar chaves por API
As chaves também podem ser listadas, criadas, alteradas e revogadas em /api/v1/keys?botId=…, mas essas chamadas usam a sessão do painel (login), não a chave de API. Para automatizar, use o painel.
Custos e limites da Meta
As mensagens são cobradas pela Meta na conta do WhatsApp Business do cliente. Pendência de pagamento bloqueia o envio (erro 131042): o painel avisa e o número para de enviar até regularizar. Limites diários e qualidade do número aparecem em Números.
