get_channel_messages
Retrieve recent channel messages, unread posts, or updates since a given timestamp. Supports pagination, unread-only mode, and sync from a watermark.
Instructions
Get messages from a channel — recent history, the user's unread window, or posts changed since a watermark.
Three mutually-exclusive modes. Pick by user intent:
"Show last N" / "what's in this channel" → default (page, per_page). Reverse-chronological.
truncated=True⇒ more posts exist; paginate."What did I miss" →
unread_only=True. The user's unread window anchored atlast_viewed_at, withlimit_beforecontext posts. Quirk: on a never-viewed channel (last_viewed_at == 0)orderis empty even whenunread_msg_count > 0— callmark_channel_viewedonce to bootstrap."Sync everything since " →
since=<unix_ms>. Posts withupdate_at > since, including edits of older posts and tombstones (delete_at != 0, emptymessage). Server caps at 1000; ontruncated=Truestep the watermark forward in smaller windows.
Returns {order, posts, truncated}. posts may contain more entries
than order (root posts pulled in by thread replies). System posts
(type starts with "system_") appear in unread_only/since
responses but are NOT counted in unread_msg_count.
For keyword search use search_messages; for full threads use get_thread.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (0-indexed) | |
| since | No | Unix timestamp in milliseconds (>= 10^12, i.e. >= 2001-01-01); return posts modified after this time. Mutually exclusive with unread_only and pagination. Use ChannelWithUnreads.last_viewed_at from list_my_channels. | |
| per_page | No | Results per page | |
| channel_id | Yes | 26-character channel identifier (e.g., 'o5w8h47pdfbzjc4d8w7dhnhren') | |
| limit_after | No | In unread_only mode: unread posts to return (1-200) | |
| unread_only | No | Return only the user's unread window via /posts/unread | |
| limit_before | No | In unread_only mode: read context posts before the first unread (max 200) | |
| collapsed_threads | No | Set True only if the user has CRT (Collapsed Reply Threads) enabled. Team default is CRT off — leave False unless you know otherwise. Requires unread_only=True or since=<ms>; the default /posts endpoint rejects CRT-aware queries. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| order | Yes | Post IDs in display order | |
| posts | Yes | Map of post ID to Post object | |
| truncated | No | True when the response hit a Mattermost response cap — more posts exist beyond this batch | |
| next_post_id | No | Next post ID for pagination | |
| prev_post_id | No | Previous post ID for pagination |