For AI agents: markdown of this page — /docs-content-en/chats/messages/send.md documentation index — /llms.txt

Send a message

POST /v1/chats/:dialogId/messages

Sends a text message to the given dialog. The text supports BB codes for formatting; you can attach a keyboard and attachments to the message.

Parameters

Parameter Type Req. Description
dialogId (path) string yes Dialog identifier. Numeric user ID for personal messages, list — GET /v1/users. chatXXX for group chats. Accepts the value me — see below

The me alias. Instead of a numeric user ID you can pass the string me: the dialog opens with the current key owner. Learn more in Chats and messages.

Request body fields

Field Type Req. Description
message string yes Message text (up to 20,000 characters). Supports BB codes
attach array no Attachments: cards, tables, images, files, dividers
keyboard array no Interactive buttons under the message
menu array no Message context menu items
replyId number no ID of the quoted message
system boolean no When true — system style (no avatar, authorId = 0)
urlPreview boolean no When false, disables link preview in the text

Message layout

Examples

In the examples, dialogId is 42 — the recipient's numeric user ID.

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/42/messages \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Invoice issued. Please await confirmation."
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/42/messages \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Invoice issued. Please await confirmation."
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/42/messages', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Invoice issued. Please await confirmation.',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/42/messages', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Invoice issued. Please await confirmation.',
  }),
})

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

Response fields

Field Type Description
success boolean Always true on success
data number ID of the created message

Response example

JSON 
{
  "success": true,
  "data": 36889
}

Error response example

422 — Bitrix24 returned an error (dialog not found or unavailable):

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Dialog not found"
  }
}

Errors

HTTP Code Description
400 MESSAGE_REQUIRED The message field is empty and there is no attach block. A common cause is text passed under an unknown field name, for example text. message lists the unrecognized fields
422 BITRIX_ERROR Bitrix24 returned an error — dialog not found or unavailable (details in message)
502 ME_ALIAS_RESOLUTION_FAILED dialogId=me — failed to resolve the current user's ID
403 SCOPE_DENIED The key does not have the im scope
401 TOKEN_MISSING The key has no configured tokens

Full list of common API errors — Errors.

Known specifics

System messages. When system: true, the message is shown without the sender's avatar and the authorId field equals 0. Such a message cannot be edited or deleted via the API.

Long text truncation. Text longer than 20,000 characters is truncated to 20,000, with (...) appended at the end.

See also