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

Сообщения

Отправляйте сообщения от имени бота, редактируйте и удаляйте их, читайте отдельные сообщения и отмечайте переписку прочитанной.

Скоуп: imbot | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Отправить сообщение

POST /v1/bots/:botId/messages

Отправляет сообщение от имени бота в указанный диалог. Текст поддерживает BB-коды, к сообщению можно прикрепить клавиатуру и ATTACH-блоки.

Параметры

Параметр Тип Обяз. По умолч. Описание
botId (path) number да — ID бота
dialogId string да — ID диалога: строка с ID пользователя для личных сообщений, chatN — чат с ID N, crm|TYPE|ID — чат CRM-записи, где TYPE — тип записи, например DEAL, а ID — ID записи, sgN — чат рабочей группы с ID N. Идентификаторы берите из сотрудников, создания чата, соответствующей CRM-записи или рабочих групп. Формат не предоставляет прав доступа к диалогу
fields.message string да — Текст сообщения (до 20 000 символов). Поддерживает BB-коды
fields.keyboard array нет — Интерактивная клавиатура
fields.attach array/object нет — ATTACH-блоки с оформленным содержимым
fields.replyId number нет — ID сообщения для цитирования
fields.forwardIds object нет — Сообщения для пересылки: {uuid: messageId}, где uuid — произвольная строка-ключ, messageId — ID исходного сообщения. Максимум 100. В ответе uuidMap вернёт {uuid: newMessageId}
fields.system boolean нет false Системное сообщение (другой стиль, без аватара бота)
fields.urlPreview boolean нет true Показывать превью ссылок в тексте
fields.templateId string нет — UUID шаблона сообщения

Примеры

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/bots/42/messages \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dialogId": "chat123",
    "fields": {
      "message": "[b]Задача #42[/b]\nСтатус: выполнено",
      "keyboard": [
        {
          "TEXT": "Открыть задачу",
          "LINK": "https://portal.bitrix24.ru/tasks/42/",
          "BG_COLOR_TOKEN": "primary"
        }
      ]
    }
  }'

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/bots/42/messages \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dialogId": "chat123",
    "fields": {
      "message": "[b]Задача #42[/b]\nСтатус: выполнено",
      "keyboard": [
        {
          "TEXT": "Открыть задачу",
          "LINK": "https://portal.bitrix24.ru/tasks/42/",
          "BG_COLOR_TOKEN": "primary"
        }
      ]
    }
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/bots/42/messages', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dialogId: 'chat123',
    fields: {
      message: '[b]Задача #42[/b]\nСтатус: выполнено',
      keyboard: [
        {
          TEXT: 'Открыть задачу',
          LINK: 'https://portal.bitrix24.ru/tasks/42/',
          BG_COLOR_TOKEN: 'primary',
        },
      ],
    },
  }),
})

const { success, data } = await res.json()
console.log('Message ID:', data.id)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/bots/42/messages', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dialogId: 'chat123',
    fields: {
      message: '[b]Задача #42[/b]\nСтатус: выполнено',
      keyboard: [
        {
          TEXT: 'Открыть задачу',
          LINK: 'https://portal.bitrix24.ru/tasks/42/',
          BG_COLOR_TOKEN: 'primary',
        },
      ],
    },
  }),
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Результат отправки
data.id number | null ID созданного сообщения. null, если в запросе только forwardIds без собственного текста
data.uuidMap array|object Соответствие UUID при пересылке: {uuid: newMessageId}, где uuid — ключ из forwardIds, а newMessageId — ID созданной копии. Без forwardIds — пустой массив []
data.failureMap array|object Отказы пересылки. Пустой массив [], если отказов нет

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

JSON 
{
  "success": true,
  "data": {
    "id": 36357,
    "uuidMap": [],
    "failureMap": []
  }
}

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

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 не является числом
400 MESSAGE_REQUIRED В теле нет ни message, ни другого ключа содержимого. В тексте ошибки перечислены нераспознанные ключи тела и указано, куда положить текст. Пустой массив в attach и пустая строка в message содержимым не считаются
404 BOT_NOT_FOUND Бот с таким ID не найден
403 BOT_ACCESS_DENIED Бот принадлежит другому API-ключу
422 BITRIX_ERROR b24Code равен MESSAGE_NOT_FOUND: сообщения из forwardIds не существует или бот не участник чата, где оно лежит
422 BITRIX_ERROR Другая ошибка Битрикс24 при отправке. Текст ошибки — в message
403 SCOPE_DENIED API-ключ не имеет скоупа imbot
403 WRITE_BLOCKED_READONLY_KEY Ключ только для чтения — см. права доступа
410 BOT_DISABLED Бот отключён и не обрабатывает вызовы API. Как вернуть бота — Бот отключён
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

Два формата тела: канонический формат — содержимое сообщения внутри fields (как в примерах выше). Принимается и «плоский» формат, когда message, keyboard, attach, system, urlPreview, replyId, forwardIds, templateId передаются на верхнем уровне рядом с dialogId — они автоматически оборачиваются в fields. Это та же симметрия, что и у обновления сообщения. Если передан fields, плоские ключи не применяются (приоритет у fields).

Системные сообщения: при system: true сообщение отображается без аватара бота и имеет authorId = 0. Такие сообщения нельзя обновить или удалить через бота.

Текст обрезается: если сообщение длиннее 20 000 символов, Битрикс24 обрежет текст и добавит (...).

Пересылка: формат — объект {uuid: messageId}, где uuid — произвольная строка, а messageId — ID исходного сообщения. Бот может пересылать только сообщения из чатов, где он является участником.

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