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

User events (ONIMV2*)

The common first step is the subscription: POST /v1/chats/events/subscribe (scope im, not imbot). Without an active subscription, Bitrix24 does not register user events.

After that, events are fetched in one of two ways:

  1. Together with bot events — pass withUserEvents=true to bot event polling. Bot events (ONIMBOTV2*) and user events (ONIMV2*) arrive in the same events array.
  2. As a separate poll on behalf of the user — GET /v1/chats/events. Does not require a registered bot; suitable for agents acting on behalf of a user.

Event list

Event Description
EventONIMV2MESSAGEADD DescriptionNew message in a subscribed chat
EventONIMV2MESSAGEUPDATE DescriptionMessage edited
EventONIMV2MESSAGEDELETE DescriptionMessage deleted
EventONIMV2JOINCHAT DescriptionA participant joined the chat
EventONIMV2REACTIONCHANGE DescriptionReaction changed

ONIMV2MESSAGEADD

A new message in a subscribed chat. The message object has the same structure as in bot events. In the GET /v1/chats/events response, the keys inside message.params arrive in camelCase.

JSON 
{
  "eventId": 46,
  "type": "ONIMV2MESSAGEADD",
  "date": "2026-04-13T17:15:14+00:00",
  "data": {
    "message": {
      "id": 1520,
      "chatId": 123,
      "authorId": 17,
      "text": "Yes, I agree",
      "isSystem": false,
      "forward": null,
      "params": { "replyId": "1518" }
    },
    "chat": { "id": 123, "dialogId": "chat123", "type": "chat", "name": "Work chat" },
    "user": { "id": 17, "name": "John Brown", "type": "user" },
    "language": "en",
    "additionalMessages": [
      { "id": 1518, "chatId": 123, "authorId": 5, "text": "Can you confirm the meeting at 15:00?", "isSystem": false, "params": [] }
    ]
  }
}

data fields:

Field Type Description
Fieldmessage.id Typenumber DescriptionMessage ID
Fieldmessage.text Typestring DescriptionMessage text
Fieldmessage.chatId Typenumber DescriptionChat ID
Fieldmessage.authorId Typenumber DescriptionAuthor ID. List: GET /v1/users
Fieldmessage.params Typeobject | array DescriptionMessage parameters. For a message without parameters, this is an empty array []
Fieldmessage.params.replyId Typestring DescriptionReply to a message: the ID of the quoted message
Fieldchat.dialogId Typestring DescriptionDialog ID
Fielduser Typeobject DescriptionMessage author (id, name, etc.)
Fieldlanguage Typestring DescriptionUser interface language
FieldadditionalMessages Typearray DescriptionRelated messages. In a reply event, the quoted message arrives here. In other events, it is an empty array

Known specifics

Separate scope: subscribing and unsubscribing require the im scope, not imbot.

See also