Skip to main content

chat

chat — ɳSelf documentation.

Chat Plugin

Real-time chat with rooms, direct messages, reactions, and moderation. Pro plugin: Basic tier ($0.99/mo).

Requires: Basic license tier or higher. nself license set nself_pro_...

Install

nself license set nself_pro_xxxxx...
nself plugin install chat

What It Does

Adds a complete real-time chat backend to your ɳSelf stack. Supports group rooms, direct messages between users, message reactions, thread replies, and built-in moderation tools. Powers the ɳSelf Chat open-source client app. Exposes a REST API and WebSocket connections for real-time message delivery.

Configuration

Env VarDefaultDescription
CHAT_PORT3401Chat service port
CHAT_MAX_MESSAGE_LENGTH4096Max characters per message
CHAT_FILE_UPLOAD_ENABLEDtrueAllow file attachments
CHAT_MODERATION_ENABLEDtrueEnable content moderation
CHAT_HISTORY_RETENTION_DAYS365Days to retain messages

LiveKit Integration (video/audio calls)

When the livekit plugin is installed alongside chat, set these additional env vars:

Env VarRequiredDescription
LIVEKIT_URLYesLiveKit server WebSocket URL (e.g. wss://livekit.example.com)
LIVEKIT_API_KEYYesLiveKit API key for server-side token generation
LIVEKIT_API_SECRETYesLiveKit API secret for server-side token generation
LIVEKIT_WEBHOOK_SECRETNoOptional: webhook secret for LiveKit room events

Expose these to the Next.js frontend via the NEXT_PUBLIC_ prefix where needed:

# In your nSelf env file
LIVEKIT_URL=wss://livekit.example.com
LIVEKIT_API_KEY=your_api_key
LIVEKIT_API_SECRET=your_api_secret

# Frontend detection (set in .env.local or via nself env set)
NEXT_PUBLIC_LIVEKIT_URL=wss://livekit.example.com

The chat frontend detects LiveKit at runtime: if NEXT_PUBLIC_LIVEKIT_URL is not set, video call buttons are hidden and the app continues to function normally.

Ports

PortPurpose
3401Chat REST API and WebSocket

Database Tables

6 tables added to your Postgres database:

  • np_chat_rooms: room definitions and settings
  • np_chat_participants: room membership
  • np_chat_messages: message content and metadata
  • np_chat_reactions: message reactions
  • np_chat_threads: threaded reply chains
  • np_chat_moderation: moderation actions and bans

Nginx Routes

RouteTarget
/chat/Chat REST API
/chat/wsWebSocket endpoint