API и вебхуки WidgetChat

Что можно сделать

• Прочитать обращения Список разговоров сайта с отбором по состоянию и времени, карточка разговора и вся переписка постранично.
• Ответить посетителю Ответ появляется в окне чата на сайте так же, как ответ из Telegram, и попадает в общую историю.
• Закрыть обращение Разговор помечается закрытым, а новое сообщение посетителя заведёт следующий.
• Забрать вложение Файлы посетителя скачиваются по ключу, а в событиях приходят временной подписанной ссылкой: её откроет чужой сервер, у которого нашего ключа нет.
• Получать события Новое обращение, новое сообщение и закрытие разговора приходят запросом на ваш адрес.

Ключ доступа

Ключ выдаётся в кабинете на конкретный сайт, в разделе API и вебхуки карточки подключения. Значение показывается один раз: у нас хранится только его отпечаток. Потерянный ключ отзывается и выдаётся заново.

Ключ серверный. В код страницы его класть нельзя: оттуда его прочитает любой посетитель и получит доступ ко всей переписке.

• Документация для разработчиков
• Ключ, права и коды отказов

curl https://api.widgetchat.ru/api/v1/conversations \
  -H "Authorization: Bearer wck_ваш_ключ"

Ответ посетителю

Повторная отправка с тем же заголовком Idempotency-Key не создаёт второй ответ. Связь может оборваться уже после того, как запрос приняли, и повтор без такого ключа удвоил бы сообщение в переписке.

curl -X POST https://api.widgetchat.ru/api/v1/conversations/<id>/messages \
  -H "Authorization: Bearer wck_ваш_ключ" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-4417" \
  -d '{"content": "Заказ уже в пути, доставим завтра до 14:00"}'

События на ваш адрес

Адрес и набор событий задаются в кабинете там же, где ключи. События: conversation.started, message.created, conversation.closed. Событие message.created приходит на сообщения в обе стороны, поэтому у сообщения есть поле origin: по нему видно, что ответ написала ваша же программа и второй раз его отправлять не нужно.

Ответ 2xx значит принято. На 4xx повтора не будет. При обрыве связи, ответе 5xx или если обработчик молчит дольше 20 секунд, мы пробуем ещё раз: всего три попытки с паузами 5 и 10 секунд. Все попытки видны в журнале доставок в кабинете, журнал хранится 30 дней.

POST /ваш-обработчик 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":{…}}}

Проверка подписи

Подписывается не одно тело запроса, а метка времени и тело через точку. Подпись голого тела можно переслать повторно хоть через сутки, и обработчик не отличил бы повтор от свежего события. Метка внутри подписи делает такой повтор видимым.

Проверяйте три вещи: подпись совпала, метка времени отличается от ваших часов не больше чем на пять минут, номер доставки из заголовка X-WidgetChat-Delivery ещё не встречался. Повторная попытка приходит с тем же номером, и по нему уже принятое событие отбрасывается.

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

Секрет подписи показывается один раз при создании адреса. Забыли, смените его кнопкой в кабинете и пропишите новый в обработчике.

Пределы и правила

• Только HTTPS И для запросов к API, и для адреса, на который приходят события.
• 300 запросов в минуту на ключ Сверх предела ответ 429 с заголовком Retry-After.
• Один конверт ответа Удачный ответ содержит поле data, отказ содержит поле error с кодом и пояснением.
• Сайты изолированы Ключ открывает переписку только того сайта, на который выдан. Разговор соседнего подключения по нему не найдётся.