# chat_get_messages

Get Chat Messages

## Beschreibung

Reads messages from a chat channel or DM. Two response shapes:

- Default ("channel view"): root threads with their replies
  nested underneath each root. Sorted oldest-first within the
  returned window — `messages[last]` is the newest.
- Thread view (`parent_message_id` set): flat list of replies,
  no nesting (oona supports one thread level).

`limit` (1-200, default 50) caps ROOT count — replies always
come along in full, even outside the time filter (context
preserved). `before_id` pages backwards by root id. See Server
Instructions for date-filter semantics.

Attachments + reactions inline on every message (bulk-loaded).
`download_url` is signed + 30-min valid.

Access: the channel must be inside one of the caller's workspaces.
Public channels and joined private/DM channels are readable;
account admins may read every channel in the tenant.

## Zugriff

Zugriffsprofil: `basic`. Module: `chat`.
Die Freigabe im Profil ersetzt keine Account-, Workspace- oder Rollenberechtigung.

## Parameter

| Name | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `account_id` | string | Ja | Account prefix ID (e.g., acct_abc123). |
| `channel_id` | string | Ja | Channel prefix ID (e.g., chan_xyz789) from chat_list_channels. |
| `limit` | integer | Nein | Max ROOT threads (replies are always fully loaded). Default 50. |
| `before_id` | string | Nein | Paginate backwards: pass the oldest ROOT id from your previous response (msg_…) to get the next older page. Ignored in thread view. |
| `since` | string | Nein | Only return roots with created_at >= this ISO 8601 timestamp (e.g., 2026-04-21T00:00:00Z). Ignored in thread view. |
| `until` | string | Nein | Only return roots with created_at < this ISO 8601 timestamp. Ignored in thread view. |
| `start_date` | string | Nein | Calendar-day lower bound on root created_at (beginning of day in UTC). Use for single-day or multi-day ranges. Ignored in thread view. |
| `end_date` | string | Nein | Calendar-day upper bound (end of day). Defaults to start_date when only start_date is given — pair them for a range. Ignored in thread view. |
| `parent_message_id` | string | Nein | Switch to flat thread view: return only replies to this root (msg_…). Time filters and limit are ignored. |

## Eingabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Account prefix ID (e.g., acct_abc123)."
    },
    "channel_id": {
      "type": "string",
      "description": "Channel prefix ID (e.g., chan_xyz789) from chat_list_channels."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Max ROOT threads (replies are always fully loaded). Default 50."
    },
    "before_id": {
      "type": "string",
      "description": "Paginate backwards: pass the oldest ROOT id from your previous response (msg_…) to get the next older page. Ignored in thread view."
    },
    "since": {
      "type": "string",
      "format": "date-time",
      "description": "Only return roots with created_at >= this ISO 8601 timestamp (e.g., 2026-04-21T00:00:00Z). Ignored in thread view."
    },
    "until": {
      "type": "string",
      "format": "date-time",
      "description": "Only return roots with created_at < this ISO 8601 timestamp. Ignored in thread view."
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "description": "Calendar-day lower bound on root created_at (beginning of day in UTC). Use for single-day or multi-day ranges. Ignored in thread view."
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "Calendar-day upper bound (end of day). Defaults to start_date when only start_date is given — pair them for a range. Ignored in thread view."
    },
    "parent_message_id": {
      "type": "string",
      "description": "Switch to flat thread view: return only replies to this root (msg_…). Time filters and limit are ignored."
    }
  },
  "required": [
    "account_id",
    "channel_id"
  ],
  "type": "object"
}
```

## Ausgabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "channel": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Channel prefix ID (chan_…)."
        },
        "name": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "messages": {
      "type": "array",
      "description": "Channel view: roots with `replies` nested. Thread view: flat list of replies (no `replies` field).",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Message prefix ID (msg_…)."
          },
          "body": {
            "type": "string"
          },
          "user": {
            "type": "object",
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "handle": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "type": "string"
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "parent_message_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "null for roots; parent root's msg_… for replies."
          },
          "replies_count": {
            "type": "integer"
          },
          "reactions": {
            "type": "array",
            "description": "Flat list of all emoji reactions on this message, ordered by created_at ASC. Group by `emoji` client-side for counts.",
            "items": {
              "type": "object",
              "properties": {
                "emoji": {
                  "type": "string",
                  "description": "Unicode emoji."
                },
                "user": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "handle": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "name": {
                      "type": "string"
                    }
                  }
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                }
              },
              "required": [
                "emoji",
                "user",
                "created_at"
              ]
            }
          },
          "attachments": {
            "type": "array",
            "description": "Files attached to this message, ordered by upload time. download_url is a signed URL valid for 30 minutes — possession is the capability.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Blob prefix ID (att_…)."
                },
                "filename": {
                  "type": "string"
                },
                "mime_type": {
                  "type": "string"
                },
                "byte_size": {
                  "type": "integer"
                },
                "download_url": {
                  "type": "string",
                  "format": "uri"
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                }
              },
              "required": [
                "id",
                "filename",
                "mime_type",
                "byte_size",
                "download_url",
                "created_at"
              ]
            }
          },
          "replies": {
            "type": "array",
            "description": "Only present in channel view, on root messages.",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "id",
          "body",
          "user",
          "created_at",
          "parent_message_id",
          "replies_count",
          "reactions",
          "attachments"
        ]
      }
    }
  },
  "required": [
    "channel",
    "messages"
  ],
  "type": "object"
}
```