Skip to main content
Direct messages (DMs) in Osmium Chat Protocol provide one-on-one communication between users. Each DM is represented as a Conversation object that tracks message history, read states, and user preferences.

​
GetChats

Retrieve a paginated list of all your conversations (including both DMs and group chats). 
message GetChats {
  optional uint32 limit = 1;
  // @snowflake<Chat>
  optional fixed64 max_id = 2;
  // @snowflake<Chat>
  optional fixed64 min_id = 3;
}

​
Parameters

​
limit
uint32
Maximum number of conversations to return in the response
​
max_id
fixed64
Snowflake Chat ID - Return only chats with IDs less than this value (for backward pagination)
​
min_id
fixed64
Snowflake Chat ID - Return only chats with IDs greater than this value (for forward pagination)

​
Response: Chats

The response includes all related data to render the conversations list: 
message Chats {
  repeated types.Conversation chats = 1;
  repeated types.User users = 2;
  repeated types.Group groups = 3;
  repeated types.Channel channels = 4;
  repeated types.Message messages = 5;
}
​
chats
Conversation[]
Array of conversation objects, each representing a DM or group chat with read state information
​
users
User[]
All user objects referenced in the conversations (DM participants, group members, message authors)
​
groups
Group[]
Group objects for any group chats included in the response
​
channels
Channel[]
Channel objects if any conversations involve channels
​
messages
Message[]
The last message for each conversation (used for previews)

​
GetChat

Retrieve detailed information about a specific conversation. 
message GetChat { 
  refs.ChatRef chat_ref = 1; 
}

​
Parameters

​
chat_ref
ChatRef
required
Reference to the chat to retrieve. Can specify by user ID (for DMs) or chat ID (for groups)

​
Response: Chat

Returns complete information about a single conversation: 
message Chat {
  types.Conversation chat = 1;
  optional types.Message message = 2;
  repeated types.User users = 3;
  optional types.Group group = 4;
  optional types.Channel channel = 5;
}
​
chat
Conversation
The conversation object with read states and metadata
​
message
Message
The last message in the conversation (if any)
​
users
User[]
All users involved in the conversation
​
group
Group
Group information if this is a group chat
​
channel
Channel
Channel information if this conversation is in a channel context

​
Conversation Type

The Conversation type tracks the state of a chat from the current user’s perspective: 
message Conversation {
  refs.ChatRef chat_ref = 1;
  // defaults to chat id if no last message (used for sorting)
  // @snowflake<Message>
  fixed64 last_message_id = 2;
  // @snowflake<Message>
  fixed64 last_read_message_id = 3;
  // reserved possible read receipts (last_read_message_id_sent?)
  reserved 4;
  uint32 unread_count = 5;
  optional string draft = 6;
  optional PermissionOverrides permissions = 7;
  bool muted = 8;
}

​
Fields

​
chat_ref
ChatRef
Reference identifying this conversation (user ID for DMs, chat ID for groups)
​
last_message_id
fixed64
Snowflake Message ID of the most recent message. Defaults to chat ID if no messages exist. Used for sorting conversations by recency
​
last_read_message_id
fixed64
Snowflake Message ID of the last message the current user has read
​
unread_count
uint32
Number of unread messages in this conversation
​
draft
string
Unsent message draft saved for this conversation
​
permissions
PermissionOverrides
Permission overrides for this conversation (if any)
​
muted
bool
Whether the user has muted notifications for this conversation

​
Permission Overrides

Permissions can be customized per conversation: 
message PermissionOverrides {
  fixed64 pos = 1;
  fixed64 neg = 2;
}
​
pos
fixed64
Bitfield of permissions to explicitly grant
​
neg
fixed64
Bitfield of permissions to explicitly deny

​
Usage Example

  1. Listing Conversations: Call GetChats to retrieve all DMs and group chats
  2. Opening a DM: Call GetChat with a ChatRef pointing to the user
  3. Tracking Read State: The Conversation object includes unread_count and last_read_message_id
  4. Sorting: Use last_message_id to sort conversations by most recent activity

Build docs developers (and LLMs) love

Get started for freeTalk to us