API виджета

Публичный embed использует Site ID (wgt_…) и проверку Origin на bootstrap. API-ключ в браузере не используется. Для server-side BFF — POST /v1/widget/embed-session с правом widget:embed:issue.

Создать visitor-сессию

Создаёт visitor-сессию и отдаёт конфиг активного пресета. Вызывается embed shell и createWidgetClient({ siteId }).

POST /v1/widget/bootstrap
Origin: https://your-site.com
Content-Type: application/json

{
  "site_id": "wgt_...",
  "visitor_id": "optional-uuid",
  "config_etag": "optional-etag"
}

{
  "visitor_id": "uuid",
  "token": "visitor-jwt",
  "ws_ticket": "uuid",
  "ws_url": "wss://...",
  "config": {},
  "etag": "abc123",
  "preset_id": "uuid"
}

Выдать сессию с сервера

Только server BFF — API key с правом widget:embed:issue.

POST /v1/widget/embed-session
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "visitor_id": "optional-uuid",
  "config_etag": "optional"
}

{
  "visitor_id": "uuid",
  "token": "visitor-jwt",
  "ws_ticket": "uuid",
  "ws_url": "wss://...",
  "config": {},
  "etag": "abc123",
  "preset_id": "uuid"
}

Сообщение посетителя

POST /v1/widget/messages
X-Visitor-Token: {visitor-jwt}
Content-Type: application/json

{
  "visitor_id": "uuid",
  "body": "Текст сообщения",
  "idempotency_key": "stable-id"
}

Канал: widget:{visitor_id}. SDK: createWidgetClient().sendMessage(...).

Для изображения или документа сначала используйте visitor upload intent, завершите загрузку и передайте attachment_ids. Повторная отправка с тем же idempotency_key безопасна.

История чата

X-Visitor-Token + query visitor_id, limit.

Статус E2EE

Возвращаются уровень шифрования и параметры рукопожатия. Сервер не получает приватный ключ посетителя; если E2EE выключен политикой канала, старт отклоняется.

Идентификация посетителя

Visitor JWT позволяет безопасно записать email, телефон или внешний id CRM. Ответ не возвращает эти значения обратно браузеру.

Аналитика

Beacon для аналитики виджета. События SDK 1.2.0:

• widget.loaded
• widget.config_loaded
• widget.launcher_clicked
• widget.opened
• widget.closed
• widget.panel_expanded
• widget.panel_collapsed
• widget.session_started
• widget.message_sent
• widget.message_received
• widget.attachment_clicked
• widget.ws_connected
• widget.ws_disconnected
• widget.error
• widget.custom

Управление установками (панель)

CRUD /v1/widget/installs — Site ID, allowlist Origin. Только JWT панели, не публичный API.

Ответ оператора (панель)

Ответы из панели — POST /v1/conversations/widget:{visitor_id}/messages. См. гайд по панели.

WebSocket

Подключение по ws_url с ws_ticket из bootstrap (предпочтительнее JWT в query). См. гайд по виджету.

SDK

• @sapportly/widget-sdk — embed UI (React, Vue, Svelte, Next)
• @sapportly/sdk — client.widget (bootstrap / embed-session)