docs

OriginChats Documentation

Welcome to the OriginChats server documentation. OriginChats is a WebSocket-based real-time chat server with voice channels, slash commands, plugins, and role-based permissions.

Client List: See clients.md for a list of official and community clients.

---

Table of Contents

• Getting Started
  • Quick Start
  • Setup
  • Configuration
• API Reference
• Commands
• Data Structures
• Client Development

---

Getting Started

Quick Start

OriginChats is a real-time WebSocket chat server built in Python. It supports text and voice channels, role-based permissions, slash commands, and plugin extensibility.

Setup

1. Requirements:

   pip install -r requirements.txt

2. Configuration:

   • Run python setup.py to generate config.json, or edit it manually
   • Configure Rotur authentication service

3. Start the Server:

   python init.py

Configuration

Key configuration options in config.json:

{
  "websocket": {
    "host": "127.0.0.1",
    "port": 5613
  },
  "rotur": {
    "validate_url": "...",
    "validate_key": "..."
  },
  "rate_limiting": {
    "enabled": true,
    "messages_per_minute": 30
  },
  "limits": {
    "post_content": 2000,
    "search_results": 30
  },
  "uploads": {
    "emoji_allowed_file_types": ["gif", "jpg", "jpeg", "png"]
  }
}

For full configuration details, see Configuration.

To add a new config value:

1. Add the default in config_builder.py.
2. If it should be configurable during setup, prompt for it in setup.py and add it to the overrides passed into build_config(...).
3. Read it with get_config_value(...) from config_store.py, or use the local handler helper when server_data["config"] is already available.

---

API Reference

• Protocol Documentation - WebSocket protocol details, handshake, heartbeat
• Authentication - User authentication flow with Rotur service
• Error Handling - Common error responses and their meanings

---

Commands

Text Messaging

Command	Description	Documentation
message_new	Send a new message	View
message_edit	Edit an existing message	View
message_delete	Delete a message	View
typing	Send typing indicator	View
messages_get	Get channel messages	View
message_get	Get a specific message	View
message_replies	Get replies to a message	View
messages_search	Search messages in a channel	View
messages_pinned	Get pinned messages	View
message_react_add	Add reaction to message	View
message_react_remove	Remove reaction from message	View
message_pin / message_unpin	Pin/unpin a message	View

Voice Channels

Command	Description	Documentation
voice_join	Join a voice channel	View
voice_leave	Leave current voice channel	View
voice_mute / voice_unmute	Mute/unmute microphone	View
voice_state	Get voice channel participants	View

User Management

Command	Description	Documentation
users_list	List all users	View
users_online	List online users	View
users_banned_list	List banned users (owner only)	View
user_ban	Ban a user (owner only)	View
user_unban	Unban a user (owner only)	View
user_timeout	Set user timeout (owner only)	View
user_leave	Disconnect a user (owner only)	View
user_roles_add	Add roles to a user (owner only)	View
user_roles_remove	Remove roles from a user (owner only)	View
user_roles_get	Get a user's roles (owner only)	View

Role Management

Command	Description	Documentation
role_create	Create a new role (owner only)	View
role_update	Update a role (owner only)	View
role_delete	Delete a role (owner only)	View
roles_list	List all roles	View

Channel Management

Command	Description	Documentation
channels_get	Get available channels	View
channel_create	Create a new channel (owner only)	View
channel_update	Update a channel (owner only)	View
channel_move	Move a channel to new position (owner only)	View
channel_delete	Delete a channel (owner only)	View

Server Management

Command	Description	Documentation
ping	Ping the server	View
plugins_list	List loaded plugins	View
plugins_reload	Reload plugins	View
rate_limit_status	Check rate limit status	View
rate_limit_reset	Reset rate limit (owner only)	View

Slash Commands

Command	Description	Documentation
slash_register	Register a new slash command (owner only)	View
slash_list	List all registered slash commands	View
slash_call	Execute a slash command	View

Push Notifications

Command	Description	Documentation
push_get_vapid	Request the server's VAPID public key	View
push_subscribe	Register a Web Push subscription	View
push_unsubscribe	Remove a Web Push subscription	View

For a full overview of the feature including server setup, payload format, and client integration, see the Web Push Notifications guide.

---

Data Structures

• User Object - User data structure
• Channel Object - Channel configuration, permissions, and voice state
• Message Object - Message structure with replies and reactions
• Emoji Object - Custom emoji metadata and collection format
• Role Object - Role definitions and colors
• Config Schema - Server configuration options
• Permissions System - How role-based permissions work

---

Client Development

For developers building clients:

1. Connection Flow:

   • Connect to WebSocket server
   • Receive handshake packet
   • Authenticate using Rotur validator
   • Start sending/receiving commands

2. Voice Channels:

   • WebRTC peer connection setup
   • Join/leave voice channels
   • Mute/unmute functionality

3. Commands Overview:

   • All commands use JSON format with cmd field
   • Global broadcasts use global: true flag
   • Errors return { "cmd": "error", "val": "message" }

---

Rate Limiting

OriginChats includes built-in rate limiting:

• Per-minute limit: Maximum messages per user per minute (configurable)
• Burst protection: Prevents spam in short time windows
• Cooldown: Temporary restriction after burst limit exceeded

Response format:

{
  "cmd": "rate_limit",
  "length": <milliseconds>
}

See README.md for server architecture and rate limiting details.

---

Support

For issues, questions, or contributions:

• Source Code: Repository
• Issue Tracker: Open an issue on GitHub
• Protocol: See protocol.md

---

Last Updated: 2026-03-09