Telegram bot for posting VRChat memes to a channel, featuring a suggestion and review system.
- Posts memes directly to a specified Telegram channel (Admin only)
- User Suggestion System: Allows channel subscribers to suggest posts (
/suggest). - Admin Review Queue: Admins can review (
/review), approve, or reject suggestions. - Caption Management: Admins can set (
/caption), view (/showcaption), and clear (/clearcaption) a default caption for subsequent media posts. - Localization: Supports multiple languages (EN, RU) using
go-i18n. - Debug mode for development.
- Error tracking with Sentry (including panic recovery).
- Enhanced error handling with context wrapping.
- Improved logging with contextual information.
- Detailed GoDoc comments throughout the codebase.
- Robust media group handling with rate limit retries.
- Environment-based configuration.
- MongoDB integration for user tracking, post logging, and suggestion storage.
- Docker support (Development & Production environments).
- Hot-reload development mode with Air.
- Unit tests for command handlers.
- CI/CD pipeline with testing and deployment via GitHub Actions.
- Go 1.24 or higher
- Docker & Docker Compose
- Telegram Bot Token
- Sentry DSN (optional, for error tracking)
- Key dependencies:
github.com/mymmrac/telego v1.0.2github.com/getsentry/sentry-go v0.31.1go.mongodb.org/mongo-driver v1.17.3github.com/joho/godotenv v1.5.1(for loading.envfiles)github.com/nicksnyder/go-i18n/v2 v2.6.0github.com/stretchr/testify v1.10.0(for testing)
-
Clone the repository:
git clone https://github.com/yourusername/vrcmemes-bot.git cd vrcmemes-bot -
Copy the example environment file and configure it:
cp .env.example .env
-
Edit
.envfile with your configuration:- Set
TELEGRAM_BOT_TOKEN,CHANNEL_ID. - Set
SENTRY_DSNif you want to use Sentry for error tracking. - Adjust
MONGO_INITDB_ROOT_USERNAMEandMONGO_INITDB_ROOT_PASSWORDif needed (defaults are 'admin'/'password'). - Other variables like
APP_ENV,DEBUG,VERSION,BOT_DEFAULT_LANGUAGEcan be configured as needed. - Note: The
MONGODB_URIis automatically configured for Docker Compose. For manual runs, you'll need to set it appropriately.
# Example .env APP_ENV=development # development, staging, or production DEBUG=true # Enable debug mode VERSION=dev # Application version BOT_DEFAULT_LANGUAGE=en # Default bot language (en, ru) TELEGRAM_BOT_TOKEN=your-bot-token CHANNEL_ID=your-channel-id # Bot will check admin status here & post memes here SENTRY_DSN=your-sentry-dsn-here # Optional # MongoDB Credentials (used by docker-compose.yml) MONGO_INITDB_ROOT_USERNAME=admin MONGO_INITDB_ROOT_PASSWORD=password # MongoDB Connection (usually set for non-docker runs or specific overrides) # MONGODB_URI=mongodb://admin:password@localhost:27017 MONGODB_DATABASE=vrcmemes
- Set
-
Run in Development Mode (with Hot-Reload): This uses
docker-compose.ymlanddocker-compose.override.ymlto run thebuilderstage withairand mounts your local code.docker compose up --build
(Add
-dto run in the background) -
Run in Production Mode: This uses only
docker-compose.ymlto run the final, optimized stage. It builds the production image and does not mount local code.docker compose -f docker-compose.yml up --build -d
-
Stopping the Application:
# If started with 'docker compose up' (dev mode) docker compose down # If started with 'docker compose -f docker-compose.yml up' (prod mode) docker compose -f docker-compose.yml down
-
Clone, install dependencies (
go mod download), and configure.envas described above. EnsureMONGODB_URIpoints to your accessible MongoDB instance. -
Run the application directly:
go run main.go
-
For hot-reload during manual development:
# Make sure air is installed (go install github.com/air-verse/air@latest) air
| Variable | Description | Required | Default |
|---|---|---|---|
APP_ENV |
Application environment (development/staging/production) | No | development |
DEBUG |
Enable debug mode | No | false |
VERSION |
Application version | Yes | - |
BOT_DEFAULT_LANGUAGE |
Default language for the bot (e.g., en, ru) |
No | en |
TELEGRAM_BOT_TOKEN |
Your Telegram bot token | Yes | - |
CHANNEL_ID |
Telegram channel ID where memes will be posted and admin status checked | Yes | - |
SENTRY_DSN |
Sentry DSN for error tracking | No | - |
MONGO_INITDB_ROOT_USERNAME |
MongoDB root username for initialization | No (used by Docker) | admin |
MONGO_INITDB_ROOT_PASSWORD |
MongoDB root password for initialization | No (used by Docker) | password |
MONGODB_URI |
MongoDB connection URI | Yes (for manual run) | - |
MONGODB_DATABASE |
MongoDB database name | Yes | - |
- Admin: Determined by having
creatororadministratorstatus in the Telegram channel specified byCHANNEL_ID. Admins can use all bot commands except/suggestand/feedback. They can post directly, manage captions, and review suggestions (/review). - User/Subscriber: Can use
/start,/help,/suggest, and/feedback. Must be subscribed to the target channel (CHANNEL_ID) to use/suggest.
/start: Start interaction with the bot and get a welcome message./help: Show help information./suggest: Start the process of suggesting a post for the channel. (Requires channel subscription)/feedback: Send feedback or suggestions about the bot to the admins.
/start: Start interaction with the bot and get a welcome message./help: Show help information./status: Show bot status and current caption./version: Show bot version./caption [text]: Set or update the caption to be used for the next direct media post./showcaption: Show the currently active caption./clearcaption: Clear the currently active caption./review: Start reviewing pending suggestions.- (Direct messages): Send photos, videos, or media groups directly to the bot to post them to the channel. Text in the message will be used as the caption unless an active caption is set via
/caption.
- A user subscribes to the channel defined by
CHANNEL_ID. - The user sends
/suggestto the bot. - The bot asks the user to send a photo or a media group (up to 10 photos).
- The user sends the media. The message text is stored as a private comment for the suggestion.
- The bot confirms receipt and stores the suggestion (including media file IDs and comment) in MongoDB with "pending" status.
- An admin (checked via channel status) uses
/review. - The bot presents the oldest pending suggestion (media + comment + submitter info) with Approve/Reject/Next buttons.
- Admin approves: The bot posts the media to the channel (using the suggestion's comment as caption if desired) and updates the suggestion status to "approved".
- Admin rejects: The bot updates the suggestion status to "rejected".
- Admin skips (Next): The bot shows the next pending suggestion.
The bot uses github.com/nicksnyder/go-i18n/v2 for localization. Language files (en.json, ru.json) are located in internal/locales/. The default language is set via the BOT_DEFAULT_LANGUAGE environment variable (defaulting to en in internal/locales/i18n.go).
.
├── bot/ # Core bot logic, Telegram API interaction, update loop
├── internal/
│ ├── auth/ # Admin checking logic
│ ├── config/ # Configuration loading (.env)
│ ├── database/ # MongoDB interaction (connection, models, repository interfaces)
│ ├── handlers/ # Telegram message/command handlers (routing, initial processing)
│ ├── locales/ # Localization files (en.json, ru.json) and i18n setup
│ ├── mediagroups/ # Handling of Telegram media groups
│ └── suggestions/ # Logic for suggestion handling, review process
├── pkg/
│ ├── telegoapi/ # Wrapper/interface for telego BotAPI (for easier mocking)
│ └── utils/ # Utility functions (e.g., Markdown escaping)
├── .github/workflows/ # GitHub Actions workflows (CI/CD)
│ └── deploy.yml
├── .air.toml # Air configuration for hot-reload
├── .env.example # Example environment variables
├── .gitignore # Git ignore rules
├── Dockerfile # Docker build instructions (multi-stage)
├── README.md # This file
├── docker-compose.yml # Docker Compose setup (Production base)
├── docker-compose.override.yml # Docker Compose overrides (Development)
├── go.mod # Go module dependencies
├── go.sum # Go module checksums
└── main.go # Application entry point
See the Installation & Running with Docker section for running in development mode using Docker Compose, which is the recommended approach.
Manual development using go run or air is possible but requires manual setup of dependencies like MongoDB.
The bot uses Sentry for error tracking. Set SENTRY_DSN in your .env file to enable it.
The bot uses MongoDB to store user actions, published post logs, and suggestions. The Docker Compose setup includes a MongoDB service. Database credentials (MONGO_INITDB_ROOT_USERNAME, MONGO_INITDB_ROOT_PASSWORD) and the database name (MONGODB_DATABASE) are configured via .env.
- Multi-stage Build:
Dockerfileuses a builder stage for dependencies/compilation and a minimal final stage for the production image. - Platform Aware: The build automatically detects the target architecture (
amd64,arm64). - Development Environment:
docker compose upusesdocker-compose.override.ymlto run thebuilderstage, mounts local code, and usesairfor hot-reloading. - Production Environment:
docker compose -f docker-compose.yml upuses only the base configuration, builds the final lean image, and runs the compiled binary. - MongoDB Service: Included in Docker Compose for convenience.
- Configuration: Environment variables are loaded from the
.envfile.
This project uses GitHub Actions for testing and basic Continuous Deployment.
- Workflow:
.github/workflows/deploy.yml - Trigger: Pushes to the
developbranch. - Actions:
- Sets up Go.
- Downloads dependencies.
- Builds the project.
- Runs tests (
go test -v ./...). - Connects to the production server via SSH.
- Pulls the latest changes from the
developbranch. - Rebuilds and restarts the Docker containers using
docker-compose up -d --build.
For the deployment workflow to function, the following secrets must be configured in the GitHub repository settings (Settings > Secrets and variables > Actions):
SSH_PRIVATE_KEY: Private SSH key to access the server.SSH_HOST: Hostname or IP address of the server.SSH_USER: Username for SSH connection.SERVER_PROJECT_PATH: Absolute path to the project directory on the server.
MIT