Skip to main content

chat

chat — ɳSelf documentation.

Chat Plugin

Real-time chat with rooms, direct messages, reactions, and moderation. Pro plugin.

Requires: A paid bundle license or ɳSelf+. 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 Var Default Description
CHAT_PORT 3401 Chat service port
CHAT_MAX_MESSAGE_LENGTH 4096 Max characters per message
CHAT_FILE_UPLOAD_ENABLED true Allow file attachments
CHAT_MODERATION_ENABLED true Enable content moderation
CHAT_HISTORY_RETENTION_DAYS 365 Days to retain messages

LiveKit Integration (video/audio calls)

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

Env Var Required Description
LIVEKIT_URL Yes LiveKit server WebSocket URL (e.g. wss://livekit.example.com)
LIVEKIT_API_KEY Yes LiveKit API key for server-side token generation
LIVEKIT_API_SECRET Yes LiveKit API secret for server-side token generation
LIVEKIT_WEBHOOK_SECRET No Optional: 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

Port Purpose
3401 Chat 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

Route Target
/chat/ Chat REST API
/chat/ws WebSocket endpoint