Рецепт: ответы AI-агента, база знаний и свой бот

Обновлено: 11 ноября 2026 · 5 мин чтения

Шаги

1. 1

   Что Вы получите

   • Поиск или помощник на Вашем сайте отвечает по инструкциям и базе знаний AI-агента Clomni.
   • Когда сайт меняется, AI-агент отвечает по новым данным, базу знаний не нужно обновлять вручную.
   • Ваш бот (например, Ваша LLM) отвечает в диалогах WhatsApp, Instagram и чата и передаёт оператору, когда не справляется.
2. 2

   A. Ответы AI-агента на Вашей платформе

   Scope: ai_agents:read (низкий риск), чтобы узнать id агента, ai_agents:ask (средний риск), чтобы задавать вопросы.

   Список агентов:

   curl "https://api.clomni.ai/v1/ai_agents" \
     -H "Authorization: Bearer clomni_pat_xxx"

   Задайте вопрос. Если это продолжение разговора, передайте прошлые вопросы и ответы в history: Clomni Ваш разговор не хранит.

   curl -X POST "https://api.clomni.ai/v1/ai_agents/4/ask" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"question": "А в регионы?", "history": [{"role": "user", "content": "Сколько идёт доставка?"}, {"role": "assistant", "content": "По Баку 1 рабочий день."}]}'

   { "answer": "В регионы заказ доставляется за 2-3 рабочих дня.", "handoff": false, "sources": [] }

   • question не длиннее 4000 символов, из history учитываются последние 20 сообщений. Пустой или слишком длинный вопрос возвращает 400 invalid_request, неизвестный агент 404 not_found.
   • При handoff: true агент сам ответить не может и answer равно null: передайте вопрос человеку.
   • sources пока всегда пустой список.
   • В диалоги ничего не пишется: ask только возвращает ответ Вам.
   • Каждый ответ списывается с AI-кредита workspace. Когда он заканчивается, приходит 402 ai_credit_spent. Остаток показывает GET /v1/ai_credits (billing:read).
3. 3

   B. Обновление базы знаний из Вашей системы

   Scope: knowledge:write (средний риск) и ai_agents:read для id агента. Если будете писать FAQ, ещё ai_agents:train (средний риск).

   Добавьте страницу сайта по ссылке:

   curl -X POST "https://api.clomni.ai/v1/knowledge" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"document": {"name": "Правила доставки", "external_link": "https://demo-store.example/delivery", "assistant_id": 4}}'

   Документ обрабатывается в фоне, это может занять несколько минут. Готов ли он, показывает status в ответе GET /v1/knowledge?assistant_id=4. Отдельного endpoint для обновления нет: когда страница меняется, удалите старый документ через DELETE /v1/knowledge/{document_id} и добавьте заново.

   Для коротких вопросов и ответов пишите FAQ:

   curl -X POST "https://api.clomni.ai/v1/ai_agent_faqs" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"question": "Сколько идёт доставка?", "answer": "По Баку 1 рабочий день, в регионы 2-3 рабочих дня.", "assistant_id": 4}'

   Менять настройки и инструкции агента из кода нужно в два шага: ai_agents:write меняет черновик (PATCH /v1/ai_agents/{ai_agent_id}/draft), ai_agents:publish делает его рабочим (POST /v1/ai_agents/{ai_agent_id}/draft/publish). ai_agents:publish высокого риска, потому что меняет ответы, которые получают клиенты.

4. 4

   C. Подключение своего AI-бота к диалогам

   Scope: messages:read (средний), чтобы получать новые сообщения, messages:send (высокий), чтобы отвечать, conversations:assign (средний), чтобы передавать оператору. Если будете менять статус, conversations:write (средний), для заметок операторам notes:write (низкий).

   Бота можно подключить и одним адресом вебхука, без приложения: Как подключить свой бот к каналу (агент-бот). Путь ниже работает через приложение разработчика.

   1. На портале разработчика выберите для вебхука приложения тему message.created.
   2. Отвечайте только на сообщения клиента: data.direction должно быть incoming, а data.sender.type равно contact. message.created приходит и для Ваших собственных ответов, и для внутренних заметок: если отвечать на них, бот будет говорить сам с собой.
   3. Запишите ответ в диалог. В пути используйте data.conversation_number (номер из панели), а не data.conversation_id: последнее это внутренний ID.

   curl -X POST "https://api.clomni.ai/v1/conversations/1042/messages" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Idempotency-Key: 6f1c2a9e-3b7d-4f0a-9c55-0e8b1d2a7f41" \
     -H "Content-Type: application/json" \
     -d '{"content": "Ваш заказ доставят завтра."}'

   4. Когда бот не справляется, передайте диалог команде или оператору:

   curl -X POST "https://api.clomni.ai/v1/conversations/1042/assignments" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"team_id": 3}'

   5. При желании держите диалог в статусе pending, пока говорит бот, и переводите в open при передаче оператору (POST /v1/conversations/{conversation_id}/toggle_status, conversations:write). AI-агент Clomni и сценарии тоже держат диалог в pending, а диалог в pending не попадает в список «Открытые».

   Сообщение, отправленное через API, видно от имени владельца токена (во внутреннем приложении это пользователь, создавший приложение). Если хотите, чтобы ответы бота шли под отдельным именем, создайте приложение от отдельного пользователя-администратора для бота. Для POST /v1/conversations/{conversation_id}/messages лимит 60 запросов в минуту на токен.

5. 5

   Частые ошибки

   • 402 ai_credit_spent автоматически повторяется. Дождитесь пополнения кредита.
   • Пользователю что-то показывается и при handoff: true. Передайте вопрос человеку.
   • В вопрос попадают личные данные: номер карты, пароль. Не передавайте их.
   • Точные данные (цена, дата, номер заказа) показываются без проверки. Подтверждайте их из своей системы.
   • Новый ответ ждут сразу после добавления документа. Сначала его status должен стать готовым.
   • Бот использует в пути conversation_id из вебхука и получает 404 или пишет в чужой диалог. Используйте conversation_number.
   • Бот отвечает на своё же сообщение, и начинается цикл. Отвечайте только на incoming.
   • Вебхук приходит дважды, и бот отвечает дважды. Проверяйте id события и отправляйте с Idempotency-Key.

   Все endpoint AI: Scope и endpoint: AI-агенты, база знаний, центр помощи.