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

Scope: imbot

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

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

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

Для быстрого старта создайте входящий вебхук в интерфейсе Битрикс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
          }'

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

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