messages_get

messages_get returns a page of messages from a channel or thread. Call it with no start to load the newest messages, then page backwards to load older ones.

Request

{
  "cmd": "messages_get",
  "channel": "general",
  "limit": 50
}

Field	Type	Required	Description
channel	string	One of channel or thread_id	Channel name.
thread_id	string	One of channel or thread_id	Thread ID. If you also send channel, it must be the thread’s parent.
start	integer or string	No	Where the page ends. A number skips that many of the newest messages; negative numbers count as 0. A string is a message ID; the page holds the messages just before it, not including it. Defaults to 0.
limit	integer	No	How many messages to return. Defaults to 100. Values are clamped to 0 through 200.

There are two ways to load older messages:

• By ID (recommended). Send the id of the oldest message you have as start. New messages arriving in between don’t shift the page.
• By offset. Send the previous response’s range.end as start. If new messages arrived since the last page, the offsets have moved and you may get duplicates.

A string is always treated as a message ID, even if it looks like a number. Send a JSON number for an offset.

Response

{
  "cmd": "messages_get",
  "channel": "general",
  "val": [
    {
      "id": "0b6c7f55-4a0f-4f7e-9a53-1a8b0d3d52c1",
      "user": "bob",
      "author_id": "<bob's user ID>",
      "timestamp": 1788939990.02,
      "content": "When do the release notes go out?"
    },
    {
      "id": "7d0e4c1a-5b8f-4b0e-8f55-2d3c9a61e7b4",
      "user": "alice",
      "author_id": "<alice's user ID>",
      "timestamp": 1788940000.31,
      "content": "Release notes are up: https://example.com/changelog"
    }
  ],
  "range": { "start": 0, "end": 2, "limit": 50 },
  "at_start": true,
  "at_end": true
}

Field	Description
val	Message objects, oldest first.
range.start	How many newer messages come after this page. 0 means the page ends at the newest message.
range.end	range.start plus the number of messages the page covers. Use it as the next start when paging by offset.
range.limit	The limit the server used, after clamping.
at_start	true when the page reaches the oldest message. Stop paging.
at_end	true when the page reaches the newest message.

• A thread response has thread_id, and channel is the thread’s parent.
• Messages from users severed from you are left out, so val can be shorter than the range.
• An offset past the oldest message, or limit: 0, returns an empty val.

Note

messages_around also returns a range, but counts from the oldest message instead. Don’t mix the two.

Permissions

You must be able to view the channel, or the thread’s parent channel.

Errors

val	When
Channel not found	The channel doesn’t exist, or you sent neither channel nor thread_id.
Thread not found	No thread has this ID.
Thread does not belong to this channel	channel is not the thread’s parent.
You do not have permission to view this thread	You can’t view the thread’s parent channel.
Messages must be sent inside a thread in forum channels	channel is a forum and you sent no thread_id.
This channel does not support chat	channel is a separator.
Access denied to this channel	You can’t view the channel.
start must be a message ID or numeric offset	start is an empty or blank string.
Message not found	start is an ID that isn’t in this channel or thread.

A validation message is returned when start or limit has the wrong type, including numbers with a fraction.

See also

• messages_around
• messages_batch