#Чат с ИИ-продажником: обзор

Статус: Доступно / Планируется. Виджет одной строкой и клиентский Chat API — Доступно. Серверный API диалогов: чтение — Доступно, запись — Планируется. JS API виджета и параметры виджета v2 — Планируется. Статус каждого способа указан в таблицах ниже.

Назначение: объяснить, что умеет чат с ИИ-продажником, какими тремя способами его встроить в свой сайт, приложение или мессенджер и какой способ выбрать.

#Содержание

1. Что делает чат
2. Три способа встроить
3. Как выбрать
4. Схема потоков данных
5. Адреса ячеек
6. Деньги и пределы
7. Персональные данные и согласие
8. Куда читать дальше
9. Открытые вопросы

#Что делает чат

ИИ-продажник — собеседник на вашем сайте (или в вашем канале), который ведёт посетителя от вопроса к заявке.

Что чат не делает: не показывает другим посетителям чужие диалоги, не выполняет инструкции, спрятанные в заголовке или адресе страницы, не обещает ответа, если суточный предел ИИ исчерпан (в этом случае диалог переходит к оператору).

#Три способа встроить

Дополнительно к способу 1 планируется JS API виджета (Sapport.open(), Sapport.on(), identify и др.) — JS API виджета, статус Планируется.

Важно про способ 2. Маршруты клиентского Chat API (messages, history, poll, events, upload) не отдают заголовки CORS. Из браузера они доступны со страниц, которые открыты на домене самой ячейки, а со стороннего домена браузер заблокирует чтение ответа. Рабочие варианты — в разделе «Известные ограничения» страницы про клиентский API.

#Как выбрать

#Схема потоков данных

#Способ 1. Виджет

 Страница сайта-хозяина                       Ячейка Sapport
 ┌──────────────────────────┐
 │ <script src=…/widget.js  │   POST /api/widget/init (CORS *)
 │   data-channel=…>        │ ───────────────────────────────►  название, цвет, приветствие,
 │                          │ ◄───────────────────────────────  форма перед чатом, согласие
 │  [кнопка 60 px]          │
 │      │ клик              │
 │      ▼                   │   iframe: /widget/<channel_id>?page=…&title=…&ft=…
 │  ┌─────────────────┐     │ ───────────────────────────────►  страница чата (наш домен)
 │  │ iframe 380×560  │     │
 │  │  (наш домен)    │ ─── POST /api/widget/messages ───────►  ИИ-продажник
 │  │                 │ ◄── ответ, session_token ────────────   │  ├─ база знаний
 │  │                 │ ◄── SSE /events (или /poll) ─────────   │  ├─ контакт, лид, атрибуция
 │  └─────────────────┘     │                                    │  └─ оператор в кабинете
 │   ▲ postMessage          │
 │   └ sapport:new-message  │
 │     sapport:close        │
 └──────────────────────────┘

#Способ 2. Свой интерфейс

 Ваш интерфейс (страница на домене ячейки или ваш прокси)    Ячейка Sapport
 ┌──────────────────────┐   POST /api/widget/init            ┌─────────────────┐
 │ ввод, список реплик, │ ──────────────────────────────────►│ канал web_chat  │
 │ индикатор набора     │   POST /api/widget/messages        │ ИИ-продажник    │
 │                      │ ──────────────────────────────────►│ оператор        │
 │ хранит session_token │ ◄── response + session_token       │                 │
 │                      │   GET /history /poll /events       │                 │
 │                      │ ◄──────────────────────────────────│                 │
 └──────────────────────┘                                    └─────────────────┘

#Способ 3. Свой канал (Планируется)

 Клиент ──► ваш мессенджер ──► ваш сервер                      Ячейка Sapport
                                  │  POST /conversations          ┌────────────────────┐
                                  │  POST …/messages              │ канал «api»        │
                                  │  (Idempotency-Key, Bearer)    │ ИИ-продажник       │
                                  │ ─────────────────────────────►│ оператор           │
                                  │ ◄── 202 + operation ──────────│ кошелёк арендатора │
                                  │     (GET /operations/{id})    │                    │
                                  │ ◄── вебхук message.created ───│ outbox → доставка  │
                                  │     (ответ ИИ, ответ оператора)└────────────────────┘
 Клиент ◄── ваш мессенджер ◄──────┘

#Адреса ячеек

Три независимые ячейки. Каналы, ключи и данные принадлежат одной ячейке; используйте адрес той, где заведён ваш арендатор (Ячейки и данные).

Скрипт виджета: https://<домен ячейки>/widget.js. Клиентский Chat API: https://<домен ячейки>/api/widget/…. Серверный API: https://<домен ячейки>/api/public/v1.

#Деньги и пределы

• Каждый ответ ИИ — платная операция из кошелька арендатора. Маршрут открыт для любого посетителя, поэтому у него есть собственные ограничения.
• Длина реплики — не более 4000 знаков (413 message_too_long).
• Частота сообщений: 20 в минуту на посетителя (канал + IP) и 240 в минуту на канал. Счётчики хранятся в памяти процесса сервера.
• Суточный предел ответов ИИ на канал арендатора — 200 по умолчанию (настройка канала ai_daily_limit, максимум 10 000). После предела сообщение сохраняется, а диалог переходит к оператору; ответ клиентского Chat API содержит queued: true. В серверном API диалогов тот же предел действует для канала api: сообщение сохраняется, диалог получает состояние handoff_pending, а в ai_reply приходит {"status": "skipped", "reason": "daily_limit"}.
• Загрузка файла: 10 МБ, 5 в минуту на IP, 30 в минуту на канал.
• Серверный API: не более 5 одновременных платных операций на интеграцию, стоимость одной операции ограничена примерно 100 ₽ (Соглашения).

Подробные таблицы — на странице Клиентский Chat API.

#Персональные данные и согласие

• Если арендатор задал текст согласия с офертой, посетитель не отправит сообщение, пока не согласится. Версия согласия зависит от текста и ссылки: правка текста требует нового согласия.
• Первое касание (UTM, метки кликов, реферер) хранится в браузере на сайте-хозяине и уходит на платформу только при наличии согласия посетителя (при установке через загрузчик).
• Подробнее: Страница, источник и UTM.

#Куда читать дальше

Готовые файлы для копирования лежат в каталоге examples/.

#Открытые вопросы

• Когда будет опубликован серверный API диалогов и в каком порядке выйдут JS API виджета и параметры v2 — срок в проекте не зафиксирован. К владельцу.
• Заголовки CORS для клиентского Chat API (messages, history, poll, events, upload) в проекте не описаны; сегодня их нет. Техническое.
• Где именно GET /me отдаёт channel_id канала api и как кабинет показывает его при создании интеграции — форма ответа предварительная. Техническое.