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

Get message

GET /v1/bots/:botId/messages/:messageId

Returns a message by its ID.

Bot type restriction. The method is available only for bots with type ∈ {personal, supervisor}. For a regular bot, Bitrix24 returns 422 BITRIX_ERROR: Method is available only for supervisor and personal bots. The type is set during registration via POST /v1/bots and cannot be changed without re-registration.

Parameters

Parameter Type Required Description
botId (path) number yes Bot ID
messageId (path) number yes Message ID

Examples

curl — personal key

Terminal 
curl https://vibecode.bitrix24.com/v1/bots/42/messages/1501 \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/bots/42/messages/1501 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/messages/1501', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/messages/1501', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
id number Message ID
chatId number Chat ID
authorId number Author ID
date string Send date (ISO 8601)
text string Message text
isSystem boolean System message
params object Additional message parameters

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 1501,
    "chatId": 123,
    "authorId": 1,
    "date": "2026-03-31T10:00:00+00:00",
    "text": "Hi, bot!",
    "isSystem": false,
    "params": {}
  }
}

Error response example

502 — the bot has no access to the message:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Access denied"
  }
}

Errors

HTTP Code Description
400 INVALID_BOT_ID botId is not a number
404 BOT_NOT_FOUND No bot found with this ID
403 BOT_ACCESS_DENIED The bot belongs to a different API key
502 BITRIX_ERROR Bitrix24 error (the bot has no access to the 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

Only personal and supervisor: the method is available only for bots of type personal and supervisor. For standard bots (bot), Bitrix24 returns an access error.

Typical scenario: the bot received an event with replyId and wants to read the original message the user replied to.

See also