Para agentes de IA: markdown desta página — /docs-content-en/bots/messages.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Messages

Send messages on behalf of the bot, edit and delete them, read individual messages and mark conversations as read.

Scope: imbot | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Send message

POST /v1/bots/:botId/messages

Sends a message on behalf of the bot to the specified dialog. The text supports BB-codes; you can attach a keyboard and ATTACH blocks to the message.

Parameters

Parameter Type Required Default Description
botId (path) number yes — Bot ID
dialogId string yes — Dialog ID: numeric user ID for direct messages, chatXXX for group chats
fields.message string yes — Message text (up to 20,000 characters). Supports BB-codes
fields.keyboard array no — Interactive keyboard
fields.attach array/object no — ATTACH blocks with rich content
fields.replyId number no — ID of the message being quoted
fields.forwardIds object no — Messages to forward: {uuid: messageId}, where uuid is an arbitrary key string and messageId is the source message ID. Maximum 100. The response returns uuidMap as {uuid: newMessageId}
fields.system boolean no false System message (different style, no bot avatar)
fields.urlPreview boolean no true Show link previews in the text
fields.templateId string no — Message template UUID

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/bots/42/messages \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dialogId": "chat123",
    "fields": {
      "message": "[b]Task #42[/b]\nStatus: done",
      "keyboard": [
        {
          "TEXT": "Open task",
          "LINK": "https://portal.bitrix24.com/tasks/42/",
          "BG_COLOR_TOKEN": "primary"
        }
      ]
    }
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/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]Task #42[/b]\nStatus: done",
      "keyboard": [
        {
          "TEXT": "Open task",
          "LINK": "https://portal.bitrix24.com/tasks/42/",
          "BG_COLOR_TOKEN": "primary"
        }
      ]
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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]Task #42[/b]\nStatus: done',
      keyboard: [
        {
          TEXT: 'Open task',
          LINK: 'https://portal.bitrix24.com/tasks/42/',
          BG_COLOR_TOKEN: 'primary',
        },
      ],
    },
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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]Task #42[/b]\nStatus: done',
      keyboard: [
        {
          TEXT: 'Open task',
          LINK: 'https://portal.bitrix24.com/tasks/42/',
          BG_COLOR_TOKEN: 'primary',
        },
      ],
    },
  }),
})

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

Response fields

Field Type Description
id number ID of the created message
uuidMap array UUID mapping when forwarding (empty array when no forwardIds)

Response example

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

Error response example

404 — bot not found:

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

Errors

HTTP Code Description
400 INVALID_BOT_ID botId is not a number
400 MESSAGE_REQUIRED The body carries neither message nor any other content key. The error text lists the unrecognized body keys and points at where the text belongs. An empty attach array and an empty message string do not count as content
404 BOT_NOT_FOUND No bot found with this ID
403 BOT_ACCESS_DENIED The bot belongs to a different API key
422 BITRIX_ERROR Bitrix24 error while sending (error text in message)
403 SCOPE_DENIED The API key does not have the imbot scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Two body formats: the canonical format keeps the message content inside fields (as in the examples above). For convenience, a "flat" format is also accepted, where message, keyboard, attach, system, urlPreview, replyId, forwardIds, templateId are passed at the top level next to dialogId — they are automatically wrapped in fields. This is the same symmetry as for updating a message. If fields is passed, the flat keys are not applied (fields takes priority).

System messages: with system: true the message is shown without the bot avatar and has authorId = 0. Such messages cannot be updated or deleted by the bot.

Text is truncated: if the message is longer than 20,000 characters, Bitrix24 truncates the text and appends (...).

Forwarding (forwardIds): the format is an object {uuid: messageId}, where uuid is an arbitrary string and messageId is the source message ID. The bot can only forward messages from chats where it is a participant.

See also