A REST API you can read in an afternoon.

curl https://api.chatdrill.com/v1/conversations \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

GET /v1/conversations?status=open&limit=20

{
  "object": "list",
  "has_more": true,
  "next_cursor": "cnv_8fQ2mR",
  "data": [
    {
      "id": "cnv_7hK2p9",
      "status": "open",
      "channel": "web",
      "subject": "Question about annual billing",
      "assignee_id": "usr_3bd1",
      "contact_id": "ctc_91xz",
      "tags": ["billing"],
      "last_message_at": "2026-08-14T09:41:02Z",
      "created_at": "2026-08-14T09:38:55Z"
    }
  ]
}

POST /v1/conversations
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "website_id": "web_1a2b3c",
  "contact": {
    "email": "dana@example.com",
    "name": "Dana Whitfield"
  },
  "message": {
    "body": "My export finished but the file is empty.",
    "author": "contact"
  },
  "tags": ["exports"],
  "attributes": {
    "plan": "growth",
    "source_page": "/settings/export"
  }
}

HTTP/1.1 201 Created

{
  "id": "cnv_7hK2p9",
  "status": "open",
  "channel": "api",
  "contact_id": "ctc_91xz",
  "assignee_id": null,
  "tags": ["exports"],
  "created_at": "2026-08-15T11:02:17Z"
}

PUT /v1/contacts
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "external_id": "user_44120",
  "email": "dana@example.com",
  "name": "Dana Whitfield",
  "phone": "+15551234567",
  "attributes": {
    "plan": "growth",
    "seats": 12,
    "signed_up_at": "2026-02-03T00:00:00Z"
  }
}

POST /v1/conversations/cnv_7hK2p9/messages
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "body": "The export is rebuilding now — you will get an email when it is ready.",
  "author": "agent",
  "author_id": "usr_3bd1",
  "type": "reply"
}

POST https://yourapp.com/hooks/chatdrill
X-Chatdrill-Signature: t=1755255737,v1=6f2c9d...
Content-Type: application/json

{
  "id": "evt_2mQ81a",
  "type": "conversation.created",
  "created_at": "2026-08-15T11:02:17Z",
  "data": {
    "conversation_id": "cnv_7hK2p9",
    "website_id": "web_1a2b3c",
    "contact_id": "ctc_91xz",
    "channel": "web",
    "first_message": "My export finished but the file is empty."
  }
}

import crypto from "node:crypto";

export function verify(rawBody, header, secret) {
  const [tsPart, sigPart] = header.split(",");
  const timestamp = tsPart.split("=")[1];
  const signature = sigPart.split("=")[1];

  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex");

  // Constant-time compare, and reject anything older than five minutes.
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

window.chatdrill("identify", {
  id: "user_44120",
  email: "dana@example.com",
  name: "Dana Whitfield",
  created_at: "2026-02-03T00:00:00Z",
  attributes: {
    plan: "growth",
    seats: 12,
    mrr: 348
  }
});

// Open and close the widget
window.chatdrill("open");
window.chatdrill("close");

// Open with a message already typed for the visitor
window.chatdrill("open", { message: "I need help with billing" });

// Show or hide the launcher entirely
window.chatdrill("hide");
window.chatdrill("show");

// Clear the session on logout so the next user starts fresh
window.chatdrill("logout");

// React to widget events
window.chatdrill("on", "conversation:started", function (payload) {
  analytics.track("Chat started", { conversationId: payload.id });
});

HTTP/1.1 200 OK
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 1755255780

HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "website_id is required.",
    "param": "website_id",
    "request_id": "req_5tB0nQ"
  }
}