01AUTH
Crie uma chave
Abra Canais → API para desenvolvedores e crie uma credencial identificada para o seu servidor.
Bearercc_live_…REST & Webhooks · API pública v1
Leve mensagens para o seu próprio produto
Envie mensagens, sincronize conversas e receba eventos dos canais usando o mesmo motor de mensagens da ConvoClerk.
OpenAPI 3.1.0API v1.0.09 Endpoints
URL Base da APIDisponível
https://app.convoclerk.com/apiComeço rápido
Sua primeira requisição em três passos
02GET
Liste os canais
Chame GET /v1/channels e escolha o ID do canal usado pela integração.
GET/v1/channels03POST
Envie ou sincronize
Envie com uma chave idempotente, consulte cursores ou configure webhooks assinados por canal.
POST/v1/messagesExplorador do contrato ao vivo
Teste todos os endpoints e repita com segurança
Escolha um canal para ver apenas as ações compatíveis. O explorador vem do contrato do backend, então requisições, exemplos de mídia e limitações permanecem alinhados com a API.
WhatsApp Cloud APICanal Ativo
Mensagens oficiais do WhatsApp Business pela Cloud API da Meta.
Recursos disponíveis
TextoImagemVídeoÁudioDocumentoResponderDigitando…Marcar conversa como visualizadaReaçõesTemplates
- Mensagens livres devem respeitar a janela de atendimento do WhatsApp.
- Áudio não aceita legenda de texto; envie o áudio e o texto em duas requisições.
- A Cloud API não permite editar ou apagar mensagens enviadas.
Listar tipos de canal
Retorna a matriz de recursos usada para validar ações específicas de cada canal.
Escopo:
channels:readURL base publicada
https://app.convoclerk.com/apiA chave fica apenas na memória desta página. O explorador envia credenciais somente para a origem publicada acima.
cURL
curl --request GET \ --url 'https://app.convoclerk.com/api/v1/channel-types' \ --header 'Authorization: Bearer cc_your_api_key'
Informe uma chave temporária para habilitar o teste.
Resposta
Execute a requisição para ver status, duração e corpo da resposta.
Autenticação e segurança das chaves
Envie Authorization: Bearer cc_… em todas as requisições. Escolha apenas os escopos necessários, mantenha as chaves no servidor e visualize ou revogue chaves ativas como administrador da empresa.
Idempotência e novas tentativas
Informe client_message_id no envio. Repetir a mesma conversa e UUID devolve a mensagem original sem enviar uma duplicata.
Consulta ou webhooks
Use after com poll_cursor para sincronização ativa ou configure webhooks message.received e message.sent em cada canal.
Webhooks & Eventos
Webhooks assinados por canal
Cada canal entrega eventos separadamente. As requisições têm timeout curto, novas tentativas com espera exponencial e nunca bloqueiam o processamento das mensagens.
Cabeçalhos HTTP de Entrega
Enviados pela ConvoClerk em cada requisição POSTx-convoclerk-signatureAssinatura HMAC-SHA256 do payloadx-convoclerk-timestampUnix timestamp da requisição (segundos)x-convoclerk-event-idUUID exclusivo para desduplicaçãoHMAC-SHA256 Timing Safe
Valide todas as entregas
Calcule HMAC-SHA256 de <timestamp>.<corpo bruto> com o segredo do canal e compare com x-convoclerk-signature.
Tolerância máx: 5 minutos
Anti Replay Attack
verify-webhook.ts
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyWebhookSignature({
rawBody,
timestamp,
signatureHeader,
signingSecret,
}: {
rawBody: string;
timestamp: string;
signatureHeader: string;
signingSecret: string;
}): boolean {
// 1. Calcula HMAC-SHA256 sobre timestamp + '.' + corpo bruto
const expectedHash = createHmac("sha256", signingSecret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
// 2. Compara com x-convoclerk-signature usando timingSafeEqual
const expectedSignature = `v1=${expectedHash}`;
if (expectedSignature.length !== signatureHeader.length) return false;
return timingSafeEqual(
Buffer.from(expectedSignature),
Buffer.from(signatureHeader)
);
}JSON Schemav2026-08-14
Envelope de evento estável
Use o ID do evento para evitar duplicatas. Os tipos são message.received, message.sent e webhook.test.
Disparado em tempo real quando um cliente envia texto, áudio ou mídia em qualquer canal.
Mensagem Recebida
{
"id": "evt_01h9yq9v8w0000000000000001",
"type": "message.received",
"api_version": "2026-08-14",
"created_at": "2026-09-22T20:15:00.000Z",
"data": {
"channel_id": "chn_meta_wa_01",
"channel_type": "meta-whatsapp",
"conversation_id": "cnv_01h9yq8x000000000000000001",
"customer": {
"id": "cst_01h9yq7z",
"name": "Maria Silva",
"phone": "+5511999998888"
},
"message": {
"id": "msg_01h9yq9v",
"direction": "inbound",
"type": "text",
"text": "Olá! Gostaria de saber os horários disponíveis."
}
}
}Orientações operacionais
- Retorne uma resposta 2xx rapidamente antes de executar tarefas demoradas.
- Evite duplicatas usando o ID do evento e da mensagem.
- Não exponha chaves de API ou segredos de assinatura em aplicações de navegador.
- Salve o histórico necessário além da política de retenção do canal.