MCP Reference
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_idset): 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
{
"$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
{
"$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"
}