Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/osmiumchat/proto/llms.txt

Use this file to discover all available pages before exploring further.

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