## 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 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 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](/docs/chats/events/subscribe) and [unsubscribing](/docs/chats/events/unsubscribe) require the `im` scope, not `imbot`.

## See also

- [Get events](/docs/bots/events/polling)
- [Get user events](/docs/chats/events/poll)
- [Bot events](/docs/bots/events/bot-events)
- [Bot platform](/docs/bots)