mirror of
https://github.com/HugeFrog24/go-telegram-bot.git
synced 2026-06-29 22:07:12 +00:00
HugeFrog24
165 lines
5.4 KiB
Markdown
165 lines
5.4 KiB
Markdown
# Go Telegram Multibot
|
|
|
|
A scalable, multi-bot solution for Telegram using Go, GORM, and the Anthropic API.
|
|
|
|
## Design Considerations
|
|
|
|
- AI-powered (Anthropic Claude)
|
|
- Voice message support (ElevenLabs STT + TTS) — optional, enabled per bot via config
|
|
- Supports multiple bot profiles
|
|
- Uses SQLite for persistence
|
|
- Implements rate limiting and user management
|
|
- Modular architecture
|
|
- Comprehensive unit tests
|
|
|
|
## Usage
|
|
|
|
### Docker Deployment (Recommended)
|
|
|
|
1. Clone the repository:
|
|
|
|
```bash
|
|
git clone https://github.com/HugeFrog24/go-telegram-bot.git
|
|
cd go-telegram-bot
|
|
```
|
|
|
|
2. Copy the default config template and edit it:
|
|
```bash
|
|
cp config/default.json config/mybot.json
|
|
nano config/mybot.json
|
|
```
|
|
|
|
> [!IMPORTANT]
|
|
> Keep your config files secret and do not commit them to version control.
|
|
|
|
3. Create data directory and run:
|
|
```bash
|
|
mkdir -p data
|
|
docker-compose up -d
|
|
```
|
|
|
|
### Native Deployment
|
|
|
|
1. Install using `go get`:
|
|
|
|
```bash
|
|
go get -u github.com/HugeFrog24/go-telegram-bot
|
|
cd go-telegram-bot
|
|
```
|
|
|
|
2. Configure as above, then build:
|
|
```bash
|
|
go build -o telegram-bot
|
|
```
|
|
|
|
## Trying Out New Behavior Safely
|
|
|
|
Want to experiment with a different personality, tone, or set of instructions without disturbing the bot your users already talk to? Run a second, separate bot just for testing.
|
|
|
|
Each bot profile is its own config file with its own Telegram token, and bots are fully independent — separate identity, separate chat history, separate settings. So a "test twin" is quick to set up:
|
|
|
|
1. Create a new bot with [@BotFather](https://t.me/BotFather) and copy its token.
|
|
2. Copy your existing config to a new file, e.g. `cp config/mybot.json config/mybot-test.json`.
|
|
3. In the new file, paste the new token, give it a different `id`, and edit `system_prompts` to try your changes.
|
|
4. Start it alongside your main bot. Chat with the test bot, tweak its prompt, and restart the test bot to try again — your real users never see the experiments.
|
|
5. Happy with the result? Copy the same change into your main bot's config and restart it.
|
|
|
|
> [!NOTE]
|
|
> A test bot always needs its **own** token. Telegram only lets one running bot listen on a given token, so you can't point a second copy at your live bot — give the twin its own @BotFather bot instead.
|
|
|
|
## Systemd Unit Setup
|
|
|
|
To enable the bot to start automatically on system boot and run in the background, set up a systemd unit.
|
|
|
|
1. Copy the systemd unit template and edit it:
|
|
|
|
```bash
|
|
sudo cp examples/systemd/telegram-bot.service /etc/systemd/system/telegram-bot.service
|
|
```
|
|
|
|
Edit the service file:
|
|
|
|
```bash
|
|
sudo nano /etc/systemd/system/telegram-bot.service
|
|
```
|
|
|
|
Adjust the following parameters:
|
|
|
|
- WorkingDirectory
|
|
- ExecStart
|
|
- User
|
|
|
|
2. Enable and start the service:
|
|
|
|
```bash
|
|
sudo systemctl daemon-reload
|
|
```
|
|
|
|
```bash
|
|
sudo systemctl enable telegram-bot
|
|
```
|
|
|
|
```bash
|
|
sudo systemctl start telegram-bot
|
|
```
|
|
|
|
3. Check the status:
|
|
|
|
```bash
|
|
sudo systemctl status telegram-bot
|
|
```
|
|
|
|
For more details on the systemd setup, refer to the [demo service file](examples/systemd/telegram-bot.service).
|
|
|
|
## Logs
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
docker-compose logs -f telegram-bot
|
|
```
|
|
|
|
### Systemd
|
|
|
|
```bash
|
|
journalctl -u telegram-bot -f
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Command | Access | Description |
|
|
| --------------------------------- | ----------- | ------------------------------------------------------------ |
|
|
| `/stats` | All users | Show global bot statistics (total users and messages) |
|
|
| `/stats user` | All users | Show your own message statistics |
|
|
| `/stats user <user_id>` | Admin/Owner | Show statistics for a specific user |
|
|
| `/whoami` | All users | Show your Telegram ID, username, and role |
|
|
| `/clear` | All users | Soft-delete your own chat history |
|
|
| `/clear <user_id>` | Admin/Owner | Soft-delete all messages for a user across every chat |
|
|
| `/clear <user_id> <chat_id>` | Admin/Owner | Soft-delete a user's messages in a specific chat |
|
|
| `/clear_hard` | All users | Permanently delete your own chat history |
|
|
| `/clear_hard <user_id>` | Admin/Owner | Permanently delete all messages for a user across every chat |
|
|
| `/clear_hard <user_id> <chat_id>` | Admin/Owner | Permanently delete a user's messages in a specific chat |
|
|
| `/set_model <model-id>` | Admin/Owner | Switch the AI model live without restarting |
|
|
|
|
> **Note:** In private DMs each user's `chat_id` equals their `user_id`. The scoped `<chat_id>` form is mainly useful for group chat moderation.
|
|
|
|
## Testing
|
|
|
|
The GitHub actions workflow already runs tests on every commit:
|
|
|
|
> [](https://github.com/HugeFrog24/go-telegram-bot/actions/workflows/go-ci.yaml)
|
|
|
|
However, you can run the tests locally using:
|
|
|
|
```bash
|
|
go test -race -v ./...
|
|
```
|
|
|
|
## Storage
|
|
|
|
At the moment, a SQLite database (`./data/bot.db`) is used for persistent storage.
|
|
|
|
Remember to back it up regularly.
|
|
|
|
Future versions will support more robust storage backends.
|