لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/bots/messages.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

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
ParameterbotId (path) Typenumber Requiredyes Default— DescriptionBot ID
ParameterdialogId Typestring Requiredyes Default— DescriptionDialog ID: a user ID as a string for direct messages, chatN — a chat with ID N, crm|TYPE|ID — a CRM record chat, where TYPE is the record type, for example DEAL, and ID is the record ID, sgN — a workgroup chat with ID N. Obtain IDs from users, chat creation, the corresponding CRM record, or workgroups. The format does not grant access to the dialog
Parameterfields.message Typestring Requiredyes Default— DescriptionMessage text (up to 20,000 characters). Supports BB-codes
Parameterfields.keyboard Typearray Requiredno Default— DescriptionInteractive keyboard
Parameterfields.attach Typearray/object Requiredno Default— DescriptionATTACH blocks with rich content
Parameterfields.replyId Typenumber Requiredno Default— DescriptionID of the message being quoted
Parameterfields.forwardIds Typeobject Requiredno Default— DescriptionMessages 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}
Parameterfields.system Typeboolean Requiredno Defaultfalse DescriptionSystem message (different style, no bot avatar)
Parameterfields.urlPreview Typeboolean Requiredno Defaulttrue DescriptionShow link previews in the text
Parameterfields.templateId Typestring Requiredno Default— DescriptionMessage 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionSend result
Fielddata.id Typenumber | null DescriptionID of the created message. null if the request has only forwardIds without its own text
Fielddata.uuidMap Typearray|object DescriptionUUID mapping when forwarding: {uuid: newMessageId}, where uuid is a key from forwardIds and newMessageId is the ID of the created copy. If forwardIds is omitted, this is an empty array []
Fielddata.failureMap Typearray|object DescriptionForwarding failures. An empty array [] if there are none

Response example

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

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
HTTP400 CodeINVALID_BOT_ID DescriptionbotId is not a number
HTTP400 CodeMESSAGE_REQUIRED DescriptionThe 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
HTTP404 CodeBOT_NOT_FOUND DescriptionNo bot found with this ID
HTTP403 CodeBOT_ACCESS_DENIED DescriptionThe bot belongs to a different API key
HTTP422 CodeBITRIX_ERROR Descriptionb24Code is MESSAGE_NOT_FOUND: a message from forwardIds does not exist, or the bot is not a member of the chat that contains it
HTTP422 CodeBITRIX_ERROR DescriptionAny other Bitrix24 error while sending. The error text is in message
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the imbot scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — see access rights
HTTP410 CodeBOT_DISABLED DescriptionThe bot is disabled and does not process API calls. To restore the bot, see Bot disabled
HTTP401 CodeTOKEN_MISSING DescriptionThe 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). A "flat" format is also accepted, where message, keyboard, attach, system, urlPreview, replyId, forwardIds, and templateId are passed at the top level next to dialogId — they are automatically wrapped in fields. Updating a message accepts the same two formats. 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