TeLLMgramBot 2.1.0

OpenAI GPT, driven by Telegram

TeLLMgramBot

The basic goal of this project is to create a bridge between a Telegram Bot and a Large Langage Model (LLM), like OpenAI's GPT 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 Telgram group, the bot must be adminstrator 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 another GPT model, preferably GPT-5 or GPT-4o, 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 boadloads 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.

Directories

When initializing TeLLMgramBot, the following directories get created:

• configs - Contains bot configuration files.
  • commands.txt
    • Users can type /help interacting with the to see this file's text get displayed in Telegram.
  • config.yaml (can be a different name)
    • This file sets main OpenAI parameters like naming and GPT models to process.
    • The parameter url_model is to read URL content, different than chat_model that the bot normally uses to interact with the user.
    • An empty token_limit would do the maximum amount of tokens supported by the chat_model (e.g. 128000 for gpt-4o-mini).
  • tokenGPT.yaml
    • This important YAML file contains token size parameters for supported OpenAI models.
    • If the first time, gpt-5, gpt-5-mini, gpt-5-nano, gpt-4o, and gpt-4o-mini get populated, but the user can specify more models with token size parameters as needed.
• prompts - Contains prompt files for how the bot interacts with any user.
  • test_personality.prmpt
    • This is a sample prompt file as a basis to test this library.
    • The user can create more prompt files as needed for different personalities. See OpenAI Playground to test some ideas.
  • url_analysis.prmpt
    • This is a crucial prompt file to analyze URL content in brackets [] in a different model (such as gpt-4o or gpt-4.1).
• 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 current directory execution run path.

API Keys

To operate TeLLMgramBot, three API keys are required:

• OpenAI - Drives the actual GPT AI.
• Telegram - Offers a Bot API through BotFather for the messaging platform.
• VirusTotal - Performs safety checks on URLs.

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

Environment Variables

TeLLMgramBot uses the following environment variables that can be pre-loaded with the three API keys respectively:

1. TELLMGRAMBOT_OPENAI_API_KEY
2. TELLMGRAMBOT_TELEGRAM_API_KEY
3. 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['GPTKey']
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 three files by the base path during execution or a specified environment variable TELLMGRAMBOT_KEYS_PATH. By default, three files are created for the user to input each API key:

1. openai.key
2. telegram.key
3. virustotal.key

Each file with the associated API key will update its respective environment variable if not defined.

Bot Setup

This library includes an example script test_local.py, which uses files from the folders configs and prompts for TeLLMgramBot to process. The bot communicates with OpenAI via the Responses API, which replaces the older Chat Completions endpoint.

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:

   telegram_bot = TeLLMgramBot.TelegramBot(
       bot_username   = <Bot username like 'friendly_bot'>,
       bot_owner      = <Bot owner's Telegram username>,
       bot_name       = <Bot name like 'Friendly Bot'>,
       bot_nickname   = <Bot nickname like 'Botty'>,
       bot_initials   = <Bot initials like 'FB'>,
       chat_model     = <Conversation model like 'gpt-4o-mini'>,
       url_model      = <URL analysis model like 'gpt-4o'>,
       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. Typing /help shows all available commands reported by the configs/commands.txt file.
6. Only as owner, type /start directly to the bot to initiate user conversations.

Resources

• GitHub repository python-telegram-bot has guides to create a Telegram bot.
• For more information on OpenAI models like gpt-4o and token limits, see the following:
  • OpenAI model overview and maximum tokens.
  • OpenAI message conversion to tokens.
  • OpenAI custom fine-tuning.
  • OpenAI's tiktoken library, including some helpful guides.
• OpenAI Playground is a great place to test out prompts and responses.