WidgetChat API and webhooks

What you can do

• Read conversations The site's conversations filtered by state and time, one conversation's card and the whole exchange page by page.
• Reply to a visitor The reply shows up in the chat window on the site exactly like a reply from Telegram and joins the shared history.
• Close a conversation The conversation is marked closed, and the visitor's next message starts a new one.
• Fetch an attachment Visitor files are downloaded with the key, and events carry a temporary signed link that another server can open without our key.
• Receive events A new conversation, a new message and a closed conversation are pushed to your address.

The access key

The key is issued in the dashboard for one site, in the API and webhooks section of the connection card. The value is shown once: we keep only its fingerprint. A lost key is revoked and issued again.

The key is a server key. It must not go into your page code: any visitor would read it there and get access to every conversation.

• Developer documentation
• Keys, scopes and error codes

curl https://api.widgetchat.ru/api/v1/conversations \
  -H "Authorization: Bearer wck_your_key"

Replying to a visitor

Sending again with the same Idempotency-Key header does not create a second reply. The connection can drop after the request was already accepted, and a retry without that key would double the message in the conversation.

curl -X POST https://api.widgetchat.ru/api/v1/conversations/<id>/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"}'

Events on your address

The address and the set of events are configured in the dashboard next to the keys. Events: conversation.started, message.created, conversation.closed. The message.created event fires for messages in both directions, so a message carries an origin field: it shows that the reply came from your own program and does not have to be sent again.

A 2xx answer means accepted. A 4xx is not retried. On a dropped connection, a 5xx, or if your endpoint stays silent for more than 20 seconds, we try again: three attempts in total, with pauses of 5 and 10 seconds. Every attempt is visible in the delivery log in the dashboard, which keeps 30 days.

POST /your-handler HTTP/1.1
Content-Type: application/json
X-WidgetChat-Event: message.created
X-WidgetChat-Delivery: message.created:8f1c…
X-WidgetChat-Attempt: 1
X-WidgetChat-Timestamp: 1755878400
X-WidgetChat-Signature: sha256=6b2f…

{"id":"message.created:8f1c…","event":"message.created","createdAt":"2026-08-22T12:00:00Z",
 "workspaceKey":"example-ru","data":{"conversation":{…},"message":{…}}}

Checking the signature

What is signed is not the body alone but the timestamp and the body joined by a dot. A signature over a bare body could be replayed a day later and the handler would not tell the replay from a fresh event. The timestamp inside the signature makes such a replay visible.

Check three things: the signature matches, the timestamp is no more than five minutes away from your clock, and the delivery id from the X-WidgetChat-Delivery header has not been seen before. A retry arrives with the same id, so an event already taken into work is dropped by it.

# Go
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(timestampHeader + "." + string(body)))
expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))

The signing secret is shown once when the address is created. If you lose it, replace it with the button in the dashboard and put the new one into your handler.

Limits and rules

• HTTPS only Both for API requests and for the address events are sent to.
• 300 requests per minute per key Above the limit the answer is 429 with a Retry-After header.
• One response envelope A successful answer carries a data field, a failure carries an error field with a code and an explanation.
• Sites are isolated A key opens the conversations of the site it was issued for. A neighbouring site's conversation is not found with it.