ConvoClerk
Log inStart free trial
REST & Webhooks · Public API v1

Build messaging into your own product

Send messages, synchronize conversations, and receive channel events using the same messaging engine as ConvoClerk.

Create an API key Download OpenAPI JSON
OpenAPI 3.1.0API v1.0.09 Endpoints
API Base URLLive
https://app.convoclerk.com/api
Quickstart

Your first request in three steps

01AUTH

Create a key

Open Channels → Developer API and create a named server-side credential.

Bearercc_live_…
02GET

List channels

Call GET /v1/channels and choose the channel ID your integration should use.

GET/v1/channels
03POST

Send or synchronize

Send with an idempotency key, poll message cursors, or configure signed channel webhooks.

POST/v1/messages
Live contract explorer

Try every endpoint, then retry safely

Choose a channel to see only its supported actions. The explorer is generated from the backend contract, so every request, media example, and limitation stays aligned with the API.

WhatsApp Cloud APIActive Channel

Official WhatsApp Business messaging through Meta's Cloud API.

Available capabilities
TextImageVideoAudioDocumentReplyTyping…Mark conversation as readReactionsTemplates
  • Free-form messages must respect WhatsApp's customer-service window.
  • Audio cannot include a text caption; send audio and text as two separate requests.
  • Editing or deleting a sent Cloud API message is not supported.
GET/v1/channel-types

List channel types

Returns the capability matrix used to validate channel-specific actions.

Scope:channels:read
Published base URL
https://app.convoclerk.com/api

The key stays only in this page's memory. The explorer sends credentials exclusively to the published origin above.

cURL
curl --request GET \
  --url 'https://app.convoclerk.com/api/v1/channel-types' \
  --header 'Authorization: Bearer cc_your_api_key'
Enter a temporary key to enable the request.
Response

Run the request to inspect its status, duration, and response body.

Authentication and key safety

Send Authorization: Bearer cc_… on every request. Choose only the scopes your integration needs, keep keys on your server, and reveal or revoke active keys as a company administrator.

Idempotency and retries

Set client_message_id when sending. Retrying the same conversation and UUID returns the original message instead of sending a duplicate.

Polling or webhooks

Use after with poll_cursor for pull-based synchronization, or configure message.received and message.sent webhooks on each channel for push delivery.

Webhooks & Events

Signed channel webhooks

Each channel can deliver independently. Requests time out quickly, retry with exponential backoff, and never block provider message processing.

HTTP Delivery Headers
Sent by ConvoClerk on every POST request
x-convoclerk-signatureHMAC-SHA256 signature of payload
x-convoclerk-timestampUnix timestamp of request (seconds)
x-convoclerk-event-idUnique UUID for event deduplication
HMAC-SHA256 Timing Safe

Verify every delivery

Compute HMAC-SHA256 over <timestamp>.<raw body> with the channel signing secret and compare it to x-convoclerk-signature.

Max tolerance: 5 minutes
Replay attack protected
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

Stable event envelope

Use the event ID for deduplication. Event types are message.received, message.sent, and webhook.test.

Triggered in real-time when a customer sends text, audio, or media on any channel.

Inbound Message
{
  "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."
    }
  }
}

Operational guidance

  • Return any 2xx response quickly before doing expensive work.
  • Deduplicate with the event id and message id.
  • Do not expose API keys or signing secrets in browser applications.
  • Persist any history you need beyond the channel retention policy.
Create an API key