TeLLMgramBot 2.5.1

LLM-powered Telegram bot (OpenAI + Anthropic)

TeLLMgramBot

The basic goal of this project is to create a bridge between a Telegram Bot and a Large Language Model (LLM), supporting both OpenAI's GPT models and Anthropic's Claude models.

• To use this library, you must have a Telegram account with a user name, not just a phone number. If you don't have one, create one online.
• If added to a Telegram group, the bot must be administrator in order to respond to a user calling out its name, initials, or nickname.

Telegram Bot + LLM Encapsulation

• The Telegram interface handles special commands, especially on some basic "chatty" prompts and responses that don't require LLM, like "Hello".
• The more dynamic conversation gets handed off to the LLM to manage prompts and responses, and Telegram acts as the interaction broker.
• Pass the URL in [square brackets] and mention how the bot should interpret it.
  • Example: "What do you think of this article? [https://some_site/article]"
  • This uses a separate model (configurable via url_model) to support more URL content with its higher token limit.
• Tokens are used to measure the length of all conversation messages between the Telegram bot assistant and the user. This is useful to:
  • Ensure the length does not go over the model limit. If it does, prune oldest messages to fit within the limit.
  • Remember 50% of the past conversations when starting up TeLLMgramBot again.
• Users can also clear their conversation history for privacy.

Why Telegram?

Using Telegram as the interface not only solves "exposing" the interface, but gives you boatloads of interactivity over a standard Command Line interface, or trying to create a website with input boxes and submit buttons to try to handle everything:

1. Telegram already lets you paste in verbose, multiline messages.
2. Telegram already lets you paste in pictures, videos, links, etc.
3. Telegram already lets you react with emojis, stickers, etc.

Supported LLM Providers

TeLLMgramBot selects the LLM provider automatically based on the model name:

Model prefix	Provider	Example models
gpt-	OpenAI	gpt-4o, gpt-4o-mini, gpt-5-mini
claude-	Anthropic	claude-sonnet-4-6, claude-haiku-4-5

Simply set chat_model (and optionally url_model) in your config.yaml to any supported model and supply the corresponding API key — no other changes needed.

Directories

When initializing TeLLMgramBot, the following directories get created:

• configs - Contains bot configuration files.
  • config.yaml (can be a different name)
    • This file sets main bot parameters like naming and the LLM models to use.
    • chat_model — the model used for normal conversation (e.g. gpt-5-mini or claude-sonnet-4-6).
    • url_model — the model used to read and summarize URL content, can differ from chat_model.
    • An empty token_limit will use the maximum tokens supported by the chat_model.
  • tokenGPT.yaml
    • Contains token size parameters for all supported models.
    • On first run, GPT and Claude model families are pre-populated. Additional models can be added manually.
• prompts - Contains prompt files for how the bot interacts with any user.
  • test_personality.prmpt (can be a different name)
    • A sample prompt file defining the bot's personality: generic, helpful, and multi-provider-aware.
    • The prompt emphasizes the bot's ability to fetch and analyze URLs passed in square brackets [].
    • The user can create more prompt files as needed for different personalities.
  • url_analysis.prmpt
    • Prompt template used to analyze URL content passed in brackets [].
• errorlogs
  • Contains a tellmgrambot_error.log file to investigate if there are problems during the interaction.
  • User will also get notified to contact the owner.
• sessionlogs
  • Every conversation is stored between the Telegram bot assistant and each user.
  • If a user types /forget, any session log files between the bot and the user will all be removed.

Environment Variables

TeLLMgramBot also creates or utilizes the following environment variables that can be pre-loaded especially in other operating systems like Home Assistant, having different configurations for persistent storage:

1. TELLMGRAMBOT_CONFIGS_PATH
2. TELLMGRAMBOT_PROMPTS_PATH
3. TELLMGRAMBOT_ERRORLOGS_PATH
4. TELLMGRAMBOT_SESSIONLOGS_PATH

If neither of these are defined, the initialization would use the top-level execution run directory.

API Keys

TeLLMgramBot supports the following API keys:

• OpenAI — required when using a gpt-* model. Missing: chat and URL analysis disabled.
• Anthropic — required when using a claude-* model. Missing: chat and URL analysis disabled.
• Telegram — always required; offers a Bot API through BotFather. Missing: bot will not start.
• VirusTotal — performs safety checks on URLs. Missing: URL analysis disabled.

If a provider API key matching your configured model is missing, the bot will start but disable chat and URL analysis features. A startup summary will show which features are enabled.

There are two ways to populate each API key: environment variables or .key files.

Environment Variables

TeLLMgramBot uses the following environment variables for API keys:

1. TELLMGRAMBOT_OPENAI_API_KEY (OpenAI models)
2. TELLMGRAMBOT_ANTHROPIC_API_KEY (Anthropic models)
3. TELLMGRAMBOT_TELEGRAM_API_KEY
4. TELLMGRAMBOT_VIRUSTOTAL_API_KEY

During spin-up time, a user can call out os.environ[env_var] to set those variables, like the following example:

my_keys = Some_Vault_Fetch_Function()

os.environ['TELLMGRAMBOT_OPENAI_API_KEY']     = my_keys['OpenAIKey']
os.environ['TELLMGRAMBOT_ANTHROPIC_API_KEY']  = my_keys['AnthropicKey']
os.environ['TELLMGRAMBOT_TELEGRAM_API_KEY']   = my_keys['BotFatherToken']
os.environ['TELLMGRAMBOT_VIRUSTOTAL_API_KEY'] = my_keys['VirusTotalToken']

This means the user can implement whatever key vault they want to fetch the keys at runtime, without needing files stored in the directory.

API Key Files

The other route is to create files by the base path during execution or a specified environment variable TELLMGRAMBOT_KEYS_PATH. By default, files are created for the user to input each API key:

1. openai.key — OpenAI API key for GPT models
2. anthropic.key — Anthropic API key for Claude models
3. telegram.key — Telegram Bot API key
4. virustotal.key — VirusTotal API key for URL safety checks

Each file with the associated API key will update its respective environment variable if not defined. Missing provider keys (OpenAI or Anthropic) will disable chat and URL analysis but allow the bot to start. Missing VirusTotal keys will disable URL analysis.

Bot Setup

This library includes an example script test_local.py, which uses files from the folders configs and prompts for TeLLMgramBot to process.

1. Ensure the previous sections are followed with the proper API keys and your Telegram bot set.
2. Install this library via PIP (pip install TeLLMgramBot) and then import into your project.
3. Instantiate the bot by passing in various configuration pieces needed below. Note the Telegram bot's full name and username auto-populate before startup.

   telegram_bot = TeLLMgramBot.TelegramBot(
       bot_owner      = <Bot owner's Telegram username>,
       bot_nickname   = <Bot nickname like 'Botty'>,
       bot_initials   = <Bot initials like 'FB'>,
       chat_model     = <Conversation model like 'gpt-4o-mini' or 'claude-sonnet-4-6'>,
       url_model      = <URL analysis model like 'gpt-4o' or 'claude-haiku-4-5'>,
       token_limit    = <Maximum token count set, by default chat_model max>,
       persona_temp   = <LLM factual to creative value [0-2], by default 1.0>,
       persona_prompt = <System prompt summarizing bot personality>
   )
   

4. Turn on TeLLMgramBot by calling:

   telegram_bot.start_polling()
   

   Once you see TeLLMgramBot polling..., the bot is online in Telegram.
5. Converse! Type /help for all available commands.

Resources

• GitHub repository python-telegram-bot has guides to create a Telegram bot.
• For more information on OpenAI models and token limits:
  • OpenAI model overview and maximum tokens
  • OpenAI message conversion to tokens
  • OpenAI custom fine-tuning
  • OpenAI's tiktoken library
• For more information on Anthropic Claude models:
  • Anthropic model overview and context windows
  • Anthropic Python SDK