matrix-quotes-bot/README.md

🎃 Ancestor Quote Bot

A Matrix chatbot that responds to !quote commands with random quotes from Darkest Dungeons.

Quick Start

# 1. Update .env file (create from template)
cp .env.example .env
nano .env  # Edit MATRIX_ACCESS_TOKEN and MATRIX_HOME_SERVER

# 2. Build Docker image
docker build -t ancestor-quote-bot .

# 3. Run the bot
docker run --rm \
  -e MATRIX_HOME_SERVER=https://matrix.org \
  -e MATRIX_ACCESS_TOKEN=your_access_token_here \
  ancestor-quote-bot

Deployment Options

Option A: Pass env vars via docker run (Recommended)

docker run --rm \
  -e MATRIX_HOME_SERVER=https://matrix.org \
  -e MATRIX_ACCESS_TOKEN=your_access_token_here \
  -e BOT_COMMAND=!quote \
  ancestor-quote-bot

Option B: Mount .env file directly

docker run --rm \
  -v $(pwd)/.env:/app/.env \
  ancestor-quote-bot

Configuration

Variable	Description	Default
MATRIX_HOME_SERVER	Matrix homeserver URL (e.g., https://matrix.org)	https://matrix.org
MATRIX_ACCESS_TOKEN	Bot access token for authentication	REQUIRED
BOT_COMMAND	Command trigger to request a quote	!quote

Getting an Access Token

1. Go to Matrix Registration API
2. Or use your Matrix admin panel to create a bot account
3. Get the access token from your Matrix settings

How It Works

1. The bot connects to your Matrix homeserver using the provided access token
2. Once joined to a room, it listens for messages containing the trigger command
3. When triggered, it selects a random quote from quotes.json and replies instantly

Usage

# Invite the bot to a room:
# @ancestor-quote-bot:matrix.org (or your custom username)

# In any Matrix room, type:
!quote

# Bot responds with:
"Dispatch this thug in brutal fashion, that all may hear of your arrival!"

License

ISC