Telecord

Telegram bot that notifies in a group chat when:

• Someone starts streaming in a Discord server
• Multiple people start playing the same game

Notifications include clickable deep links that open the Discord app:

• Stream notifications: Links directly to the voice channel where the stream is happening
• Same game notifications: Links to the voice channel when all players are together

Setup

1. Install dependencies (requires uv):

   uv sync --dev

2. Create a Discord Bot:

   • Go to Discord Developer Portal
   • Create a new application and enable bot
   • Enable privileged intents: Presence Intent, Server Members Intent
   • Copy the bot token

3. Create a Telegram Bot:

   • Message @BotFather on Telegram
   • Create a new bot with /newbot
   • Copy the bot token

4. Get your Telegram Chat ID:

   • Message @userinfobot on Telegram
   • Get your numeric chat ID

5. Configure environment variables:

   cp .env.example .env
   # Edit .env with your tokens and IDs

   For Docker, either create a .env file (used by docker-compose) or pass environment variables directly.

6. (Optional) Customize notification formats:

   cp config.example.yaml config.yaml
   # Edit config.yaml to customize notification templates

   See CONFIG.md for details on customizing notification messages.

7. Invite the Discord bot to your server with the OAuth2 URL generator in the Developer Portal:

   • Scope: bot
   • Permissions: View Channels

Running

Direct (with uv)

uv run telecord
uv run telecord --debug  # Enable debug logging

Docker

# Build and run with docker-compose
docker-compose up -d

# Or build manually
docker build -t telecord .

# Run with environment variables (all required)
docker run -d \
  -e DISCORD_TOKEN="your_discord_token" \
  -e TELEGRAM_TOKEN="your_telegram_token" \
  -e TELEGRAM_CHAT_ID="123456789" \
  -e DISCORD_GUILD_ID="123456789" \
  telecord

# Optional: Override defaults
docker run -d \
  -e DISCORD_TOKEN="your_discord_token" \
  -e TELEGRAM_TOKEN="your_telegram_token" \
  -e TELEGRAM_CHAT_ID="123456789" \
  -e DISCORD_GUILD_ID="123456789" \
  -e MIN_SAME_GAME_THRESHOLD=3 \
  -e MIN_STREAM_DURATION_SECONDS=120 \
  -e STREAM_RESTART_GRACE_PERIOD_SECONDS=600 \
  telecord

# Optional: Mount custom config.yaml for notification templates
docker run -d \
  -e DISCORD_TOKEN="your_discord_token" \
  -e TELEGRAM_TOKEN="your_telegram_token" \
  -e TELEGRAM_CHAT_ID="123456789" \
  -e DISCORD_GUILD_ID="123456789" \
  -v ./config.yaml:/app/config.yaml:ro \
  telecord

Development

# Format code
uv run ruff check .

# Run tests
uv run pytest

Configuration

Environment Variables

Variable	Required	Default	Description
DISCORD_TOKEN	Yes	-	Discord bot token
TELEGRAM_TOKEN	Yes	-	Telegram bot token
TELEGRAM_CHAT_ID	Yes	-	Telegram chat ID to send notifications to
TELEGRAM_TOPIC_ID	No	-	Telegram topic ID (for group chats with topics)
DISCORD_GUILD_ID	Yes	-	Discord server ID to monitor
MIN_SAME_GAME_THRESHOLD	No	2	Minimum users playing same game to trigger notification
MIN_STREAM_DURATION_SECONDS	No	60	Minimum stream duration before notifying
STREAM_RESTART_GRACE_PERIOD_SECONDS	No	300	Grace period to avoid duplicate notifications

Notification Templates

You can customize notification message formats by creating a config.yaml file. See CONFIG.md for full documentation.