Quick start

The key, the first request, the first reply to a visitor and the first event on your address — in five steps.

On this page

Addresses
1. Get a key
2. The first request
3. Reply to a visitor
4. Subscribe to events
5. What next

Addresses #

What	Address
Public API	https://api.widgetchat.ru/api/v1
Widget file	https://api.widgetchat.ru/widget/bozex-support-widget.js
Dashboard	https://widgetchat.ru/cabinet
Bitrix24 event endpoint	https://widgetchat.ru/b24/event
amoCRM event endpoint	https://widgetchat.ru/amocrm/hook/{scope_id}
RetailCRM event endpoint	https://widgetchat.ru/retailcrm/hook/{clientId}

HTTPS only. There is no sandbox: create a separate project in the dashboard and work with it — a workspace keeps it isolated from the live one.

1. Get a key #

Dashboard → the site card → API and webhooks → Create a key. The key is shown once: the database keeps only its fingerprint.

Scopes are chosen when the key is issued: conversations:read, conversations:write, media:read. A method without its scope answers 403 insufficient_scope while the rest keep working with the same key.

2. The first request #

GET /api/v1/conversations?status=open&limit=5 conversations:read

Example call

curl -s https://api.widgetchat.ru/api/v1/conversations?status=open&limit=5 \
  -H "Authorization: Bearer wck_your_key"

Response

{
  "data": [
    {
      "id": "6c82f8e2-2ee2-4387-8c9b-34d164b18176",
      "status": "open",
      "channel": "app",
      "visitor": {"id": "u_8f1c…", "name": "John", "email": "john@example.com"},
      "source": "https://example.com/pricing",
      "createdAt": "2026-08-22T09:14:58.113Z",
      "lastMessageAt": "2026-08-22T09:15:04.281Z",
      "lastReadAt": null
    }
  ],
  "nextCursor": "2026-08-22T09:14:58.113Z",
  "hasMore": true
}

3. Reply to a visitor #

POST /api/v1/conversations/{id}/messages conversations:write

Example call

curl -s -X POST https://api.widgetchat.ru/api/v1/conversations/6c82f8e2-…/messages \
  -H "Authorization: Bearer wck_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-4417" \
  -d '{"content": "Your order is on the way, delivery tomorrow before 2 pm"}'

Response

201 {"data": {"id": "7735af47-…", "status": "queued", "direction": "outgoing",
                "createdAt": "2026-08-22T09:15:04.281Z"}}

Idempotency-Key makes a retry safe: the same key returns 200 and duplicate: true instead of a second message in the conversation.

4. Subscribe to events #

Dashboard → API and webhooks → Add an address. The signing secret is shown once. The Test button sends a webhook.test event — it shows you your own signature and your handler's response code.

The handler has to answer 2xx within 20 seconds. Move the work into your own queue: a slow answer counts as a failure and causes a retry.