/TelegramGPT

A minimum ChatGPT Telegram Bot with voice messages and custom system prompt support

Primary LanguagePythonMIT LicenseMIT

TelegramGPT

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

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