Skip to content

Latest commit

 

History

History
235 lines (177 loc) · 8.13 KB

README.md

File metadata and controls

235 lines (177 loc) · 8.13 KB

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

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

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

Data Structures

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:

Last Updated: 2026-03-09