Skip to main content
The Osmium Chat Protocol provides a comprehensive chat system that supports both direct messaging and group conversations. Chats are distinct from communities and channels, offering a more personal communication experience.

​
Chats vs Communities

Chats are designed for direct, personal communication:
  • Direct messages (DMs) between two users
  • Group chats with multiple participants
  • Conversation-based interface with read states
  • Personal permissions and muting settings
Communities are structured group spaces:
  • Multiple organized channels (text, voice, categories)
  • Role-based permission system
  • Hierarchical structure with channels and categories
  • Server-wide settings and moderation

​
Core Chat Types

The protocol defines chats through the Conversation type, which can represent:
  1. Direct Messages - One-on-one conversations between two users
  2. Group Chats - Multi-user conversations managed through the Group type

​
GetChats

Retrieve a list of all your conversations with pagination support. 
message GetChats {
  optional uint32 limit = 1;
  // @snowflake<Chat>
  optional fixed64 max_id = 2;
  // @snowflake<Chat>
  optional fixed64 min_id = 3;
}
​
limit
uint32
Maximum number of chats to return
​
max_id
fixed64
Snowflake ID - return chats older than this ID (for pagination)
​
min_id
fixed64
Snowflake ID - return chats newer than this ID (for pagination)

​
Response: Chats

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[]
List of conversation objects containing read states and metadata
​
users
User[]
User objects referenced in the conversations
​
groups
Group[]
Group objects for group chats
​
channels
Channel[]
Channel objects (if any conversations are with channels)
​
messages
Message[]
Last messages for each conversation

​
Key Features

​
Conversation Management

  • Retrieve all chats with GetChats
  • Get individual chat details with GetChat
  • Track read states and unread counts
  • Support for drafts and typing indicators

​
Group Chat Operations

  • Create new group chats with multiple users
  • Update group chat settings (name, etc.)
  • Manage participants (add/remove members)
  • Owner-based permission model

​
Read States & Activity

  • Mark messages as read with MarkChatRead
  • Track unread message counts per conversation
  • Set typing indicators with SetTyping
  • Maintain last read message position

​
Invitations

  • Create chat invites with expiration and usage limits
  • List all invites for a chat
  • Delete/revoke invites

​
Next Steps

Direct Messages

Learn about direct messaging and the Conversation type

Group Chats

Create and manage group conversations

Conversations

Understand read states, typing indicators, and chat invites

Build docs developers (and LLMs) love

Get started for freeTalk to us