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 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
ONIMV2MESSAGEADD New message in a subscribed chat
ONIMV2MESSAGEUPDATE Message edited
ONIMV2MESSAGEDELETE Message deleted
ONIMV2JOINCHAT A participant joined the chat
ONIMV2REACTIONCHANGE Reaction changed

ONIMV2MESSAGEADD

A new message in a subscribed chat. The message object has the same composition as bot events, but the keys inside params are 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"
  }
}

data fields:

Field Type Description
message.id number Message ID
message.text string Message text
message.authorId number Author ID
message.params.replyId string Reply to a message: the ID of the quoted message
chat.dialogId string Dialog ID
user object Message author (id, name, etc.)
language string User interface language

Known specifics

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

See also