OriginChats

A real-time chat server with text, voice, and forum channels.

Features

• Text Channels - Send messages, reply, react, pin
• Voice Channels - Peer-to-peer audio calls
• Forum Channels - Organized threads for discussions
• User Management - Roles, permissions, bans, timeouts
• Plugins - Extend with custom features
• Slash Commands - Custom commands for users

Quick Start

1. Install:

pip install -r requirements.txt

2. Configure:

python setup.py

3. Run:

python init.py

Server runs at ws://localhost:5613 by default.

Documentation

• Overview - Core concepts and features
• Getting Started - How to connect and use the API
• Client Development - Build your own client
• Plugin Development - Create server plugins
• Production Setup - Deploy securely
• Command Reference - All available commands
• Clients - Existing clients you can use

Configuration

Main settings in config.json:

{
  "websocket": { "host": "127.0.0.1", "port": 5613 },
  "rate_limiting": { "enabled": true, "messages_per_minute": 30 },
  "limits": { "post_content": 2000 }
}

See Configuration Docs for all options.

Rate Limiting

Built-in spam protection limits messages per user. When rate limited, clients receive:

{ "cmd": "rate_limit", "length": 5000 }

Wait length milliseconds before sending more messages.

Channel Types

Type	Description
Text	Real-time text messaging
Voice	Audio calls via WebRTC
Forum	Organized threads for topics

Permissions

Role-based permissions control what users can do:

• View channels
• Send/edit/delete messages
• Manage users (ban, timeout)
• Pin messages
• Use slash commands

See Permissions for details.

Authentication

Uses Rotur authentication service. See Getting Started for the full flow.

Clients

See clients.md for available clients.

Development

Adding New Commands

1. Add a new case in handlers/message.py:

   case "my_command":
       # Handle command
       return {"cmd": "my_response"}

2. Update documentation in docs/commands/my_command.md

Creating Plugins

See plugins/ directory for examples. Plugins can:

• Respond to new messages
• Handle slash commands
• Modify message data
• Trigger events

Adding Config Values

Use the same 3-step flow throughout the codebase:

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 Protocol

All WebSocket messages follow this format:

{
  "cmd": "command_name",
  "key": "value",
  "global": true  // Optional: broadcast to all
}

See Protocol Documentation for details.

Error Handling

All errors return:

{
  "cmd": "error",
  "val": "Error message"
}

See Error Handling for all possible errors.

Contributing

Contributions welcome! See the documentation for details.