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, visitor.identified. Событие message.created приходит на сообщения в обе стороны, поэтому у сообщения есть поле origin — по нему видно, что ответ написан вашей же программой, и его не нужно отправлять второй раз.

Ответ 2xx означает «принято». На 4xx повтора не будет: получатель не изменит мнение. Всё остальное — обрыв связи, 500, таймаут — повторяется трижды с растущей паузой, после чего попытки видны в журнале доставок в кабинете.

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 с кодом и пояснением.
• Изоляция сайтов — Ключ открывает переписку только того сайта, на который выдан. Разговор соседнего подключения по нему не найдётся.

Частые вопросы