Skip to main content

​
Osmium Chat Protocol

Osmium Chat Protocol is a comprehensive, type-safe communication protocol built on Protocol Buffers (proto3). It provides a complete foundation for building modern chat applications with support for direct messaging, communities, voice channels, media sharing, and real-time updates.

​
Overview

The protocol is designed around a request-response RPC pattern with real-time server-pushed updates. Every client request receives a typed response, while the server can push updates to keep clients synchronized with minimal overhead. Key Architecture:
  • ClientMessage: Wraps all client requests with a unique ID for matching responses
  • ServerMessage: Contains either an RPC result or a real-time update
  • RPCResult: Type-safe responses mapped to specific request types
  • Update: Real-time notifications for messages, typing indicators, member changes, and more

​
Key Features

Type-Safe RPC

Request-response pattern with unique message IDs. Every RPC call has a corresponding result type defined in the protocol.

Real-Time Updates

Server-pushed updates for messages, typing indicators, presence, member changes, and more. Keep clients synchronized effortlessly.

Rich Messaging

Support for text formatting, mentions, replies, embeds, reactions, message editing, forwarding, and comprehensive media attachments.

Communities & Channels

Full-featured community system with text and voice channels, roles, permissions, channel categories, and member management.

Media Handling

Chunked file upload/download with metadata for images, videos, audio, and custom emojis. Support for both uploaded files and embeds.

Voice & Video

Voice channel support with room management, participant tracking, and real-time room state updates.

Flexible Authentication

Multiple auth flows including sign up, sign in, token authorization, session management, email verification, and password reset.

Extensible Design

Modular protocol structure organized into focused packages: auth, messages, communities, chats, media, friends, and more.

​
Protocol Packages

The protocol is organized into specialized packages:
  • core: ClientMessage, ServerMessage, RPCResult, and initialization
  • auth: Authentication, authorization, sessions, and invite management
  • messages: Sending, editing, deleting, searching, and forwarding messages
  • chats: Direct messages, group chats, and conversation management
  • communities: Communities, channels, roles, and permissions
  • friends: Friend relationships and friend requests
  • media: File upload/download and media metadata
  • updates: Real-time update messages for all entity types
  • voice: Voice room management and participant state
  • reactions: Message reactions
  • stickers: Custom sticker packs and saved stickers
  • settings: User profiles, notifications, and account settings
  • types: Shared data types used across the protocol
  • refs: Reference types for addressing users, channels, and chats

​
Getting Started

Protocol Overview

Learn about the protocol architecture, message structure, and RPC patterns

Quick Start

Get up to speed quickly with practical examples and your first RPC call

​
Example: Sending a Message

Here’s a simple example of the message flow: 
// Client sends a message
ClientMessage {
  id: 42,
  message: {
    messages_send_message: SendMessage {
      chat_ref: ChatRef {
        channel: ChannelRef {
          community_id: 123456789,
          channel_id: 987654321
        }
      },
      message: "Hello, world!"
    }
  }
}

// Server responds with the message ID
ServerMessage {
  id: 1001,
  message: {
    result: RPCResult {
      req_id: 42,
      result: {
        sent_message: SentMessage {
          message_id: 555555555
        }
      }
    }
  }
}

// Server broadcasts update to all members
ServerMessage {
  id: 1002,
  message: {
    update: Update {
      message_created: UpdateMessageCreated {
        message: Message {
          chat_ref: { ... },
          message_id: 555555555,
          author_id: 111111111,
          message: "Hello, world!"
        },
        channel_unread_count: 1
      }
    }
  }
}
The protocol uses snowflake IDs (fixed64) for all entities, providing distributed ID generation with timestamp ordering.

​
Why Protocol Buffers?

Osmium uses Protocol Buffers for several key advantages:
  • Efficiency: Binary serialization is compact and fast
  • Type Safety: Strongly typed messages prevent errors
  • Cross-Platform: Generate clients in any language (Go, Rust, JavaScript, Python, etc.)
  • Versioning: Built-in support for evolving the protocol over time
  • Documentation: Protocol definitions serve as documentation

​
What’s Next?

1

Understand the Architecture

Read the Protocol Overview to understand how ClientMessage, ServerMessage, and updates work together.
2

Follow the Quick Start

Go through the Quick Start Guide to make your first RPC call and handle updates.
3

Explore the Packages

Dive into specific packages like messages, communities, or auth to learn about available operations.

Build docs developers (and LLMs) love

Get started for freeTalk to us