HamAlert Discord Bot
Monitor HamAlert telnet feeds and forward amateur radio spot notifications to Discord webhooks
Features
Real-time Monitoring
Connects to HamAlert telnet feeds for instant spot notifications with automatic reconnection and exponential backoff.
SOTA & POTA Support
Special formatting for Summits on the Air and Parks on the Air with emoji indicators and enhanced information display.
QRZ Integration
Automatic callsign lookup with QRZ.com integration, combining operator first names with callsigns to create clickable links to QRZ pages.
Rate Limiting
Built-in Discord webhook rate limiting (30 messages/minute) to comply with API limits and prevent blocking.
Smart Caching
24-hour QRZ data caching with automatic cleanup to minimize API calls and improve response times.
Health Monitoring
Optional Uptime Kuma integration for service health monitoring and alerting when the bot goes offline.
Setup & Configuration
Clone Repository
git clone https://github.com/sonyccd/hamalert-discord.git
cd hamalert-discordInstall Dependencies
pip install -r requirements.txtConfigure Environment
# Required settings
export USERNAME="YOUR_HAMALERT_USERNAME"
export PASSWORD="YOUR_HAMALERT_PASSWORD"
export WEBHOOK_URL="YOUR_DISCORD_WEBHOOK_URL"
# Optional QRZ integration
export QRZ_USERNAME="YOUR_QRZ_USERNAME"
export QRZ_PASSWORD="YOUR_QRZ_PASSWORD"
# Optional monitoring
export UPTIMEKUMA_URL="YOUR_UPTIME_KUMA_PUSH_URL"
export HEARTBEAT_INTERVAL="300"Run the Bot
python app.pyConfiguration Options
| Environment Variable | Command Line | Description | Required |
|---|---|---|---|
USERNAME |
--username |
HamAlert username | ✅ |
PASSWORD |
--password |
HamAlert password | ✅ |
WEBHOOK_URL |
--webhook |
Discord webhook URL | ✅ |
QRZ_USERNAME |
--qrz-username |
QRZ.com username for callsign lookups | ❌ |
QRZ_PASSWORD |
--qrz-password |
QRZ.com password | ❌ |
UPTIMEKUMA_URL |
--heartbeat-url |
Uptime Kuma push URL | ❌ |
HEARTBEAT_INTERVAL |
--heartbeat-interval |
Heartbeat interval in seconds (default: 300) | ❌ |
LOG_LEVEL |
--log-level |
Logging level: DEBUG, INFO, WARNING, ERROR (default: INFO) | ❌ |
Docker Deployment
Quick Start with Docker
Deploy the bot quickly using Docker with all dependencies included:
Build and Run
# Build the image
docker build -t hamalert-discord .
# Run with environment variables
docker run -e USERNAME=your_username \
-e PASSWORD=your_password \
-e WEBHOOK_URL=your_webhook_url \
-e QRZ_USERNAME=your_qrz_username \
-e QRZ_PASSWORD=your_qrz_password \
-e LOG_LEVEL=INFO \
hamalert-discordDocker Compose
version: '3.8'
services:
hamalert-discord:
build: .
environment:
- USERNAME=${USERNAME}
- PASSWORD=${PASSWORD}
- WEBHOOK_URL=${WEBHOOK_URL}
- QRZ_USERNAME=${QRZ_USERNAME}
- QRZ_PASSWORD=${QRZ_PASSWORD}
- UPTIMEKUMA_URL=${UPTIMEKUMA_URL}
- LOG_LEVEL=${LOG_LEVEL:-INFO}
restart: unless-stopped