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

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

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 Код Описание
HTTP400 КодINVALID_BOT_ID ОписаниеbotId не является числом
HTTP400 КодMESSAGE_REQUIRED ОписаниеВ теле нет ни message, ни другого ключа содержимого. В тексте ошибки перечислены нераспознанные ключи тела и указано, куда положить текст. Пустой массив в attach и пустая строка в message содержимым не считаются
HTTP404 КодBOT_NOT_FOUND ОписаниеБот с таким ID не найден
HTTP403 КодBOT_ACCESS_DENIED ОписаниеБот принадлежит другому API-ключу
HTTP422 КодBITRIX_ERROR Описаниеb24Code равен MESSAGE_NOT_FOUND: сообщения из forwardIds не существует или бот не участник чата, где оно лежит
HTTP422 КодBITRIX_ERROR ОписаниеДругая ошибка Битрикс24 при отправке. Текст ошибки — в message
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа imbot
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч только для чтения — см. права доступа
HTTP410 КодBOT_DISABLED ОписаниеБот отключён и не обрабатывает вызовы API. Как вернуть бота — Бот отключён
HTTP401 Код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 исходного сообщения. Бот может пересылать только сообщения из чатов, где он является участником.

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