Telegram Summariser Userbot

A Telegram userbot that summarises chat messages using AI.

Features

• Summarise the last N messages in any chat
• Summarise messages since a specific time (since:07:00, since:DD-MM-YYYY_HH:MM)
• Summarise messages from the last N minutes, hours, or days (last:5m, last:2h, last:1d)
• Summarise messages since your last outgoing message (since:lastout), with skip options (since:lastout-2, since:lastout-10m)
• Ask a specific question about the chat content alongside the summary
• Works with any OpenAI-compatible or Anthropic-compatible AI provider
• Customisable system prompt via a plain text file
• Flood limit handling

Setup

Docker (recommended)

Pull the image and run the interactive setup wizard:

docker run -it -v ./data:/app/data m4l3vich/telegram-summariser-userbot setup

The wizard will walk you through:

1. Entering your Telegram API credentials (from https://my.telegram.org/apps)
2. Authenticating your Telegram account
3. Configuring your AI provider and selecting a model
4. Setting optional preferences (language, timezone, prompt file)

Configuration and session data are written to ./data/ on your host. Once setup is complete, start the bot:

docker run -d -v ./data:/app/data m4l3vich/telegram-summariser-userbot

From source

Prerequisites: Node.js 18+, pnpm, Telegram API credentials from https://my.telegram.org/apps, an API key from your chosen AI provider.

git clone <repo-url>
pnpm install
pnpm setup

The setup wizard creates a .env file with your configuration. Then start the bot:

pnpm dev     # development with hot-reload
pnpm start   # production (run pnpm build first)

Manual configuration (without setup wizard)

cp .env.example .env
# Edit .env with your credentials

On first run, the bot will prompt you to authenticate your Telegram account. The session is saved to a SQLite file (default: session.sqlite).

AI Provider Configuration

AI_PROVIDER selects the protocol: openai (OpenAI-compatible) or anthropic. Any provider that implements either protocol works — set AI_BASE_URL to point at its endpoint.

BotHub

AI_PROVIDER=openai
AI_API_KEY=your-bothub-api-key
AI_MODEL=gpt-5-nano
AI_BASE_URL=https://bothub.chat/api/v2/openai/v1

Get an API key at: https://bothub.chat

OpenAI

AI_PROVIDER=openai
AI_API_KEY=sk-...
AI_MODEL=gpt-4o

No AI_BASE_URL needed — defaults to OpenAI's API.

Get an API key at: https://platform.openai.com/api-keys

OpenRouter

AI_PROVIDER=openai
AI_API_KEY=sk-or-...
AI_MODEL=anthropic/claude-sonnet-4-20250514
AI_BASE_URL=https://openrouter.ai/api/v1

Model IDs follow OpenRouter format (provider/model).

Get an API key at: https://openrouter.ai/keys

Anthropic

AI_PROVIDER=anthropic
AI_API_KEY=sk-ant-...
AI_MODEL=claude-sonnet-4-20250514

No AI_BASE_URL needed — defaults to Anthropic's API.

Get an API key at: https://console.anthropic.com/settings/keys

GLM (ZhipuAI)

AI_PROVIDER=openai
AI_API_KEY=your-glm-api-key
AI_MODEL=glm-4-plus
AI_BASE_URL=https://open.bigmodel.cn/api/paas/v4

Get an API key at: https://open.bigmodel.cn

Reasoning effort

For reasoning models (e.g. o3, o4-mini, gpt-5):

AI_REASONING_EFFORT=minimal

Accepted values: minimal, low, medium, high.

Usage

Commands are sent as outgoing messages in any chat.

Command	Description
/summary 100	Summarise the last 100 messages
/summary 50 What was decided about X?	Summarise with a specific question
/summary since:07:00	Messages since 07:00 today
/summary since:11-03-2026_07:00	Messages since a specific date and time
/summary since:lastout	Messages since your last outgoing message
/summary since:lastout-2	Skip 2 outgoing messages, summarise from the 3rd
/summary since:lastout-10m	Since last outgoing message older than 10 min
/summary last:30m	Messages from the last 30 minutes
/summary last:2h	Messages from the last 2 hours
/summary last:1d	Messages from the last day

The bot edits the command message in place as it works, showing a progress indicator, then replaces it with the finished summary.

Environment Variables

Variable	Description	Required	Default
API_ID	Telegram API ID	Yes
API_HASH	Telegram API Hash	Yes
SESSION_FILE	SQLite session file path	No	session.sqlite
AI_PROVIDER	Protocol type: openai or anthropic	Yes
AI_API_KEY	AI provider API key	Yes
AI_MODEL	Model ID	No	gpt-4o
AI_BASE_URL	Provider API base URL	No	OpenAI / Anthropic default
AI_REASONING_EFFORT	Reasoning effort level	No	Not set (provider default)
SUMMARY_LANGUAGE	Language for the summary output	No	English
SUMMARY_TIMEZONE	Timezone used for timestamps	No	Europe/Moscow
PROMPT_FILE	Path to a custom system prompt file	No	prompt.txt

Custom Prompts

The system prompt is loaded from the file specified by PROMPT_FILE (default: prompt.txt). Two template placeholders are available:

• {{ language }} - replaced with the value of SUMMARY_LANGUAGE
• {{ timezone }} - replaced with the value of SUMMARY_TIMEZONE

Example:

Summarise the following chat messages in {{ language }}. Timestamps are in {{ timezone }}.

Docker

# Interactive setup (writes .env + session to ./data/)
docker run -it -v ./data:/app/data m4l3vich/telegram-summariser-userbot setup

# Run the bot
docker run -d -v ./data:/app/data m4l3vich/telegram-summariser-userbot

# Build locally
docker build -t telegram-summariser .
docker run -it -v ./data:/app/data telegram-summariser setup
docker run -d -v ./data:/app/data telegram-summariser

Development

pnpm dev     # Run with hot-reload
pnpm build   # Build for production
pnpm start   # Run production build
pnpm setup   # Run the interactive setup wizard

Project structure:

src/
  index.ts             — Entry point, command handler, summarisation logic
  ai-provider.ts       — AI provider abstraction (OpenAI-compatible / Anthropic)
  fetch-messages.ts    — Message fetching with timestamp/count parsing
  prepare-messages.ts  — Message formatting for the AI model
  setup.ts             — Interactive setup wizard
  utils.ts             — Telegram message editing utilities