Чат-боты 2.0: быстрый старт

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: imbot

Кто может выполнять методы: владелец зарегистрированного бота

Краткий сценарий запуска чат-бота на imbot.v2: создание вебхука, регистрация бота, получение событий, отправка сообщений и работа с файлами.

Перед началом проверьте Журнал изменений API imbot.v2. В нем собраны новые возможности, исправления и breaking changes, а записи расположены от новых к старым.

Создание входящего вебхука

Для быстрого старта создайте входящий вебхук в интерфейсе Битрикс24:

  1. Перейдите в Разработчикам -> Другое -> Входящий вебхук.
  2. В правах выберите scope imbot.
  3. Сохраните и скопируйте URL вебхука.

Формат URL:

https://{portal}/rest/{user_id}/{webhook_token}/

Типичный сценарий

1. Зарегистрировать бота

Используйте метод imbot.v2.Bot.register, чтобы создать бота и задать его основные свойства.

curl -X POST 'https://example.bitrix24.ru/rest/1/webhook_token/imbot.v2.Bot.register' \
          -H 'Content-Type: application/json' \
          -d '{
            "botToken": "my_secret_token_123",
            "fields": {
              "code": "support_bot",
              "properties": {"name": "Support Bot", "workPosition": "AI Assistant"},
              "eventMode": "fetch"
            }
          }'

2. Получить события (fetch-режим)

Используйте imbot.v2.Event.get, чтобы забрать очередь событий для зарегистрированного бота.

curl -X POST 'https://example.bitrix24.ru/rest/1/webhook_token/imbot.v2.Event.get' \
          -H 'Content-Type: application/json' \
          -d '{
            "botId": 456,
            "botToken": "my_secret_token_123",
            "limit": 50
          }'

3. Ответить в чат

Используйте imbot.v2.Chat.Message.send, чтобы отправить ответ в диалог.

curl -X POST 'https://example.bitrix24.ru/rest/1/webhook_token/imbot.v2.Chat.Message.send' \
          -H 'Content-Type: application/json' \
          -d '{
            "botId": 456,
            "botToken": "my_secret_token_123",
            "dialogId": "chat5",
            "fields": {"message": "Hello! How can I help you?"}
          }'

4. Прочитать сообщение по replyId (только supervisor/personal)

Если пользователь ответил на сообщение бота, получите исходное сообщение через imbot.v2.Chat.Message.get.

curl -X POST 'https://example.bitrix24.ru/rest/1/webhook_token/imbot.v2.Chat.Message.get' \
          -H 'Content-Type: application/json' \
          -d '{
            "botId": 456,
            "botToken": "my_secret_token_123",
            "messageId": 789
          }'

5. Загрузить файл в чат

Используйте imbot.v2.File.upload, чтобы отправить файл в чат от имени бота.

curl -X POST 'https://example.bitrix24.ru/rest/1/webhook_token/imbot.v2.File.upload' \
          -H 'Content-Type: application/json' \
          -d '{
            "botId": 456,
            "botToken": "my_secret_token_123",
            "dialogId": "chat5",
            "fields": {"name": "report.txt", "content": "SGVsbG8gV29ybGQh", "message": "Here is the report"}
          }'

6. Получить ссылку на скачивание файла

Используйте imbot.v2.File.download, чтобы получить URL для скачивания файла.

curl -X POST 'https://example.bitrix24.ru/rest/1/webhook_token/imbot.v2.File.download' \
          -H 'Content-Type: application/json' \
          -d '{
            "botId": 456,
            "botToken": "my_secret_token_123",
            "dialogId": "chat5",
            "fileId": 138
          }'

Дополнительные возможности сообщений

При отправке сообщений через imbot.v2.Chat.Message.send доступны:

Ревизии API и совместимость

Битрикс24 облако и коробочные версии могут иметь разные ревизии API. Чтобы узнать, какая ревизия установлена на конкретном портале, используйте imbot.v2.Revision.get.

Новые возможности, исправления и изменения с потерей обратной совместимости собраны на странице Журнал изменений API imbot.v2. Если интеграция уже работает в проде, эту страницу стоит проверять в первую очередь.

Порядок изучения

  1. Журнал изменений API imbot.v2
  2. imbot.v2.Bot.register
  3. imbot.v2.Event.get
  4. События imbot.v2
  5. imbot.v2.Chat.Message.send
  6. imbot.v2.Chat.Message.get и imbot.v2.Chat.Message.getContext
  7. imbot.v2.Command.register
  8. imbot.v2.File.upload и imbot.v2.File.download
  9. imbot.v2.Chat.add

Продолжите изучение

Предыдущая
Обзор методов
Следующая
Объекты и поля