Skip to main content

​
Overview

The GetHistory request retrieves message history from a chat with flexible pagination options. You can fetch messages in chronological or reverse-chronological order, or retrieve messages around a specific message ID.

​
Proto Definition

// messages.getHistory -> messages.Messages
message GetHistory {
  refs.ChatRef chat_ref = 1;
  optional uint32 limit = 2;
  oneof offset {
    fixed64 since = 3;   // @snowflake<Message>
    fixed64 before = 4;  // @snowflake<Message>
    fixed64 around = 5;  // @snowflake<Message>
  }
}

message Messages {
  repeated types.Message messages = 1;
  repeated types.User users = 2;
  repeated types.CommunityMember members = 3;
  repeated reactions.MessageReactions reactions = 4;
}

​
Request Fields

​
chat_ref
ChatRef
required
The chat to retrieve message history from. Can be a user (DM), channel, group, or self (saved messages).
​
limit
uint32
Maximum number of messages to return. Defaults to 50 if not specified.When using around, the limit is split between messages before and after the specified message ID.
​
since
fixed64
Retrieve messages sent after this message ID (exclusive). Returns messages in chronological order (oldest first).Type: Snowflake ID representing a MessageNote: Only one of since, before, or around can be specified.
​
before
fixed64
Retrieve messages sent before this message ID (exclusive). Returns messages in reverse-chronological order (newest first).Type: Snowflake ID representing a MessageNote: Only one of since, before, or around can be specified.
​
around
fixed64
Retrieve messages around this message ID. Returns messages both before and after the specified ID, split according to the limit.Type: Snowflake ID representing a MessageFor example, with limit=50, you’ll get approximately 25 messages before and 25 messages after the specified message.Note: Only one of since, before, or around can be specified.

​
Response

The response includes not just messages, but also all related data needed to display them:
​
messages
Message[]
required
Array of messages matching the query. Each message includes:
  • chat_ref - The chat reference
  • message_id - Unique snowflake ID
  • author_id - User ID of the sender
  • message - Text content
  • reply_to - ID of replied-to message (optional)
  • media - Media attachments (optional)
  • entities - Formatting entities (optional)
  • edited_at - Edit timestamp (optional)
  • type - Message type (optional)
  • forward - Forward info (optional)
​
users
User[]
required
Array of user objects for all users referenced in the messages (authors, mentioned users, etc.).
​
members
CommunityMember[]
required
Array of community member data for community channels (includes roles, nicknames, etc.).
​
reactions
MessageReactions[]
required
Array of reactions for the returned messages.

​
Examples

​
Get Recent Messages (Default)

{
  "chat_ref": {
    "user": {
      "user_id": "123456789012345678"
    }
  }
}
Returns the 50 most recent messages in chronological order.

​
Get Messages Before a Specific Message

{
  "chat_ref": {
    "channel": {
      "community_id": "987654321098765432",
      "channel_id": "111111111111111111"
    }
  },
  "before": "555555555555555555",
  "limit": 100
}
Returns up to 100 messages sent before message ID 555555555555555555.

​
Get Messages After a Specific Message

{
  "chat_ref": {
    "group": {
      "group_id": "222222222222222222"
    }
  },
  "since": "444444444444444444",
  "limit": 50
}
Returns up to 50 messages sent after message ID 444444444444444444 (useful for catching up on new messages).

​
Get Messages Around a Specific Message

{
  "chat_ref": {
    "channel": {
      "community_id": "987654321098765432",
      "channel_id": "111111111111111111"
    }
  },
  "around": "666666666666666666",
  "limit": 50
}
Returns approximately 25 messages before and 25 messages after message ID 666666666666666666 (useful for jumping to a specific message with context).

​
Pagination Strategies

​
Initial Load

To load the most recent messages when opening a chat: 
{
  "chat_ref": { /* ... */ },
  "limit": 50
}

​
Loading Older Messages (Scrolling Up)

To load older messages when the user scrolls up: 
{
  "chat_ref": { /* ... */ },
  "before": "<oldest_message_id_in_current_view>",
  "limit": 50
}

​
Loading Newer Messages (Catching Up)

To load newer messages when catching up: 
{
  "chat_ref": { /* ... */ },
  "since": "<newest_message_id_in_current_view>",
  "limit": 50
}

​
Jump to Message

To jump to a specific message (e.g., from search results or a link): 
{
  "chat_ref": { /* ... */ },
  "around": "<target_message_id>",
  "limit": 50
}

​
Notes

  • Message IDs are snowflakes, which are chronologically sortable
  • The users and members arrays in the response provide all necessary user data to render the messages
  • The reactions array includes reaction data for all returned messages
  • When using around, the specified message ID is included in the results
  • The default limit of 50 is a reasonable balance between performance and user experience

Build docs developers (and LLMs) love

Get started for freeTalk to us