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 to bots whose type is personal or supervisor. The type is set during registration via POST /v1/bots and cannot be changed without re-registration.

Parameters

Parameter Type Required Description
ParameterbotId (path) Typenumber Requiredyes DescriptionBot ID. List: GET /v1/bots
ParametermessageId (path) Typenumber Requiredyes DescriptionMessage ID. It arrives in the message.id field of bot events and in the data.id field of the POST /v1/bots/:botId/messages response

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.message.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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.message Typeobject DescriptionMessage
Fielddata.message.id Typenumber DescriptionMessage ID
Fielddata.message.chatId Typenumber DescriptionChat ID
Fielddata.message.chat_id Typenumber DescriptionChat ID, the same value as data.message.chatId
Fielddata.message.authorId Typenumber DescriptionAuthor ID. For a bot message — the bot ID
Fielddata.message.author_id Typenumber DescriptionAuthor ID, the same value as data.message.authorId
Fielddata.message.date Typestring DescriptionDate sent in ISO 8601 format
Fielddata.message.text Typestring DescriptionMessage text
Fielddata.message.isSystem Typeboolean DescriptionWhether the message is a system message
Fielddata.message.uuid Typestring | null DescriptionMessage UUID. null if no UUID is set
Fielddata.message.forward Typeobject | null DescriptionForwarding data. null if the message was not forwarded
Fielddata.message.params Typeobject | array DescriptionAdditional message parameters. An empty array [] if there are no parameters
Fielddata.message.viewedByOthers Typeboolean DescriptionWhether other chat participants have read the message
Fielddata.message.block Typeobject | null Descriptionnull for a bot text message
Fielddata.user Typeobject DescriptionMessage author
Fielddata.user.id Typenumber DescriptionUser ID
Fielddata.user.active Typeboolean DescriptionWhether the account is active
Fielddata.user.name Typestring DescriptionFull name
Fielddata.user.firstName Typestring DescriptionFirst name
Fielddata.user.lastName Typestring DescriptionLast name. An empty string if not set
Fielddata.user.workPosition Typestring DescriptionJob title
Fielddata.user.color Typestring DescriptionAvatar color in HEX format, for example #58cc47
Fielddata.user.avatar Typestring DescriptionAvatar URL. An empty string if no avatar is set
Fielddata.user.gender Typestring DescriptionGender: M — male, F — female, an empty string — not specified
Fielddata.user.birthday Typestring DescriptionDate of birth. An empty string if not specified
Fielddata.user.extranet Typeboolean DescriptionWhether the user is external, type extranet
Fielddata.user.bot Typeboolean DescriptionWhether the user is a bot
Fielddata.user.connector Typeboolean DescriptionOpen Channels user
Fielddata.user.externalAuthId Typestring DescriptionExternal authentication code of the user account. For a bot — bot
Fielddata.user.internalAccount Typeboolean DescriptionWhether this is an internal user of the Bitrix24 account. For a bot — false
Fielddata.user.intranetUser Typeboolean DescriptionWhether the user is an employee of the Bitrix24 account. For a bot — false
Fielddata.user.status Typestring DescriptionStatus: online, away, dnd
Fielddata.user.idle Typeboolean DescriptionUser idle flag
Fielddata.user.lastActivityDate Typestring | false DescriptionTime of last activity in ISO 8601 format. false if there was no activity
Fielddata.user.mobileLastDate Typestring | false DescriptionTime of the last sign-in from the mobile app. false if there was none
Fielddata.user.desktopLastDate Typestring | false DescriptionTime of the last sign-in from the desktop app. false if there was none
Fielddata.user.absent Typeboolean | string Descriptionfalse or the end date of the absence
Fielddata.user.departments Typenumber[] DescriptionDepartment IDs. List: GET /v1/departments. An empty array for a bot
Fielddata.user.phones Typeobject | false DescriptionPhone numbers. false if there are none
Fielddata.user.type Typestring DescriptionUser type: user, bot, extranet
Fielddata.user.website Typestring DescriptionWebsite. An empty string if not specified
Fielddata.user.email Typestring DescriptionEmail address. An empty string if not specified

Response example

JSON 
{
  "success": true,
  "data": {
    "message": {
      "id": 1501,
      "chatId": 123,
      "chat_id": 123,
      "authorId": 42,
      "author_id": 42,
      "date": "2026-10-21T14:00:05+00:00",
      "text": "Test message",
      "isSystem": false,
      "uuid": null,
      "forward": null,
      "params": [],
      "viewedByOthers": false,
      "block": null
    },
    "user": {
      "id": 42,
      "active": true,
      "name": "Test bot",
      "firstName": "Test bot",
      "lastName": "",
      "workPosition": "Chatbot",
      "color": "#58cc47",
      "avatar": "",
      "gender": "M",
      "birthday": "",
      "extranet": false,
      "bot": true,
      "connector": false,
      "externalAuthId": "bot",
      "internalAccount": false,
      "intranetUser": false,
      "status": "online",
      "idle": false,
      "lastActivityDate": false,
      "mobileLastDate": false,
      "desktopLastDate": false,
      "absent": false,
      "departments": [],
      "phones": false,
      "type": "bot",
      "website": "",
      "email": ""
    }
  }
}

Error response example

422 — the bot type is neither personal nor supervisor:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Method is available only for supervisor and personal bots",
    "b24Code": "BOT_TYPE_NOT_ALLOWED"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_BOT_ID DescriptionbotId is not a number
HTTP400 CodeINVALID_PARAMS DescriptionmessageId in the path must be a positive integer from 1 to 9007199254740991, without a sign, leading zeros, fraction, exponent or whitespace. Rejected before calling Bitrix24
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 (error.b24Code: BOT_TYPE_NOT_ALLOWED) DescriptionThe bot type is neither personal nor supervisor
HTTP422 CodeBITRIX_ERROR (error.b24Code: MESSAGE_NOT_FOUND) DescriptionNo message with this messageId exists
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access to the message. This is the response for a message from a chat the bot is not a member of
HTTP422 CodeBITRIX_ERROR DescriptionAnother Bitrix24 error, text in message
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the imbot scope
HTTP410 CodeBOT_DISABLED DescriptionThe bot is disabled and does not process API calls. How to restore it — Bot disabled
HTTP401 CodeTOKEN_MISSING DescriptionThe 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