Перейти к содержимому

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": "<текст>"}.