🔗API консультанта: запрос, ответ и ошибки

API консультанта

Ваша система — чат на сайте, CRM, телефония — отправляет вопрос клиента консультанту Sensei и получает ответ по базе знаний. Как создать консультанта и выпустить токен с правом bot:chat, рассказано в статье «AI-консультант для внешней системы».

Запрос

POST https://sensei.red/api/bot/{slug}/chat
Authorization: Bearer mcp_ВАШ_ТОКЕН
Content-Type: application/json

{
  "message": "Хочу записать ребёнка на робототехнику",
  "session_id": "client-42",
  "chat_history": [
    {"role": "user", "text": "Здравствуйте"},
    {"role": "assistant", "text": "Здравствуйте! Чем могу помочь?"}
  ],
  "context": "Клиент: Иван, абонемент до 2026-09"
}

• {slug} — адрес консультанта из его карточки в разделе «AI-консультанты»; консультант должен быть включён.
• message — вопрос клиента, обязательно, до 4000 символов.
• chat_history — предыдущие реплики, старые первыми, до 60. Sensei не хранит историю диалога — передавайте её в каждом запросе.
• context — данные о клиенте из вашей системы, до 8000 символов. Это справочные данные, а не инструкции консультанту.
• session_id — ваш идентификатор диалога: вернётся в ответе и свяжет записи в логах.

Ответ

{
  "answer": "…",
  "sources": [...],
  "referenced_articles": [...],
  "is_empty": false,
  "session_id": "client-42",
  "json_valid": null
}

• answer — текст ответа.
• sources — самые релевантные статьи (может быть пустым), referenced_articles — все статьи базы знаний, на которые опирался ответ. У обоих есть url; ссылки для клиента надёжнее строить по referenced_articles.
• is_empty — в базе знаний ответа не нашлось.
• json_valid — только для консультантов с включённым «Ответ в формате JSON»: разбирается ли ответ как JSON.

Лимиты и ошибки

• Ответ готовится до 1–2 минут — ставьте таймаут клиента не меньше 120 секунд.
• 429 — больше 60 запросов в минуту на токен; подождите время из заголовка Retry-After.
• 402 — исчерпан лимит AI по тарифу: в ответе "code": "ai_quota_exhausted" и retry_after.
• 401 — токен неверный, истёк или отозван либо выпустивший его администратор заблокирован или лишён прав (причина — в поле detail и в карточке токена в настройках); 403 — у токена нет права bot:chat или тариф ниже «Бизнеса»; 404 — консультант с таким slug не найден или выключен; 503 — временная ошибка AI, повторите запрос позже.