Skip to main content

Ask Telegram Bot Integration

This guide will help you set up the Ask Telegram bot using Docker.

Features​

  • 🤖 Telegram Bot API - Built on official Telegram Bot API with webhook support
  • 👥 Flexible user management - Optional whitelisting with manual approval or auto-approval modes
  • 🔄 Conversation context - Maintains conversation history with /new command for fresh starts
  • 🗄️ PostgreSQL persistence - Tracks user status, conversation state, and metadata
  • 🐳 Docker-ready - One-command deployment with Docker Compose
  • 🔐 Admin API - Optional REST endpoints for user management and monitoring

Architecture Overview​

The Telegram bot is built with a webhook-based architecture that integrates with the Ask API:

Prerequisites​

  • Docker and Docker Compose installed
  • Ask Agent: Provisioned agent with API key from Ask Platform
  • Telegram Bot Token (from @BotFather)
  • Ask API Key and Agent ID
  • Public URL for webhook (domain with HTTPS)

Installation​

1. Clone the Repository​

git clone https://github.com/ai71-Ask/ask_telegram_bot
cd ask_telegram_bot

2. Configure Environment Variables​

Create a .env file in the root directory with your credentials:

VariableDescriptionDefault
TELEGRAM_BOT_TOKENTelegram bot token from @BotFather-
ASK71_API_KEYYour Ask API key-
ASK71_AGENT_IDYour Ask agent ID-
ASK71_API_URLAsk API endpointhttps://api.ask.dev.ai71services.ai
WEBHOOK_URLPublic URL where bot is hosted-
PORTPort for the webhook server80
DATABASE_URLPostgreSQL connection string (auto-configured in Docker)-
DB_PASSWORDPostgreSQL database password (for Docker)changeme
ALLOW_WHITELISTINGEnable manual user whitelisting via Admin APIfalse
ADMIN_API_KEYAPI key for admin endpointschange-me-in-production

Example .env file:

# Required Configuration
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
ASK71_API_KEY=your_ask71_api_key
ASK71_AGENT_ID=agent_abc123def456
WEBHOOK_URL=https://yourdomain.com

# Optional Configuration (with defaults)
DB_PASSWORD=your_secure_db_password
ALLOW_WHITELISTING=true
ADMIN_API_KEY=your_secure_random_string_here

3. Run with Docker Compose​

Start all services (bot + PostgreSQL):

docker-compose up -d

View logs:

docker-compose logs -f bot

Stop all services:

docker-compose down
warning

Running docker-compose down -v will delete all database data.

The bot will automatically:

  • Set up PostgreSQL database
  • Run database migrations
  • Start the FastAPI webhook server on port 80
  • Configure the Telegram webhook

4. Build Custom Docker Image (Optional)​

If you want to build your own Docker image:

# Build the image
docker build -t your-registry/telegram-ask-bot:latest .

# Push to your registry
docker push your-registry/telegram-ask-bot:latest

# Run the custom image
docker run -d \
  --name telegram-bot \
  --env-file .env \
  -p 80:80 \
  your-registry/telegram-ask-bot:latest

Getting Your Credentials​

Telegram Bot Token​

  1. Open Telegram and search for @BotFather
  2. Send /newbot command
  3. Follow the instructions to create your bot
  4. Copy the token provided

Ask API Key and Agent ID​

  1. Visit the Ask dashboard
  2. Go to Settings → API Keys
  3. Create a new API key
  4. Navigate to Agents section
  5. Create or select an agent and copy its ID

For more details, see the Ask Getting Started Guide.

Usage​

Once the bot is running, users can interact with it using these commands:

  • /start - Register with the bot and start using it
  • /new - Start a new conversation (clears previous context)
  • /help - Show help information and usage instructions

User Flow​

Data Flow:​

  1. User sends a message to the Telegram bot
  2. Telegram servers forward the message to your webhook endpoint
  3. Bot checks user whitelist status in the database
  4. If approved, bot sends the query to Ask API with conversation context
  5. Ask API processes the query through the configured agent
  6. Bot receives the complete response and sends it back to the user via Telegram

Message Processing Flow​