# List reactions on a message

`GET /reaction.list`

## Description

List reactions on a specific message, grouped by emoji (Slack-style
`{name, count, users}`). Poll votes are returned separately in `pollVotes`
rather than folded into `reactions`.

`users` contains visible principal IDs only. Unknown or unauthorized actors
are omitted, and `count` is recomputed from the returned IDs. Hydrate them
with `user.list?ids`; these arrays do not carry inline type fields.

To list reactions on a thread reply, provide the `threadTimestamp` of the
parent message and the `timestamp` of the specific reply.

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

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `chatId` | query | string | Yes | The chat containing the message. |
| `timestamp` | query | integer | Yes | Timestamp of the message (Unix microseconds). |
| `threadTimestamp` | query | integer | No | Timestamp of the parent thread message (Unix microseconds), if listing reactions on a thread reply. |

## Responses

### 200 - Reactions retrieved successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ok` | "true" | No |  |
| `chatId` | string | Yes | The chat containing the message. |
| `timestamp` | integer | Yes | Timestamp of the message (Unix microseconds). |
| `threadTimestamp` | integer | No | Parent thread timestamp when the message is a thread reply. |
| `reactions` | Reaction[] | Yes | Emoji reactions, one entry per distinct reaction name. |
| `pollVotes` | object[] | Yes | Poll option votes when the message is a poll. Not included among `reactions`.  |

**Reaction** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | Yes | Reaction shortcode without surrounding colons (e.g. `thumbs_up`, `wave`, `heart`). Matches the `name` accepted by `reaction.add` / `reaction.remove` and delivered on the `chat.reaction` webhook.  |
| `count` | integer | Yes | Number of users who added this reaction. |
| `users` | string[] | Yes | Visible principal IDs of reactors. Hydrate with `user.list?ids`; unauthorized IDs are omitted and `count` reflects this array. |

**pollVotes** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `optionId` | string | Yes | Poll option identifier. |
| `text` | string | No | Option display text (omitted if the option no longer resolves). |
| `count` | integer | Yes |  |
| `users` | string[] | Yes |  |


#### Example Response

```json
{
  "ok": true,
  "chatId": "7be17589-4b9a-4524-bddb-ce60abea08e6",
  "timestamp": 1755723832718034,
  "reactions": [
    {
      "name": "thumbs_up",
      "count": 2,
      "users": [
        "709b8a57-70bc-427a-b6f0-b16ba5297f8c",
        "f589a8cb-78ac-493e-8719-0fa8a22f65e0"
      ]
    },
    {
      "name": "heart",
      "count": 1,
      "users": [
        "af6663d5-0f37-4105-95df-4fea20ef7c7c"
      ]
    }
  ],
  "pollVotes": []
}
```

### 400 - Bad request. Common causes:
- Message not found
- Invalid cursor or parameters


### 401 - Presented invalid authentication credentials.

### 403 - Missing `chat:history` scope, or no access to this chat.

### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

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