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

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 или false Время последней активности. Приходит false, если активности не было

Массив 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": false,
        "phones": false
      }
    ]
  }
}

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

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 SCOPE_DENIED API-ключ не имеет скоупа imbot
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

Незаполненные значения кодируются по-разному. В data.users[] пустое поле приходит в одной из форм в зависимости от типа: пустая строка "" (lastName, avatar, birthday, website, email), false (даты lastActivityDate, mobileLastDate, desktopLastDate и список phones), пустой массив [] (departments). В data.bot незаданный backgroundId приходит как null. Перед использованием поля проверяйте его форму: new Date(false) и phones.map(...) на значении false дадут некорректный результат.

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

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