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 the other types — bot and openline — the response is 422 with code BITRIX_ERROR, and the machine-readable reason code is returned in the error.b24Code field with the value BOT_TYPE_NOT_ALLOWED. 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 Sent 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

422 — the bot type is neither personal nor supervisor:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Bot type not allowed",
    "b24Code": "BOT_TYPE_NOT_ALLOWED"
  }
}

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
422 BITRIX_ERROR (error.b24Code: BOT_TYPE_NOT_ALLOWED) The bot type is neither personal nor supervisor
422 BITRIX_ERROR Another Bitrix24 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

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

See also