Для AI-агентов: markdown этой страницы — /docs-content/bots/management/get.md индекс документации — /llms.txt

Получить бота

GET /v1/bots/:botId

Получает актуальные данные о боте из Битрикс24 (живой запрос, не из кэша).

Параметры

Параметр Тип Обяз. Описание
botId number да ID бота (path-параметр)

Примеры

curl — личный ключ

Terminal 
curl https://vibecode.bitrix24.tech/v1/bots/42 \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl https://vibecode.bitrix24.tech/v1/bots/42 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/bots/42', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Бот:', data)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/bots/42', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Поля ответа

Ответ содержит два объекта: data.bot — параметры бота, data.users — массив пользователей Битрикс24, представляющих бота. В массиве один элемент — учётная запись бота-пользователя.

Поле Тип Описание
data.bot.id number ID бота на портале Битрикс24
data.bot.code string Уникальный код бота
data.bot.type string Тип бота: bot, personal, supervisor, openline
data.bot.isHidden boolean Скрыт из списка контактов
data.bot.isSupportOpenline boolean Поддержка открытых линий
data.bot.isReactionsEnabled boolean Разрешены реакции на сообщения
data.bot.backgroundId string Фон чата. Приходит null, когда не задан
data.bot.language string Язык бота, например ru
data.bot.moduleId string Модуль, зарегистрировавший бота, например rest
data.bot.eventMode string Режим событий: fetch или webhook
data.bot.countMessage number Счётчик сообщений
data.bot.countCommand number Счётчик команд
data.bot.countChat number Счётчик чатов
data.bot.countUser number Счётчик пользователей
data.users[].id number ID пользователя-бота. Совпадает с data.bot.id
data.users[].name string Полное имя
data.users[].firstName string Имя
data.users[].lastName string Фамилия. Пустая строка, если не задана
data.users[].workPosition string Должность
data.users[].color string Цвет аватара в формате HEX, например #29619b
data.users[].avatar string URL аватара. Пустая строка, если не задан
data.users[].gender string Пол: M или F
data.users[].active boolean Активен ли пользователь
data.users[].bot boolean Признак бота
data.users[].departments array Подразделения. Пустой массив, если их нет
data.users[].lastActivityDate string | null Время последней активности. null, если активности не было

Массив data.users несёт и другие стандартные поля пользователя Битрикс24 — birthday, phones, website, email, status, mobileLastDate, desktopLastDate. О том, как кодируются незаполненные значения, — в разделе «Известные особенности».

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "bot": {
      "id": 42,
      "code": "support_bot",
      "type": "bot",
      "isHidden": false,
      "isSupportOpenline": false,
      "isReactionsEnabled": true,
      "backgroundId": null,
      "language": "ru",
      "moduleId": "rest",
      "eventMode": "fetch",
      "countMessage": 0,
      "countCommand": 0,
      "countChat": 0,
      "countUser": 0
    },
    "users": [
      {
        "id": 42,
        "active": true,
        "name": "Техподдержка",
        "firstName": "Техподдержка",
        "lastName": "",
        "workPosition": "Помощник по техническим вопросам",
        "color": "#29619b",
        "avatar": "",
        "gender": "M",
        "bot": true,
        "departments": [],
        "lastActivityDate": null,
        "phones": []
      }
    ]
  }
}

Пример ответа при ошибке

404 — бот не найден:

JSON 
{
  "success": false,
  "error": {
    "code": "BOT_NOT_FOUND",
    "message": "Bot 999 not found. Register it first via POST /v1/bots."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_BOT_ID botId не является числом
404 BOT_NOT_FOUND Бот не найден — зарегистрируйте через POST /v1/bots
403 BOT_ACCESS_DENIED Бот принадлежит другому API-ключу. Вернуть управление — Восстановление доступа к боту
403 B24_MARKET_SUBSCRIPTION_REQUIRED Бот припаркован из-за неактивной подписки Маркетплейса; порядок восстановления — в разделе ошибок подписки
403 SCOPE_DENIED API-ключ не имеет скоупа imbot
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Незаполненные значения приходят в предсказуемой форме. Пустые даты lastActivityDate, mobileLastDate и desktopLastDate платформа приводит к null, а незаполненный список phones — к пустому массиву, поэтому phones.map(...) работает без предварительной проверки. Пустые строковые поля lastName, avatar, birthday, website, email приходят пустой строкой, departments — пустым массивом, а незаданный backgroundId в data.bot — null.

Цвет аватара возвращается в HEX. При записи color принимает имя из палитры (AZURE, MINT, …), но в ответе data.users[].color приходит уже как HEX-строка, например #29619b. Прочитать обратно записанное имя из палитры нельзя.

Смотрите также