## User events (ONIMV2*)

The common first step is the subscription: [`POST /v1/chats/events/subscribe`](/docs/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](/docs/bots/events/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`](/docs/chats/events/poll). Does not require a registered bot; suitable for agents acting on behalf of a user.

## Event list

| Event | Description |
|---------|---------|
| [ONIMV2MESSAGEADD](#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 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 |
|------|-----|---------|
| `message.id` | number | Message ID |
| `message.text` | string | Message text |
| `message.chatId` | number | Chat ID |
| `message.authorId` | number | Author ID. List: [`GET /v1/users`](/docs/entities/users) |
| `message.params` | object \| array | Message parameters. For a message without parameters, this is an empty array `[]` |
| `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 |
| `additionalMessages` | array | Related messages. In a reply event, the quoted message arrives here. In other events, it is an empty array |

## Known specifics

**Separate scope:** [subscribing](/docs/chats/events/subscribe) and [unsubscribing](/docs/chats/events/unsubscribe) require the `im` scope, not `imbot`.

## See also

- [Bot events](/docs/bots/events/bot-events)
- [Bot platform](/docs/bots)