Signal Group Admin Bot

A Signal bot for managing group chats with a hierarchical space/room system. Supports public and private channels. Scheduled messages. And channels that refresh themselves after some amount of time.

Features

• Spaces: Admin groups that serve as control centers for managing multiple groups
• Channels: Group chats that are a part of a space
• Room Discovery: Users can query rooms from DMs or from within any bound room
• SQLite Database: Persistent storage for spaces, and rooms

Architecture

┌──────────────────┐
│  Direct Messages │
│   (DM Commands)  │
└────────┬─────────┘
         │ !new <name>
         ▼
┌──────────────────┐
│   Admin Space    │ ◄── Control center for room/user management
│  (Admin Cmds)    │
│                  │
│  • Manage rooms  │
│  • Vet users     │
└────────┬─────────┘
         │ !create / !bind
         ▼
┌──────────────────┐
│     Channel      │
└──────────────────┘

Room Information

Every room created by the bot includes:

• Space ID: The admin space that manages this room
• Room ID: The unique identifier for this room

Setup

Prerequisites

• Node.js 18+
• pnpm
• signal-cli configured and linked to a Signal account

Environment Variables

Copy .env.example to .env and configure:

SIGNAL_NUMBER=+1234567890        # Your Signal number
SIGNAL_CLI_PATH=signal-cli       # Path to signal-cli binary
SIGNAL_CONFIG_DIR=~/.local/share/signal-cli  # signal-cli config directory
DATABASE_PATH=./data/bot.db      # SQLite database path
PORT=5000                        # HTTP server port

Installation

pnpm install
pnpm build
pnpm start

Development

pnpm dev

Security

• Admin Room Trust: Anyone in an admin space is trusted to run commands
• Bind Requirement: To bind an existing room, the bot must be a member of that room
• Space Isolation: Each admin space can only manage its own bound rooms
• Room Uniqueness: A room can only be bound to one admin space at a time

Workflow Example

1. Create a Space: DM the bot with !new My Community
2. Create Rooms: In the admin space, use !create General Chat
3. Discover Rooms: Users can run !rooms in any bound room to get a DM with the room list
4. Query Spaces: Users can DM the bot with !space <space-id> to see available rooms