RelayKit

Language: English · Русский

RelayKit is a template for a two-way bridge between MAX and Telegram bots.

Contents

• What this project is
• Highlights
• Use cases
• How it works
• Architecture
• Quick start
• Configuration
• Webhooks
• Deployment notes
• Security notes
• Limitations
• License

What this project is

This repository gives you a clean baseline for linking users across MAX and Telegram, then relaying messages in both directions.

Use it when you need a bridge that is easy to deploy and easy to modify.

Highlights

• Two-way relay: Telegram → MAX and MAX → Telegram
• One-time linking code (CODE-XXXXXX)
• Text and common media forwarding
• Webhook secret validation for both providers
• Loop protection through relay deduplication
• Retry logic for delayed media on MAX
• Service endpoints:
  • GET /health
  • GET /admin/links (requires X-Admin-Token)

Use cases

• Internal bot integrations across MAX and Telegram
• MVPs that need cross-platform messaging
• Small deployments that do not need a queue yet

How it works

flowchart LR
    A[MAX user starts bot] --> B[Send Telegram ID in MAX]
    B --> C[RelayKit creates one-time code]
    C --> D[User sends code to Telegram bot]
    D --> E[Telegram webhook validates code]
    E --> F[Link stored in PostgreSQL]
    F --> G[Two-way relay enabled]

Loading

Architecture

flowchart TB
    TG[Telegram API] --> TGW[/webhooks/telegram/]
    MX[MAX API] --> MXW[/webhooks/max/]
    TGW --> APP[FastAPI]
    MXW --> APP
    APP --> SVC[Bridge services]
    SVC --> DB[(PostgreSQL)]
    APP --> ADMIN[/admin/links/]
    APP --> HEALTH[/health/]

Loading

Project layout:

.
├── app/
│   ├── api/           # webhooks, health, admin endpoints
│   ├── services/      # relay orchestration and provider clients
│   ├── repositories/  # database access
│   ├── models/        # SQLAlchemy models
│   └── core/          # config and logging
├── alembic/           # migrations
├── deploy/nginx/      # reverse proxy config
├── scripts/           # webhook setup scripts
├── docker-compose.yml
└── .env.example

Quick start

cp .env.example .env
# fill .env with your values

docker compose up -d --build

Health check:

curl -k https://YOUR_PUBLIC_DOMAIN/health

Configuration

Main variables (full list in .env.example):

Variable	Purpose
DATABASE_URL	PostgreSQL connection string
ADMIN_TOKEN	Token for /admin/links
TELEGRAM_BOT_TOKEN	Telegram bot token
TELEGRAM_WEBHOOK_SECRET	Telegram webhook secret
MAX_API_BASE	Base URL of MAX API
MAX_BOT_TOKEN	MAX bot token
MAX_WEBHOOK_SECRET	MAX webhook secret
LINK_CODE_TTL_SECONDS	Link code expiration window
MEDIA_RETRY_ATTEMPTS	Media retry attempts
MEDIA_RETRY_INITIAL_WAIT_SECONDS	Initial retry delay

Webhooks

Telegram

./scripts/set_telegram_webhook.sh "$TELEGRAM_BOT_TOKEN" "https://YOUR_PUBLIC_DOMAIN" "$TELEGRAM_WEBHOOK_SECRET"

MAX

./scripts/set_max_webhook.sh \
  "$MAX_API_BASE" \
  "$MAX_BOT_TOKEN" \
  "https://YOUR_PUBLIC_DOMAIN" \
  "$MAX_WEBHOOK_SECRET"

Deployment notes

• Run behind TLS.
• Make sure webhook URLs are publicly reachable.
• Restrict access to /admin/links.

Security notes

• Do not commit .env or real secrets.
• Rotate bot tokens and webhook secrets before production rollout.
• Keep ADMIN_TOKEN long and random.

Limitations

• No external queue by default.
• Media relay can need provider-specific tuning in edge cases.

License

MIT. See LICENSE.