API ИИ-консультанта
Те же запросы, что делает виджет ИИ-консультанта. API нужен, если вы рисуете чат сами: в приложении, в мессенджере или в своей вёрстке на сайте. Бот ищет по каталогу проекта, отвечает на вопросы о магазине из «Знаний консультанта» в кабинете, а если в проекте включён поиск по сайту, то и по страницам сайта.
Публичный API без ключа: проект определяется по uuid в теле запроса. CORS открыт для любых доменов.
Сообщение
Заголовок раздела «Сообщение»POST https://api.searchbooster.net/chat-api/webhook/searchbooster/chat
{ "content": "Нужен сыр для пиццы", "context": { "searchboosterUUID": "ca8fc618-9ee9-48f1-b9b6-92e810424297", "regionId": "global", "userId": "<id пользователя>", "integration": { "user_id": "<id посетителя>" }, "history": [] }}| Поле | Что делает |
|---|---|
content |
Сообщение посетителя. /start — открыть диалог (ниже). |
context.searchboosterUUID |
uuid проекта. Обязателен. |
context.regionId |
Регион из фида: цены и наличие для него. По умолчанию global. |
context.userId |
Id пользователя, тот же, что в поиске и трекере (кука searchbooster_v2_user_id). По нему диалог попадает в ленту покупателя и статистику. |
context.integration.user_id |
Id посетителя для лимита ответов. Без него посетитель определяется по IP и браузеру. |
context.history |
Предыдущие сообщения диалога (ниже). Бот учитывает последние 12. |
context.offerId |
Id товара из фида: чат о товаре, «Спросить о товаре». |
context.searchQuery, context.searchDigest, context.searchOffers |
Продолжение ИИ-обзора выдачи: запрос, текст обзора и показанные товары (до 40, в той же форме, что для обзора). Бот выбирает из них карточки. |
Ответ:
{ "content": "Для пиццы подойдёт моцарелла: можно взять «Луговое утро» 125 г за 149 ₽ или мини-моцареллу «Сырная лавка» 200 г за 219 ₽, если нужно побольше.", "executionId": "exec-ca8fc618-9ee9-48f1-b9b6-92e810424297-9eff8dbb4c79c15c8ed96bc4", "context": { "type": "events", "dialogId": "dlg-7f613825117c6cfbaf830271", "products": ["1096", "1093"], "questions": ["Покажи другие сыры", "Есть моцарелла побольше?"], "data": [ { "type": "product_collection", "data": { "offers": [ { "id": "1096", "name": "Сыр Моцарелла 45% «Луговое утро» 125 г", "url": "https://site.demo.searchbooster.io/grocery/p/1096", "price": 149, "currency": "RUR", "image_url": "https://slc.searchbooster.io/…/cheese-mozzarella.jpeg", "available": true, "vendor": "Луговое утро" } ] }, "node_id": "sb_product_collection_1", "ts": "2026-11-11T11:23:54.648Z" } ] }}content— текст ответа, 1–4 предложения. Может содержать Markdown: списки,**жирный**.context.data— карточки товаров (product_collection); показывайте их под текстом или над ним. Пустой массив, если товаров в ответе нет. В карточке необязательные поля без значения не приходят.context.products— id показанных товаров,context.questions— подсказки для следующего сообщения (кнопки).questionsприходит не всегда.context.dialogId— id диалога. Он нужен в истории, сервер диалог не хранит.context.selection— условия текущего подбора (бюджет, марки, пробег…). Приходит, если для проекта настроен подбор по условиям. Не разбирайте это поле, просто верните его в истории вместе со всемcontext(см. ниже): так бот помнит условия и не спрашивает их заново.- В карточке подбора могут быть
details— строка под названием («2021 · С пробегом · 48 000 км») иnote— пометка («Пробег немного выше указанного»). Показывайте их, если они есть. executionId— id ответа для оценки.
Ответ готовится 3–15 секунд, максимум 45. Чтобы посетитель не смотрел на пустой экран, используйте поток.
История диалога
Заголовок раздела «История диалога»Сервер не хранит диалог: каждый раз передавайте предыдущие сообщения в context.history, от старых к новым. К ответам бота кладите весь context из ответа в data.reply_context — так бот помнит dialogId и какие товары уже показал («а вторая сколько весит?»).
"history": [ { "role": "user", "content": "Нужен сыр для пиццы" }, { "role": "bot", "content": "Для пиццы подойдёт моцарелла…", "data": { "reply_context": { "dialogId": "dlg-7f613825117c6cfbaf830271", "products": ["1096", "1093"] } } }]Текущее сообщение может быть и последним элементом history с role: "user": повтор content бот не считает дважды.
Начало диалога
Заголовок раздела «Начало диалога»content: "/start":
- без
offerId— приветствие консультанта, сразу и без ИИ; - с
offerId— бот рассказывает об этом товаре («Спросить о товаре»). Дальше передавайте тот жеofferIdво всех сообщениях диалога.
Если у вас свой приветственный экран, /start не нужен: сразу отправляйте первый вопрос.
Добавьте ?stream=1 и заголовок Accept: text/event-stream — ответ придёт потоком Server-Sent Events. Каждое событие — строка data: с JSON, тип в поле kind:
kind |
Данные |
|---|---|
meta |
{"executionId": "…"} — приходит первым |
state |
payload.type: "ephemeral" — статус («Ищу товары…», payload.data.text), показывайте до следующего события; payload.type: "product_collection" — карточки, как в context.data |
delta |
{"text": "кусок ответа"} — текст по мере генерации |
done |
status: "completed", payload: {content, context} — полный текст и context как в ответе без потока (карточки уже пришли в state, в context.data их нет). status: "failed" — ответить не удалось |
Пока ответ готовится, сервер раз в 10 секунд шлёт комментарий : ping — пропускайте его. Итоговый текст берите из done: delta нужны только чтобы показывать ответ по мере генерации.
const res = await fetch('https://api.searchbooster.net/chat-api/webhook/searchbooster/chat?stream=1', { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'text/event-stream' }, body: JSON.stringify({ content: question, context: { searchboosterUUID: uuid, regionId, history } }),});const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();let buf = '';for (;;) { const { value, done } = await reader.read(); if (done) break; buf += value; let i; while ((i = buf.indexOf('\n\n')) >= 0) { const line = buf.slice(0, i); buf = buf.slice(i + 2); if (!line.startsWith('data: ')) continue; // ": ping" const ev = JSON.parse(line.slice(6)); if (ev.kind === 'delta') answer.textContent += ev.text; if (ev.kind === 'state' && ev.payload.type === 'ephemeral') status.textContent = ev.payload.data.text; if (ev.kind === 'state' && ev.payload.type === 'product_collection') showCards(ev.payload.data.offers); if (ev.kind === 'done' && ev.status === 'completed') finish(ev.payload.content, ev.payload.context); if (ev.kind === 'done' && ev.status === 'failed') showError(); }}Оценка ответа
Заголовок раздела «Оценка ответа»POST https://api.searchbooster.net/chat-api/executions/<executionId>/grade с телом {"score": 5} — оценка от 1 до 5. Ответ {"ok": true}. Оценки видны в кабинете в диалогах чата.
Клики по карточкам
Заголовок раздела «Клики по карточкам»Показы карточек сервер записывает сам. Клики и покупки из чата отправляйте как у блока рекомендаций в своей вёрстке: событие click в widget-analytics с widgetId: 100922, requestId — executionId ответа, плюс запись атрибуции с тем же widgetId. Тогда в статистике рекомендаций строка «ИИ-чат» покажет клики, корзины и выручку.
Лимиты и ошибки
Заголовок раздела «Лимиты и ошибки»| Код | Когда |
|---|---|
400 |
Неверный JSON; у оценки — неверный executionId или score вне 1–5. |
404 |
Неизвестный или выключенный проект. |
429 |
Превышен лимит ответов или часовой лимит расходов на ИИ. |
502 |
Ответить не удалось (без потока; в потоке — done со status: "failed"). Повторите сообщение. |
Тело ошибки — {"error": "<текст>"}.