метод REST scope: imbot

imbot.v2.Bot.register

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

Кто может выполнять: авторизованный пользователь

Описание

Метод imbot.v2.Bot.register регистрирует нового чат-бота.

Метод идемпотентен: повторный вызов с тем же fields.code от того же приложения возвращает существующего бота без обновления данных. Для обновления используйте imbot.v2.Bot.update.

Если бот работает в составе приложения, события не будут отправляться в приложение, пока установка не завершена. Проверьте установку приложения

Параметры

fields object обязательный

Объект с параметрами бота. Описание параметров — ниже

Параметр fields

code string обязательный

Уникальный код бота в рамках приложения

botToken string необязательный

Уникальный токен авторизации бота. Обязателен при авторизации через вебхук, не нужен для OAuth.

Передайте уникальный botToken — этот ключ будет привязан к чат-боту и потребуется для всех последующих вызовов imbot.v2* через вебхук.

Максимальная длина — 40 символов.

С 06.08.2026 токены длиннее 40 символов будут отклоняться с ошибкой BOT_TOKEN_INVALID_LENGTH. Если вы используете длинный токен — обновите его через imbot.v2.Bot.update до этой даты.

properties object обязательный

Свойства профиля бота. Описание параметров — ниже

type string необязательный

Тип бота. Описание типов и их поведения — Типы ботов.

Значение по умолчанию: bot

eventMode string необязательный

Режим доставки событий.

Допустимые значения:
- fetch — бот забирает события через imbot.v2.Event.get
- webhook — события отправляются POST-запросом на webhookUrl

Значение по умолчанию: fetch

webhookUrl string необязательный

URL обработчика событий бота. Обязателен при eventMode = webhook

isHidden boolean необязательный

Скрытый бот. Допустимые значения: true, false. По умолчанию false

isReactionsEnabled boolean необязательный

Включить поддержку реакций. Допустимые значения: true, false. По умолчанию true

isSupportOpenline boolean необязательный

Включить поддержку Открытых линий. Допустимые значения: true, false. По умолчанию false

backgroundId string необязательный

Фон чата бота. По умолчанию null — используется фон из настроек пользователя. Доступные значения — в таблице фонов. Невалидное значение нормализуется в null

Параметр properties

name string обязательный

Имя бота. Отображается в списке чатов и заголовке диалога

lastName string необязательный

Фамилия бота

workPosition string необязательный

Должность бота (отображается в профиле)

color string необязательный

Цвет аватара, доступные цвета.
Если не указан — назначается автоматически

gender string необязательный

Пол. Допустимые значения: M, F

avatar file необязательный

Аватар. Передавайте строку Base64 без префикса data:*/*;base64,.

Как подготовить данные: Как загружать файлы

Доступные фоны

ID необязательный

Тема

azure необязательный

dark

mint необязательный

dark

steel необязательный

dark

slate необязательный

dark

teal необязательный

dark

cornflower необязательный

dark

sky необязательный

light

peach необязательный

light

frost необязательный

light

Примеры запроса

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "fields":{
      "code":"support_bot",
      "botToken":"my_bot_token",
      "properties":{"name":"Support Bot","workPosition":"AI Assistant"},
      "type":"bot",
      "eventMode":"fetch"
    }
  }' \
  https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/imbot.v2.Bot.register

Ответ

HTTP-статус: 200

{
    "result": {
        "bot": {
            "id": 456,
            "code": "support_bot",
            "type": "bot",
            "isHidden": false,
            "isSupportOpenline": false,
            "isReactionsEnabled": true,
            "backgroundId": null,
            "language": "en",
            "moduleId": "rest",
            "eventMode": "fetch",
            "countMessage": 0,
            "countCommand": 0,
            "countChat": 0,
            "countUser": 0
        },
        "users": [
            {
                "id": 456,
                "active": true,
                "name": "Support Bot",
                "firstName": "Support",
                "lastName": "Bot",
                "workPosition": "AI Assistant",
                "color": "#df532d",
                "avatar": "",
                "gender": "M",
                "birthday": "",
                "extranet": false,
                "bot": true,
                "connector": false,
                "externalAuthId": "bot",
                "status": "online",
                "idle": false,
                "lastActivityDate": "2025-01-15T10:30:00+03:00",
                "absent": false,
                "departments": [1],
                "phones": false,
                "type": "bot"
            }
        ]
    },
    "time": {
        "start": 1728626400.123,
        "finish": 1728626400.234,
        "duration": 0.111,
        "processing": 0.045,
        "date_start": "2024-10-11T10:00:00+03:00",
        "date_finish": "2024-10-11T10:00:00+03:00"
    }
}

Обработка ошибок

HTTP-статус: 400

{
    "error": "BOT_CODE_REQUIRED",
    "error_description": "Bot code is required"
}
Код Описание Значение
BOT_TOKEN_NOT_SPECIFIED Bot token is not specified Не указан fields.botToken. Обязателен при авторизации через вебхук
BOT_CODE_REQUIRED Bot code is required Не указан код бота (fields.code)
BOT_PROPERTIES_REQUIRED Bot properties are required Не указаны свойства бота (имя)
BOT_CODE_ALREADY_TAKEN Bot code is already taken Код бота уже занят другим приложением
BOT_INVALID_TYPE Invalid bot type Невалидный тип бота. Допустимые значения: bot, network, openline, supervisor, personal
BOT_INVALID_EVENT_MODE Invalid event mode Невалидный режим доставки событий. Допустимые значения: fetch, webhook
BOT_WEBHOOK_URL_REQUIRED Webhook URL is required Не указан fields.webhookUrl при fields.eventMode = webhook
BOT_REGISTER_FAILED Bot registration failed Ошибка регистрации бота
BOT_INVALID_CALLBACK Invalid callback URL Невалидный URL обработчика
BOT_LIMIT_EXCEEDED Bot limit exceeded Превышен лимит ботов приложения (100 ботов)
BOT_AVATAR_INCORRECT_TYPE Avatar must be an image Аватар должен быть изображением (image/*)
BOT_AVATAR_INCORRECT_SIZE Avatar exceeds maximum size Размер аватара превышает максимум (5000×5000 px)

Что будем искать? Например,Продвижение

Этот сайт использует куки-файлы. Оставаясь на сайте, Вы соглашаетесь на их использование. Для получения дополнительной информации, пожалуйста, ознакомьтесь с политикой в отношении персональных данных.