# Reaction added or removed

**Event:** `chat.reaction`

## Description

A reaction was added to or removed from a chat message the app can see.

**Event name:** `chat.reaction`

**Required scope:** `chat:history`

Delivered inside the standard [event envelope](/docs/webhooks/webhooks#event-envelope);
the schema below shows the full delivery body with this event's payload
under `data`.

Like `chat.message`, this is delivered for any message in a chat the app
participates in or can see (Slack `reaction_added` / `reaction_removed`
parity) — not only the app's own messages. The reacted message's author is
in `messageAuthorId`, so an app can filter to reactions on its own
messages.

**One event is delivered per reaction change**: `action` says whether the
reaction was added or removed, `name` is the single reaction that changed,
and `userId` is the user who changed it. There is no batching or
debouncing — an add followed by a remove delivers two events.

Delivery is at-least-once; use the envelope's `eventId` to deduplicate
retries. Event ordering is not guaranteed — use the envelope's
`timestamp` when reconstructing a sequence. To fetch a message's current
reaction set, call [`/reaction.list`](/docs/api/reaction-list).

**Filter options:**
- `names`: array of reaction names (e.g. `["wave", "heart"]`) — only
  receive events where the changed reaction is one of these names.

**Note:** the legacy v0 `chat:message:reaction` event instead delivers the
message's full reaction snapshot, debounced per message, with tagged IDs
(`chat` / `recipient` / `messageSender`) — and its filter key is `codes`.

Both actors are typed inline. `userType` describes `userId`, while
`messageAuthorType` describes `messageAuthorId`; each equals
[`user.info.type`](/docs/api/user-info) under the same credentials.

These fields are additive on both supported webhook versions. Baseline
(`2026-06-01`) includes them in the bare payload; Latest nests them under
`data`:

```json
{ "userId": "ad1e9cc0-...", "userType": "user", "messageAuthorId": "709b8a57-...", "messageAuthorType": "bot" }
{ "type": "chat.reaction", "data": { "userId": "ad1e9cc0-...", "userType": "user", "messageAuthorId": "709b8a57-...", "messageAuthorType": "bot" } }
```

A malformed event whose actor or message author cannot be resolved is not
delivered as a partially typed payload.

## Webhook Payload


### Example Payload

```json
{
  "type": "chat.reaction",
  "eventId": "0197f9a2-1a51-7aa1-8b2c-3d4e5f6a7b8c",
  "timestamp": "2025-06-02T23:21:00.000000Z",
  "apiVersion": "2026-07-07",
  "data": {
    "action": "added",
    "chatId": "8f3b9c2e-1a4d-4e7b-9c0a-2b6d1f5e3a7c",
    "chatType": "group",
    "messageId": "16933dd4-6e4c-4acf-9af1-d1972f9b4d34",
    "messageTimestamp": 1748906400000000,
    "userId": "ad1e9cc0-0ffd-47e5-895c-2630a73327b4",
    "userType": "user",
    "messageAuthorId": "709b8a57-70bc-427a-b6f0-b16ba5297f8c",
    "messageAuthorType": "bot",
    "name": "wave",
    "emojiText": "👋"
  }
}
```

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/webhooks/chat-reaction*