# Get Chat Messages

`GET /chat.history`

## Description

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

The ordering of results depends on the filter specified:

- When no parameters are provided, the most recent recordings are returned,
  sorted in reverse chronological order. This is equivalent to specifying `before`
  as NOW and leaving `after` unspecified.

- If `after` is specified, the results are sorted in forward chronological order.

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".  |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. |
| `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 | A 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 | Key of the message that this is a reply to. This applies only in DM chats which lack real threads. |
| `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 |
|----------|------|----------|-------------|
| `chat` | TaggedUUID | Yes | The chat containing the message that was reacted to. |
| `timestamp` | integer | Yes | Timestamp of the message that was reacted to. |
| `name` | string | Yes | Name of the reaction that was added (e.g. "thumbs_up", "heart"). |
| `user` | User | Yes | The user who added the reaction. |


#### 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": "1765602474760032"
}
```

### 400 - Bad request.

### 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*