# Get Chat Messages

`GET /chat.history`

## Description

List messages in a chat, filtered by date range (after/before).

The ordering of results depends on `ascending` and `after`:

- `ascending=true` sorts in forward chronological order (oldest first).
  `ascending=false` sorts in reverse chronological order (newest first),
  even when `after` is specified.

- When `ascending` is omitted and `after` is not specified, the most recent
  messages are returned in reverse chronological order. This is equivalent
  to specifying `before` as NOW and leaving `after` unspecified.

- When `ascending` is omitted and `after` is specified, the results are
  sorted in forward chronological order.

Send the same `ascending` value on every page. The cursor marks where to
resume, not which direction to sort.

Either dates or datetimes may be specified. Dates are interpreted in UTC.

Note that the API operates in UTC with respect to the date range filter.

**Access:** Organization and Personal. In Personal mode, only chats where the authenticated user is a participant are accessible.

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

---

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

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `chat` | query | string | Yes | The chat address to fetch information for. |
| `threadTimestamp` | query | number | No | Read replies of the message with this timestamp. |
| `after` | query | string | No | The datetime to begin listing transcripts (YYYY-MM-DD or RFC-3339). Defaults to "no filter".  |
| `before` | query | string | No | The datetime until which to list transcripts (YYYY-MM-DD or RFC-3339). Defaults to "now".  |
| `ascending` | query | boolean | No | `true` sorts oldest-first. `false` sorts newest-first, even when `after` is set. When omitted, results are oldest-first if `after` is set and newest-first otherwise. Send the same value on every page; |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Do not construct cursors manually. |
| `limit` | query | integer | No | Number of messages to return (default 10, max 200). |

## Responses

### 200 - Info retrieved successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `chat` | TaggedUUID | Yes |  |
| `nextCursor` | string | No | An opaque cursor to fetch the next page of results |
| `messages` | ChatMessage[] | Yes |  |

**TaggedUUID**:

A UUID prefixed by a tag identifying the specific type of object
**ChatMessage** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | "message" | Yes | Message type identifier |
| `contentType` | "text" | "block" | "voice" | "poll" | Yes | Type of message content |
| `sender` | TaggedUUID | Yes | The message sender's Address ID |
| `chat` | TaggedUUID | Yes | ID of the chat in which the message was sent |
| `threadTimestamp` | integer | No | Key of the message that this is a reply to. Omitted if this is not a reply. |
| `timestamp` | integer | Yes | Key of the message within a chat, as Unix microseconds |
| `text` | string | No | Text of the message, formatted as github-flavored markdown |
| `items` | ChatItem[] | No | Items attached to this message |
| `blocks` | object[] | No | Block Kit blocks, present when contentType is `block`. See the [Block Kit guide](/docs/guides/block-kit). |
| `color` | string | No | Color strip on the message. One of: `good`, `warning`, `danger`, or a hex color like `#5B3FD9`. Present only on Block Kit messages. |
| `poll` | object | No | Poll content, present when contentType is `poll`. |
| `replyTimestamp` | integer | No | Timestamp of the message this message quotes (set via the `replyTimestamp` request field on chat.post). Present on quoted replies in DMs and within channel threads; omitted otherwise. |
| `reactions` | Reaction[] | No | Reactions on this message |

**ChatItem** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | UUID identifying this item |
| `type` | "photo" | "blob" | Yes | Type of item:  - **photo**: Images with inline preview and thumbnail   - image/jpeg, image/png, image/gif, image/webp  - **blob**: Any other file type (download only, no preview)   - application/octet |
| `mime` | string | No | MIME type of the file (e.g., "application/octet-stream"). May be omitted for photo items where the type is inferred from the image format.  |
| `created` | string | Yes | Timestamp when the item was created |
| `name` | string | Yes | Name of the item (typically the filename). |
| `url` | string | Yes | URL for the uploaded item. |
| `thumbnail` | string | No | URL for a thumbnail of the uploaded item (photo type only). This may be equal to the item's main URL if it is suitable to use as a thumbnail.  |
| `size` | integer | No | Size of the item in bytes |
| `width` | integer | No | Width in pixels (images only) |
| `height` | integer | No | Height in pixels (images only) |

**poll**:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `question` | string | No | The poll question. |
| `options` | object[] | No | The poll answer options. |
| `allowMultipleAnswers` | boolean | No | Whether voters can select multiple options. |
| `closesAt` | string | No | When the poll closes (RFC-3339). Omitted if no close time is set. |

**Reaction** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | string | Yes | Always `"reaction"`. |
| `chat` | TaggedUUID | Yes | The chat containing the message that was reacted to. |
| `recipient` | TaggedUUID | No | The app address (bot or sender profile) this webhook was delivered to. |
| `messageId` | string | Yes | ID of the message that was reacted to. |
| `messageTimestamp` | integer | Yes | Timestamp of the message that was reacted to. |
| `threadTimestamp` | integer | No | Timestamp of the thread root, when the message is in a thread. Omitted for top-level messages. |
| `messageSender` | TaggedUUID | Yes | The author of the message that was reacted to (not the person who added the reaction). Provided so you can filter deliveries client-side.  |
| `chatType` | string | Yes | The type of chat the message is in (e.g. `dm`, `channel`). |
| `reactions` | object[] | Yes | The full set of reactions currently on the message. |


#### Example Response

```json
{
  "chat": "C-295155ae-7df5-4ed5-9ebc-89a170559c81",
  "messages": [
    {
      "type": "message",
      "contentType": "text",
      "sender": "U-ad1e9cc0-0ffd-47e5-895c-2630a73327b4",
      "chat": "C-295155ae-7df5-4ed5-9ebc-89a170559c81",
      "timestamp": 1765602474760032,
      "text": "Hey team, can we sync up on the roadmap this afternoon?"
    },
    {
      "type": "message",
      "contentType": "text",
      "sender": "U-709b8a57-70bc-427a-b6f0-b16ba5297f8c",
      "chat": "C-295155ae-7df5-4ed5-9ebc-89a170559c81",
      "timestamp": 1765602480123456,
      "text": "Sure, I'm free at 3pm!"
    },
    {
      "type": "message",
      "contentType": "poll",
      "sender": "B-ad1e9cc0-0ffd-47e5-895c-2630a73327b4",
      "chat": "C-295155ae-7df5-4ed5-9ebc-89a170559c81",
      "timestamp": 1765602490000000,
      "poll": {
        "question": "When should we have the team standup?",
        "options": [
          {
            "id": "01968a3b-7c00-7000-8000-000000000001",
            "text": "9:00 AM"
          },
          {
            "id": "01968a3b-7c00-7000-8000-000000000002",
            "text": "10:00 AM"
          },
          {
            "id": "01968a3b-7c00-7000-8000-000000000003",
            "text": "11:00 AM"
          }
        ],
        "allowMultipleAnswers": false
      }
    }
  ],
  "nextCursor": "YzE6MTc2NTYwMjQ3NDc2MDAzMg"
}
```

### 400 - Bad request, including an unparseable `ascending` value (`code` is `invalid_parameter`).

### 401 - Presented invalid authentication credentials.

### 403 - Bot is not a member of this chat.

### 405 - An unsupported method was requested.

### 500 - An internal error occured.

---

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