API & webhooks

Connect your own systems with a REST API and webhooks. Both are available depending on your plan and are set up per project under Project settings → API (managers only).

API reference

Every endpoint, parameter and response is described in the interactive API reference. It is generated from the code, so it is always current. The OpenAPI 3.1 document is at /v1/openapi.json.

API keys

Enable the API for the project, then create one key per system that connects, so you can revoke it separately. Each key gets only the permissions it needs:

Permission	Allows
Conversations	Read conversations; reply, add notes, change status, assignee, tags
Contacts	Read contacts
Reports	Read statistics
Knowledge base	Read and search; create, update and delete entries
Privacy	Anonymize texts with the project’s privacy settings

Send the key as a bearer token:

curl https://api.commelia.com/v1/conversations?status=open \
  -H "Authorization: Bearer cml_..."

Internal notes are never returned by the API.

Webhooks

Webhooks notify your system about new conversations, messages, assignments, escalations, closed conversations and knowledge base suggestions. In the app you can choose events, send a test, inspect recent deliveries and send a delivery again.

Each delivery is a POST with a JSON body, signed with HMAC-SHA256. Verify the Commelia-Signature header with the endpoint’s signing secret:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Failed deliveries are retried with increasing delays. Use the Commelia-Delivery header to ignore duplicates.