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

OpenAPI3.1.0

APIv1.0.0

Endpoints9

https://app.convoclerk.com/api

Your first request in three steps

Create a key

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

List channels

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

Send or synchronize

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

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 API

Official WhatsApp Business messaging through Meta's Cloud API.

Available capabilities

TextImageVideoAudioDocumentReplyTyping…Mark conversation as readReactionsTemplates

Channel notes

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 API key

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

Signed channel webhooks

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

Verify every delivery

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

const expected = hmacSha256(secret, timestamp + "." + rawBody);
timingSafeEqual("v1=" + expected, signatureHeader);

Stable event envelope

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

{
  "id": "evt_uuid",
  "type": "message.received",
  "api_version": "2026-08-14",
  "created_at": "2026-08-14T12:00:00Z",
  "data": { "channel": {}, "conversation": {}, "message": {} }
}

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