Valjean

A smart Telegram & Zalo bot powered by OpenAI that provides AI-powered conversation and evaluation capabilities with context awareness, rate limiting, and content moderation.

✨ Features

• 🤖 OpenAI Integration: Uses GPT-4 for intelligent responses
• 💬 Context Awareness: Maintains conversation context through reply messages
• 🚦 Rate Limiting: Prevents spam and manages usage quotas
• 🛡️ Content Moderation: Built-in content filtering and safety checks
• 📱 Flexible Triggers: Responds to mentions, prefixes, or direct replies
• 🏗️ Clean Architecture: Uses dependency injection with Uber FX
• 🚀 Webhook Support: Efficient real-time message processing
• 🌐 Multi-Channel: Unified handling for Telegram and Zalo conversations
• ⚡ High Performance: Concurrent message handling with proper synchronization

🚀 Getting Started

Prerequisites

• Go 1.24 or higher
• Telegram Bot Token (from @BotFather)
• Zalo Official Account token and webhook secret
• OpenAI API Key

📦 Installation

# Clone the repository
git clone https://github.com/nduyhai/valjean.git
cd valjean

# Install dependencies
go mod tidy

# Build the project
go build ./cmd/bot

⚙️ Configuration

Create a .env file or set environment variables:

# Telegram Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_BOT_USERNAME=your_bot_username
TELEGRAM_WEBHOOK_SECRET=your_webhook_secret
TELEGRAM_REQUIRED_MENTION=true

# Zalo Configuration
ZALO_BOT_TOKEN=your_zalo_oa_token
ZALO_BOT_USERNAME=your_zalo_display_name
ZALO_WEBHOOK_SECRET=your_zalo_webhook_secret

# OpenAI Configuration
OPENAI_KEY=your_openai_api_key

# HTTP Server
HTTP_PORT=8080

🏃 Running the Bot

Local Development

make run

Using Docker

docker build -t valjean .
docker run -p 8080:8080 --env-file .env valjean

🌐 Webhook Setup

Deploy the service with HTTPS and configure the Telegram webhook:

# Set webhook URL
curl -X POST \
 "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook?url=https://YOUR.DOMAIN/telegram/webhook/$WEBHOOK_SECRET"

Configure the Zalo webhook with the /zl/webhook endpoint:

curl -X POST "https://openapi.zalo.me/v3.0/oa/webhook" \
  -H "access_token: $ZALO_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "oaid": "YOUR_OFFICIAL_ACCOUNT_ID",
    "callback_url": "https://YOUR.DOMAIN/zl/webhook",
    "secret_key": "YOUR_WEBHOOK_SECRET"
  }'

🎯 Usage

The bot responds to messages in several ways:

1. Direct Mention: @your_bot_username Hello!
2. Reply to Bot: Reply to any bot message for continued conversation
3. Private Messages: All messages in private chats

Zalo Official Account subscribers are supported through the configured webhook and receive the same evaluation experience.

Example Conversations

User: @valjean What is artificial intelligence?
Bot: Artificial intelligence (AI) refers to the simulation of human intelligence...

🏗️ Project Structure

valjean/
├── cmd/bot/                    # Application entry point
├── internal/
│   ├── adapters/              # External integrations
│   │   ├── http/              # HTTP handlers
│   │   ├── llm/openai/        # OpenAI client
│   │   ├── limiter/           # Rate limiting
│   │   └── producer/          # Message producers for Telegram & Zalo
│   ├── app/                   # Business logic
│   │   ├── entities/          # Domain entities
│   │   ├── service/           # Domain services
│   │   └── usecase/           # Application use cases
│   ├── infra/                 # Infrastructure
│   │   ├── config/            # Configuration
│   │   ├── fxmodules/         # Dependency injection modules
│   │   └── httpserver/        # HTTP server setup
│   └── ports/                 # Interface definitions
├── docs/                      # Documentation
├── Dockerfile                 # Container configuration
└── Makefile                   # Build automation

🔧 Configuration Options

Environment Variable	Default	Description
TELEGRAM_BOT_TOKEN	-	Your Telegram bot token
TELEGRAM_BOT_USERNAME	valjean	Bot username for mentions
TELEGRAM_WEBHOOK_SECRET	-	Secret for webhook security
TELEGRAM_REQUIRED_MENTION	true	Require @mention in groups
OPENAI_KEY	-	OpenAI API key
ZALO_BOT_TOKEN	-	Zalo Official Account access token
ZALO_BOT_USERNAME	valjean	Display name used for Zalo responses
ZALO_WEBHOOK_SECRET	-	Secret for validating Zalo webhook requests
ZALO_BLOCKED_USERS	-	Optional list of blocked Zalo user IDs
ZALO_ALLOWED_USERS	-	Optional list of allowed Zalo user IDs
HTTP_PORT	8080	HTTP server port

🛠️ Development

Setting

# set webhook
curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://YOUR.DOMAIN/telegram/webhook/SECRET",
    "secret_token": "YOUR_HEADER_SECRET"
  }'

# check
curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getWebhookInfo" | jq

# delete
curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/deleteWebhook"


# name
curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setMyName" \
  -d "name=Valjean"

# short description (shown in profiles)
curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setMyShortDescription" \
  --data-urlencode "short_description=Reply-and-tag me to analyze messages."

# long description (shown on /start)
curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setMyDescription" \
  --data-urlencode "description=I analyze the message you replied to when you tag me in groups."

Group Privacy Mode (ON/OFF) → must use @BotFather → Bot Settings → Group Privacy → Turn off (Required if you want the bot to trigger on mentions like @YourBot.)

Running Tests

make test

Linting

make lint

Building

make build

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Telegram Bot API for bot functionality
• OpenAI for AI capabilities
• Uber FX for dependency injection