messages_around

messages_around returns a window of history centered on one message. Use it to jump to a message from a link, a search result, or a reply, and show the messages around it.

Request

{
  "cmd": "messages_around",
  "channel": "general",
  "around": "7d0e4c1a-5b8f-4b0e-8f55-2d3c9a61e7b4",
  "bounds": {
    "below": 1,
    "above": 1
  }
}

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.
around	string	Yes	ID of the message to center on. Trimmed; must not be empty.
bounds	object	No	How many messages to include on each side.
bounds.below	integer	No	Number of older messages before the target. Defaults to 50. Clamped to 0 through 200.
bounds.above	integer	No	Number of newer messages after the target. Defaults to 50. Clamped to 0 through 200.

The target message is always included, so one response covers at most 401 messages.

Response

{
  "cmd": "messages_around",
  "channel": "general",
  "messages": [
    {
      "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": 41, "end": 43 },
  "at_end": true
}

Here the target is the newest message, so there is nothing after it and at_end is true.

Field	Description
messages	Message objects, oldest first.
range.start	Position of the first message in the window, counting from 0 at the oldest message in the conversation.
range.end	Position just after the last message in the window.
at_start	Present and true when the window reaches the oldest message.
at_end	Present and true when the window 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 messages can be shorter than the range.
• To keep loading from here, call messages_get with the oldest message’s id as start.

Note

These positions count from the oldest message. messages_get counts from the newest, so the two range objects are not comparable.

Permissions

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

Errors

val	When
Channel or thread_id required	You sent neither channel nor thread_id.
Channel not found	The channel doesn’t exist.
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.
Message not found	around is not a message in this channel or thread.

A validation message is returned when around is missing or blank, or a bound is not a whole number.

See also

• messages_get
• messages_search