TelegramGPT

Telegram bot for ChatGPT using official OpenAI API. This project is experimental and subject to change.

Features
Get Started
Usage
Advanced Deployment
Options Reference

Features

All the powers of ChatGPT
Voice messages powered by Azure Cognitive Services
Conversation history
Restrict bot to specific chats
Resume previous conversations

Get Started

1. Create a Telegram bot

Create a Telegram bot using @BotFather and get the token.

2. Create an OpenAI API key

Go to OpenAI Dashboard and create an API key.

3. Deploy

Docker:

docker build -t telegram-gpt github.com/zhuorantan/TelegramGPT#main
docker run --rm telegram-gpt --openai-api-key "<OPENAI_API_KEY>" --telegram-token "<TELEGRAM_TOKEN>"

Docker Compose:

services:
  telegram-gpt:
    build: github.com/zhuorantan/TelegramGPT#main
    container_name: telegram-gpt
    restart: unless-stopped
    environment:
      - TELEGRAM_GPT_OPENAI_API_KEY=<OPENAI_API_KEY>
      - TELEGRAM_GPT_TELEGRAM_TOKEN=<TELEGRAM_TOKEN>

The bot will start with the default configuration. Default behaviors are:

Respond to messages from any chat
Conversations won't automatically time out
Data won't be persisted
Bot will use polling
OpenAI gpt-3.5-turbo model will be used
The bot won't respond to voice messages or read out messages

To change the default behavior, see Advanced Deployment.

Caution: The bot will respond to any message sent to it. This may induce a significant OpenAI API cost since Telegram bots are public and anyone who knows the bot's username can send messages to it. If you don't want the bot to respond to messages from specific chats, see Restrict Bot to Specific Chats.

Usage

Conversation

Send a message to the bot and it will respond with a message generated by ChatGPT. Use the /retry command to regenerate the response for the last message.

In a conversation, the bot will remember the previous messages and use them as context to generate the response. To clear the context, and start a new conversation, use the /new command. To have conversations automatically expire, see Conversation Management.

To view the conversation history, send the /history command.

Mode

You can define different modes for the bot to use. A mode is a system message that is included at the beginning of the conversation. Refer to OpenAI API documentation for more information about system message.

Use the /mode command to select and manage modes. The bot would respond with a list of available modes. Tap on a mode to select it. There would also be buttons to create a new mode, edit a mode, or clear mode selection.

Voice Messages

Refer to Support Voice Messages with Azure Cognitive Services for instructions on how to enable voice messages. When enabled, the bot would respond to voice messages with voice messages. It would first convert the voice message to text, then send the text to OpenAI API, and finally convert the response to voice message.

You can also reply to a text messaged sent by the bot with /say command to have the bot convert the message to voice message.

Advanced Deployment

Here is an empty docker-compose.yml file with all the available options. You can copy and paste the options you need to customize the bot.

services:
  telegram-gpt:
    build: github.com/zhuorantan/TelegramGPT#main
    container_name: telegram-gpt
    restart: unless-stopped
    volumes:
      - telegram-gpt:/data
    expose:
      - 80
    environment:
      - TELEGRAM_GPT_OPENAI_API_KEY=<OPENAI_API_KEY> # Required
      - TELEGRAM_GPT_TELEGRAM_TOKEN=<TELEGRAM_TOKEN> # Required
      - TELEGRAM_GPT_CHAT_ID_0=<CHAT_ID>
      - TELEGRAM_GPT_CHAT_ID_1=<CHAT_ID>
      - TELEGRAM_GPT_CONVERSATION_TIMEOUT=300
      # - TELEGRAM_GPT_MAX_MESSAGE_COUNT=32
      # - TELEGRAM_GPT_WEBHOOK_URL=https://example.com
      # - TELEGRAM_GPT_OPENAI_MODEL_NAME=azure-gpt-35-turbo
      # - TELEGRAM_GPT_AZURE_OPENAI_ENDPOINT=https://example.openai.azure.com
      # - TELEGRAM_GPT_AZURE_SPEECH_KEY=<AZURE_SPEECH_KEY>
      # - TELEGRAM_GPT_AZURE_SPEECH_REGION=westus2

volumes:
  telegram-gpt:

Restrict Bot to Specific Chats

Use the --chat-id option to restrict the bot to specific chats. To allow multiple chats, set --chat-id multiple times. If no --chat-id is set, the bot will accept messages from any chat.

You can get your chat ID either by checking the log of TelegramGPT or by sending a message to the bot and going to this URL to view the chat ID:

https://api.telegram.org/bot<TELEGRAM_TOKEN>/getUpdates

The chat ID would be the id field in the JSON response.

Conversation Management

By default, all messages would be included in a single conversation, until the conversation is cleared with the /new command. To automatically expire conversations after a timeout, set the --conversation-timeout option to the number of seconds after which a new conversation should be started. For example, to expire conversations after 5 minutes, set --conversation-timeout 300.

By default, there is no limit to the number of messages in a conversation. To limit the number of messages, set the --max-message-count option to the maximum number of messages to be included in a conversation. Earlier messages would be discarded when the limit is reached.

Data Persistence

The bot won't persist any data by default, and all conversations and mode settings would be lost when the bot is restarted. To persist these data, set the --data-dir option to a path to a directory where the data should be stored.

This option would be default to /data in the Docker image. This directory should be mounted to a persistent volume.

Telegram Bot Webhook

By default, the bot uses polling to receive messages. You can use a webhook to have Telegram servers send messages to your server. This requires a public IP address, a domain name, and a reverse proxy with SSL support. Refer to Marvin's Marvellous Guide to All Things Webhook for more information about webhook.

To enable webhook mode, set the --webhook-url to the public accessible URL of the bot. It must be able to receive HTTPS requests and requests must be forwarded to the bot via HTTP.

The bot would listen on 0.0.0.0:80 by default. To change the listening address, set the --webhook-listen-address option. Only ports 443, 80, 88 and 8443 are allowed.

Support Voice Messages with Azure Cognitive Services

TelegramGPT can convert voice messages to text and text to voice messages using Azure Cognitive Services. Follow this guide to create a Speech resource and get the API key and region.

To enable voice messages, set the --azure-speech-api-key to the API key. Set the --azure-speech-region to the region of the Speech resource if it's different from westus.

Use a Different Model

By default, the bot uses the gpt-3.5-turbo model. To use a different chat completion model, set the --openai-model-name option to the model name. Refer to OpenAI API documentation for a list of available models.

Azure OpenAI Service

Alternative to using OpenAI API, you can use Azure OpenAI Service to generate responses. Follow this guide to create an Azure OpenAI Service resource, deploy a model, and get the API key and endpoint.

To use Azure OpenAI Service, set the --azure-openai-endpoint option to the endpoint of the Azure OpenAI Service resource. Set the --openai-api-key option to the API key. Set the --openai-model-name option to the model deployment name.

Network Proxy

To use proxy, add -e http_proxy=http://<proxy>:<port> and -e https_proxy=http://<proxy>:<port> to the docker run command. For Docker Compose, add http_proxy and https_proxy environment variables to the environment section.

Options Reference

Option	Environment Variable	Description	Default
`--openai-api-key`	`TELEGRAM_GPT_OPENAI_API_KEY`	OpenAI API key created from OpenAI Platform. If `--azure-openai-endpoint` is specified, this is the Azure OpenAI Service API key.
`--telegram-token`	`TELEGRAM_GPT_TELEGRAM_TOKEN`	Telegram bot token. Get it from @BotFather.
`--chat-id`	`TELEGRAM_GPT_CHAT_ID`, `TELEGRAM_GPT_CHAT_ID_*`	IDs of Allowed chats. Can be specified multiple times. If not specified, the bot will respond to all chats.
`--conversation-timeout`	`TELEGRAM_GPT_CONVERSATION_TIMEOUT`	Timeout in seconds for a conversation to expire. If not specified, the bot will keep the conversation alive indefinitely.
`--max-message-count`	`TELEGRAM_GPT_MAX_MESSAGE_COUNT`	Maximum number of messages to keep in the conversation. Earlier messages will be discarded with this option set. If not specified, the bot will keep all messages in the conversation.
`--data-dir`	`TELEGRAM_GPT_DATA_DIR`	Directory to store data. If not specified, data won't be persisted.
`--webhook-url`	`TELEGRAM_GPT_WEBHOOK_URL`	URL for telegram webhook requests. If not specified, the bot will use polling mode.
`--webhook-listen-address`	`TELEGRAM_GPT_WEBHOOK_LISTEN_ADDRESS`	Address to listen for telegram webhook requests in the format of :. Only valid when `--webhook-url` is set.	`0.0.0.0:80`
`--openai-model-name`	`TELEGRAM_GPT_OPENAI_MODEL_NAME`	Chat completion model name. If `--azure-openai-endpoint` is specified, this is the Azure OpenAI Service model deployment name.	`gpt-3.5-turbo`
`--azure-openai-endpoint`	`TELEGRAM_GPT_AZURE_OPENAI_ENDPOINT`	Azure OpenAI Service endpoint. Set this option to use Azure OpenAI Service instead of OpenAI API.
`--azure-speech-key`	`TELEGRAM_GPT_AZURE_SPEECH_KEY`	Azure Speech Services API key. Set this option to enable voice messages powered by Azure speech-to-text and text-to-speech services.
`--azure-speech-region`	`TELEGRAM_GPT_AZURE_SPEECH_REGION`	Azure Speech Services region. Only valid when --azure-speech-key is set.	`westus`