Do primeiro envio ao webhook assinado.
Uma API REST para WhatsApp, SMS, RCS, e-mail e push, com chave de teste e de produção, repetição segura e eventos assinados. O contrato público inteiro está no openapi.json.
A chave de teste começa com ccx_test_ e usa uma carteira de teste. Nada chega a cliente nenhum.
- Crie uma chave de APIccx_test_••••••••Aparece uma vez
- Envie a mensagemPOST /messages201 na fila
- Receba o status no seu webhookmessage.deliveredAssinatura válida
Seu primeiro envio, em três passos.
Comece com a chave de teste: ela usa a carteira de teste e um envio simulado, então nada chega a cliente nenhum e nada é debitado de verdade.
curl -X POST https://api.messages.ccxcompany.co/messages \ -H "Authorization: Bearer $CCX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: pedido-4821-saiu" \ -d '{ "numberId": "num_…", "to": "+5511…", "type": "text", "payload": { "text": { "body": "Seu pedido saiu para entrega" } } }'
Corpo resumido; o objeto completo da mensagem está no openapi.json. Valores com … são exemplos.
Chaves, escopos e repetição segura.
Toda chamada leva Authorization: Bearer com a sua chave. Cada rota pede um escopo, e a chave só faz o que os escopos dela permitem.
Repita sem enviar duas vezes.
Nos envios de WhatsApp, SMS e push, o cabeçalho Idempotency-Key deixa você repetir a mesma chamada por 24 horas. Mesma chave e mesmo corpo devolvem a resposta original. Mesma chave com outro corpo dá 409. Experimente.
- Idempotency-Key: pedido-4821 · corpo A201msg_01… criada e na fila
- Idempotency-Key: pedido-4821 · corpo A201Resposta original de msg_01…, nada foi enviado de novo.
- Idempotency-Key: pedido-4821 · corpo B409CONFLICT · IDEMPOTENCY_CONFLICT
Respostas simuladas e resumidas. Valores com … são exemplos.
Webhooks assinados, com reentrega.
Cadastre o endereço, escolha os eventos e guarde o segredo. Cada entrega sai com X-CCX-Signature, X-CCX-Event, X-CCX-Delivery-Id e X-CCX-Idempotency-Key.
- 5 s
- 30 s
- 2 min
- 10 min
- 1 h
import { createHmac, timingSafeEqual } from "node:crypto"; // X-CCX-Signature: t=<unix>,v1=<hex>export function assinaturaValida(segredo, corpo, cab) { const p = Object.fromEntries( cab.split(",").map((kv) => kv.split("="))); if (Math.abs(Date.now() / 1000 - p.t) > 300) return false; const esperado = createHmac("sha256", segredo) .update(p.t + "." + corpo).digest("hex"); return esperado.length === p.v1.length && timingSafeEqual(Buffer.from(esperado, "hex"), Buffer.from(p.v1, "hex"));}
Calcule sobre o corpo bruto, exatamente como chegou, sem reserializar o JSON. A janela de 5 minutos no carimbo t barra reenvio de evento antigo.
- message.sent
- message.delivered
- message.read
- message.failed
- message.received
- template.approved
- template.rejected
- sms.delivered
- sms.received
- email.delivered
- email.bounced
- email.opened
- wallet.low_balance
Quando a resposta não é 2xx.
Todo erro vem no formato problem details (RFC 7807), com um code estável que o seu código pode comparar. Escolha um para ver a resposta.
HTTP/1.1 409Content-Type: application/problem+json { "type": "about:blank", "title": "conflict", "code": "CONFLICT", "status": 409, "detail": "idempotency key reused with a different payload", "meta": { "code": "IDEMPOTENCY_CONFLICT" }}
Exemplo de corpo de erro, como a API devolve.
O que dá para fazer pela API.
As rotas abaixo estão no contrato público. O que não está no openapi.json não é contrato e pode mudar.
Guias para o que mais trava.
Respostas curtas para as dúvidas que aparecem quando a integração sai do papel.
Acentos trocados antes do envio: á vira a. A mensagem inteira cabe no GSM-7, então continua valendo 160 caracteres por um segmento.
Contado do jeito que a fatura conta. POST /v2/sms/preview devolve segmentos e preço antes de enviar. O SMS vai para números do Brasil; rotas internacionais são sob consulta.
Meu template foi rejeitado pela Meta. E agora?
Quase sempre é formato, não conteúdo: promoção declarada como utilidade, variável no começo ou no fim do corpo, ou botão de URL sem um prefixo fixo. Antes de enviar para a Meta, o editor do painel avisa quando o texto tem linguagem promocional agressiva, quando um template de marketing não tem botão de opt-out e quando o corpo passa de 1.024 caracteres.
Quanto tempo leva para aprovar meu número?
São duas etapas. A verificação do número, com o código por SMS ou ligação, é rápida. A verificação do negócio, que libera limites maiores de envio, é feita pela própria Meta, e o prazo é dela.
Quantos segmentos meu SMS vai cobrar?
Até 160 caracteres é um segmento; acima disso, um a cada 152. Com emoji, a mensagem vai em Unicode: até 70 é um segmento, acima disso um a cada 67. Acento que não existe no GSM-7 é trocado pelo equivalente quando a mensagem inteira cabe no GSM-7, então acento não encarece. POST /v2/sms/preview devolve segmentos e preço antes de enviar. O SMS vai para números do Brasil; rotas internacionais são sob consulta.
O que acontece se o saldo acabar?
A carteira é pré-paga e o débito acontece no envio. Sem saldo, SMS, RCS e e-mail respondem 402, e os envios de WhatsApp e push falham com o status de saldo insuficiente. Campanha de SMS que fica sem saldo no meio pausa com o motivo na tela, e o Retomar envia as mensagens recusadas por falta de saldo junto com o resto. A carteira de teste é separada e nunca debita valor real.
Meus e-mails estão caindo em spam
Publique SPF, DKIM e DMARC do domínio, suba o volume aos poucos em domínio novo, tire da lista os endereços inválidos e separe transacional de marketing em subdomínios. Endereço que volta com bounce entra na lista de supressão.
Meu webhook não recebe os eventos
Confira se o endereço responde 2xx em até 10 segundos, se a assinatura é calculada sobre o corpo bruto e se o webhook está ativo, não pausado. Um 4xx do seu lado (fora 408 e 429) não é repetido; 5xx e falta de resposta são, depois de 5 s, 30 s, 2 min, 10 min e 1 h.
Como convido o time e defino permissões?
Convide por e-mail e escolha um dos nove papéis, de proprietário a somente leitura. A organização pode exigir verificação em duas etapas de todos os membros, com 30 dias de carência. Não há cobrança por usuário, então ninguém precisa dividir login.
Travou em alguma rota? Fale com quem mantém a API.
Criando a conta pelo site, você ganha R$ 10 de crédito de teste.