Creating and Managing Chat Rooms

Overview

Mirage allows you to create both public and private chat rooms for real-time communication. This guide walks you through room creation, joining rooms, and managing room messages.

Mirage limits public rooms to 5 maximum per instance. Private rooms have no limit.

Creating a Chat Room

Authenticate your request

All room operations require a valid authentication token in the Authorization header.

headers = {
    'Authorization': 'your_auth_token',
    'Content-Type': 'application/json'
}

Send room creation request

Create a room by sending a POST request to /api/create_room with the room details.

import requests

# Create a public room
response = requests.post(
    'https://api.mirage.com/api/create_room',
    headers=headers,
    json={
        'room_name': 'general-chat',
        'is_private': 0  # 0 for public, 1 for private
    }
)

Room names must be unique across the entire platform. If a room with the same name exists, you’ll receive a 400 error.

Handle the response

On success, you’ll receive the room ID and confirmation message.

{
    "message": "room \"general-chat\" created",
    "room_id": 42
}

The creator is automatically added as a member of the room.

Creating Private Rooms

Private rooms require a password and bypass the 5-room public limit.

# Create a private room
response = requests.post(
    'https://api.mirage.com/api/create_room',
    headers=headers,
    json={
        'room_name': 'secret-project',
        'is_private': 1,
        'password': 'secure_password123'
    }
)

Passwords are hashed using SHA-256 before storage. See app/utils.py:9 for the implementation.

Password Requirements

Required for private rooms (returns 400 if missing)
Stored as SHA-256 hash
Cannot be empty or whitespace-only

Public Room Limit

Mirage enforces a maximum of 5 public rooms system-wide to encourage focused discussions.

# From app/routes/chat.py:50-56
if not is_private:
    c.execute('SELECT COUNT(*) FROM rooms WHERE is_private=0')
    public_room_count = c.fetchone()[0]
    if public_room_count >= 5:
        return jsonify({
            'error': 'maximum number of public rooms reached (5). '
                     'Please create a private room to continue'
        }), 400

When the public room limit is reached, you’ll receive this error message. Create a private room instead or wait for an existing public room to be deleted.

Joining Existing Rooms

List available rooms

Get all public rooms and your membership status.

response = requests.get(
    'https://api.mirage.com/api/rooms',
    headers=headers
)

# Response
{
    "rooms": [
        {
            "room_id": 1,
            "name": "general-chat",
            "joined": false
        },
        {
            "room_id": 2,
            "name": "tech-discussion",
            "joined": true
        }
    ]
}

Join a room

For public rooms, send a join request without a password.

response = requests.post(
    'https://api.mirage.com/api/join_room',
    headers=headers,
    json={
        'name': 'general-chat'
    }
)

For private rooms, include the password.

response = requests.post(
    'https://api.mirage.com/api/join_room',
    headers=headers,
    json={
        'name': 'secret-project',
        'password': 'secure_password123'
    }
)

Join Room Error Codes

Status Code	Error	Description
`400`	Missing room name or token	Required fields not provided
`401`	Unauthorized	Invalid authentication token
`403`	Password required	Private room accessed without password
`403`	Wrong password	Incorrect password for private room
`404`	Room not found	Room doesn’t exist

Sending Messages

Once you’re a member of a room, you can send messages.

response = requests.post(
    'https://api.mirage.com/api/send_room_message',
    headers=headers,
    json={
        'room_id': 42,
        'message': 'Hello everyone!'
    }
)

You must be a member of the room to send messages. The system verifies membership in app/routes/chat.py:146-149.

Message Constraints

Messages have built-in lifecycle management:

Maximum messages: 100 stored in memory (MAX_MESSAGES in app/config.py:5)
Message lifespan: 30 minutes (MESSAGE_LIFESPAN = 60 * 30 * 30 in app/config.py:6)
Oldest messages are removed when limit is exceeded
Messages older than lifespan are automatically pruned

# From app/routes/chat.py:161-164
now = time.time()
messages[:] = [m for m in messages if now - m['created_at'] < MESSAGE_LIFESPAN]
if len(messages) > MAX_MESSAGES:
    messages.pop(0)

Retrieving Messages

Fetch all messages for a room you’re a member of.

response = requests.get(
    'https://api.mirage.com/api/get_room_messages',
    headers=headers,
    params={'room_id': 42}
)

# Response
{
    "messages": [
        {
            "username": "alice",
            "message": "Hello everyone!",
            "created_at": 1709467200.0,
            "room_id": 42
        }
    ]
}

You’ll receive a 403 error if you try to retrieve messages from a room you’re not a member of.

Managing Room Members

View Room Members

Get a list of all members in a room.

response = requests.get(
    'https://api.mirage.com/api/room_members/42',
    headers=headers
)

# Response
{
    "members": ["alice", "bob", "charlie"]
}

View Your Rooms

Get all rooms you’re currently a member of, including both public and private rooms.

response = requests.get(
    'https://api.mirage.com/api/user_rooms',
    headers=headers
)

# Response
{
    "rooms": [
        {
            "room_id": 1,
            "name": "general-chat",
            "is_private": 0
        },
        {
            "room_id": 3,
            "name": "secret-project",
            "is_private": 1
        }
    ]
}

Database Schema

Understanding the underlying schema helps with advanced integrations.

Room Tables Schema

-- Rooms table (app/db.py:89-95)
CREATE TABLE rooms (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT UNIQUE NOT NULL,
    is_private INTEGER DEFAULT 0,
    password_hash TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)

-- Room members table (app/db.py:96-103)
CREATE TABLE room_members (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    room_id INTEGER NOT NULL,
    username TEXT NOT NULL,
    joined_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY(room_id) REFERENCES rooms(id),
    FOREIGN KEY(username) REFERENCES users(username)
)

Best Practices

Use Private Rooms

When the 5 public room limit is reached, create private rooms for team discussions.

Descriptive Names

Use clear, descriptive room names to help users find relevant conversations.

Password Strength

Use strong passwords for private rooms to prevent unauthorized access.

Monitor Membership

Regularly check room members to ensure appropriate access.

Common Issues

Room creation fails with 'room already exists'

Room names must be globally unique. Try a different name or check if someone else created a room with that name.

Can't create more public rooms

The system has a hard limit of 5 public rooms. Either:

Create a private room instead
Wait for an existing public room to be deleted
Contact the administrator to remove unused rooms

Messages not appearing

Messages older than 30 minutes are automatically pruned. If you sent a message more than 30 minutes ago, it may have been removed from the in-memory store.

Can't join private room

Ensure you’re providing the correct password. Passwords are case-sensitive and must match exactly.

Get Started

Core Features

Guides

Creating and Managing Chat Rooms

Overview

Creating a Chat Room

Creating Private Rooms

Password Requirements

Public Room Limit

Joining Existing Rooms

Join Room Error Codes

Sending Messages

Message Constraints

Retrieving Messages

Managing Room Members

View Room Members

View Your Rooms

Database Schema

Best Practices

Use Private Rooms

Descriptive Names

Password Strength

Monitor Membership

Common Issues

Next Steps

File Sharing

Privacy Settings

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

​Overview

​Creating a Chat Room

​Creating Private Rooms

​Password Requirements

​Public Room Limit

​Joining Existing Rooms

​Join Room Error Codes

​Sending Messages

​Message Constraints

​Retrieving Messages

​Managing Room Members

​View Room Members

​View Your Rooms

​Database Schema

​Best Practices

Use Private Rooms

Descriptive Names

Password Strength

Monitor Membership

​Common Issues

​Next Steps

File Sharing

Privacy Settings

Build docs developers (and LLMs) love

Overview

Creating a Chat Room

Creating Private Rooms

Password Requirements

Public Room Limit

Joining Existing Rooms

Join Room Error Codes

Sending Messages

Message Constraints

Retrieving Messages

Managing Room Members

View Room Members

View Your Rooms

Database Schema

Best Practices

Common Issues

Next Steps