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 add a keyboard and attachments to the message.

Parameters

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.

The v2 mode. format=v2 sends the message with im.v2.Chat.Message.send. The body stays flat — the same fields as below — and data carries the object { id, uuidMap, failureMap } instead of a number. The mode accepts only the fields in the table below, including those marked "the v2 mode only"; any other body field, uppercase forms (MESSAGE, REPLY_ID) and query parameters other than format are rejected with 400 INVALID_PARAMS, which names the field without repeating its value. In the v2 mode message must be a string. Under the Bitrix24 rule, the message must have content: non-empty text; whitespace-only text is accepted only with a non-empty attach; without message, a non-empty attach, stickerParams or block is required. Otherwise the route returns 400 MESSAGE_REQUIRED before any call to the Bitrix24 account. Forwarding goes through POST /v1/chats/:dialogId/forward: in the v2 mode the forwardIds field is rejected with an error that points to that endpoint, and botId with one that points to sending as a bot.

Request body fields

Message layout

• Text formatting — BB codes: bold, italic, links, color
• Keyboard — interactive buttons under the message
• Attachments — cards, tables, images, files

Examples

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

curl — personal key

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

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

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

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)

curl — the v2 mode

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

Response fields

Response example

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

Error response example

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

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

Errors

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.

The v2 mode and Bitrix24 errors. In the v2 mode the Bitrix24 error code arrives in error.b24Code.

See also

• Messages
• Edit a message
• Delete a message