Minimal Python server that connects Telegram bots to GPT through a stateless webhook flow. The server does not keep one process alive for each bot: setup registers a Telegram webhook, and each Telegram update is processed by the single HTTP server instance.
make installTelegram webhooks require a public HTTPS URL. For local development, make start
can start ngrok automatically when NGROK_DOMAIN is not provided. It reads the
HTTPS tunnel from the local ngrok API and exports it as WEBHOOK_BASE_URL for
the server process.
export SERVER_SECRET_KEY="any-private-string"
export DATA_PATH="./data"
make startIf you already have a fixed ngrok domain, pass it explicitly. make start will
start ngrok with that domain using ngrok http --domain <domain> 8000 and will
add https:// to WEBHOOK_BASE_URL when omitted.
make start NGROK_DOMAIN="your-domain.ngrok-free.app"
make start NGROK_DOMAIN="https://your-domain.ngrok-free.app"On startup the server prints the effective WEBHOOK_BASE_URL, so you can verify
that the webhook origin is the expected public HTTPS URL.
Open http://127.0.0.1:8000, fill in ChatGPT Prompt ID,
Telegram Bot HTTP API Token and OpenAI API Key, then create the bot link.
During setup the server:
- validates the Telegram token with
getMe - stores the encrypted bot configuration under
DATA_PATH - registers a Telegram webhook at
/webhook/<bot-id> - returns a
/launch/<bot-id>link that redirects to the Telegram chat
In production or Docker, configure WEBHOOK_BASE_URL directly with the external
HTTPS origin that Telegram can reach. Do not include /webhook/...; the server
adds the webhook path itself.
export WEBHOOK_BASE_URL="https://example.com"If you run behind a reverse proxy, WEBHOOK_BASE_URL should be the public HTTPS
origin of that proxy.
DATA_PATH defaults to ./data. It contains encrypted bot payloads and encrypted chat
session state. Mount it to persistent external storage in production.
Conversation context is not kept forever: the server stores chat history with timestamps and sends only messages from the last hour as context. Older messages are not sent back to OpenAI.
Sensitive fields are encrypted at rest with SERVER_SECRET_KEY. Keep that key
stable across restarts or existing bot configurations cannot be decrypted.
export SERVER_SECRET_KEY="any-private-string"
export WEBHOOK_BASE_URL="https://example.com"
export DATA_PATH="./data"
make docker-startThe app is exposed at http://127.0.0.1:8000. In compose.yml, host
DATA_PATH is mounted into the container at CONTAINER_DATA_PATH
(default /data). The container reads its storage location from the DATA_PATH
environment variable.
Contributions are always welcome! Whether you want to report bugs, suggest new features, improve documentation, or contribute code, your help is appreciated.
- Openapi Team (@openapi-it)
Meet our partners using Openapi or contributing to this project:
- Blank
- Credit Safe
- Deliveroo
- Gruppo MOL
- Jakala
- Octotelematics
- OTOQI
- PWC
- QOMODO S.R.L.
- SOUNDREEF S.P.A.
We believe in open source and we act on that belief. We became Silver Members of the Linux Foundation because we wanted to formally support the ecosystem we build on every day. Open standards, open collaboration, and open governance are part of how we work and how we think about software.
This project is licensed under the MIT License.
The MIT License is a permissive open-source license that allows you to freely use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software, provided that the original copyright notice and this permission notice are included in all copies or substantial portions of the software.
For more details, see the full license text at the MIT License page.