TBXark/ChatGPT-Telegram-Workers

Prerequisites

Before you begin, make sure you have the following:

• A Cloudflare account — Free tier is sufficient. Sign up at cloudflare.com
• Node.js v18 or later — Check with node --version
• pnpm — Install with npm install -g pnpm if not already present
• Wrangler CLI — Cloudflare's deployment tool (installed as part of setup below)
• A Telegram account — To create and use your bot
• An OpenAI account (or another supported AI provider) — To generate an API key

---

Get Your API Keys

1. Telegram Bot Token

1. Open Telegram and search for @BotFather
2. Send the command /newbot
3. Follow the prompts to name your bot and choose a username
4. BotFather will reply with a token in the format 123456789:ABCDefgh... — copy and save it

2. OpenAI API Key

1. Log in to the OpenAI Platform
2. Click Create new secret key
3. Copy the key immediately — it won't be shown again
4. Ensure your account has billing enabled or credits available

Using a different AI provider? The project supports Azure OpenAI, Anthropic, Gemini, Mistral, DeepSeek, Groq, and others. Check the configuration docs for the specific variables each provider requires.

3. Cloudflare Account ID

1. Log in to Cloudflare Dashboard
2. Select any domain or go to Workers & Pages
3. Your Account ID is shown in the right-hand sidebar — copy it

---

Installation

Clone the Repository

git clone https://github.com/TBXark/ChatGPT-Telegram-Workers.git
cd ChatGPT-Telegram-Workers

Install Dependencies

pnpm install

Install Wrangler (if not already installed)

pnpm add -g wrangler

Authenticate Wrangler with Cloudflare

wrangler login

This opens a browser window — log in and authorize Wrangler to access your Cloudflare account.

---

Configuration

1. Create your wrangler.toml

Copy the example config file:

cp wrangler.example.toml wrangler.toml

If no example file exists, create wrangler.toml in the project root with at minimum:

name = "chatgpt-telegram-workers"
main = "dist/index.js"
compatibility_date = "2024-01-01"

[vars]
TELEGRAM_AVAILABLE_TOKENS = "your-telegram-bot-token"
OPENAI_API_KEY = "your-openai-api-key"

2. Environment Variables Reference

Set these as [vars] entries in wrangler.toml or as encrypted secrets using wrangler secret put <VARIABLE_NAME>.

Tip: Use wrangler secret put for sensitive values (API keys, tokens) so they are not stored in plain text.

| Variable | Description | Where to Get It | |----------|-------------|-----------------| | TELEGRAM_AVAILABLE_TOKENS | Your Telegram bot token(s). Comma-separate multiple tokens for multiple bots. | @BotFather on Telegram | | OPENAI_API_KEY | Your OpenAI secret API key | platform.openai.com/api-keys | | OPENAI_CHAT_MODEL | The GPT model to use, e.g. gpt-4o or gpt-3.5-turbo | OpenAI model list | | TELEGRAM_AVAILABLE_ENVS | Comma-separated list of allowed environment variable names exposed to the bot | Set to your wrangler.toml var names | | SYSTEM_INIT_MESSAGE | The system prompt sent to the AI at the start of every conversation | Write your own prompt string | | SYSTEM_INIT_MESSAGE_ROLE | Role for the system prompt, typically system | Use system (default) | | CLOUDFLARE_ACCOUNT_ID | Your Cloudflare account identifier | Cloudflare Dashboard sidebar | | CLOUDFLARE_TOKEN | Cloudflare API token (required if using Cloudflare AI as a provider) | Cloudflare API Tokens |

For the full list of supported variables (including Azure, Anthropic, Gemini, etc.), see the official config docs.

---

Running the Bot

Build the Project

pnpm run build:workers

Deploy to Cloudflare Workers

pnpm run deploy:workers

This builds the worker and deploys it to your Cloudflare account using the settings in wrangler.toml.

Register the Telegram Webhook

After deploying, you must tell Telegram where to send updates. Replace the placeholders with your actual values:

curl "https://api.telegram.org/bot<YOUR_TELEGRAM_TOKEN>/setWebhook?url=https://<YOUR_WORKER_NAME>.<YOUR_CF_SUBDOMAIN>.workers.dev/telegram/<YOUR_TELEGRAM_TOKEN>/webhook"

Your Worker URL is printed in the terminal after a successful deploy:workers run.

Development / Preview Mode

To test locally before deploying:

pnpm run build:workers
wrangler dev

Note: Telegram webhooks require a public HTTPS URL, so full end-to-end testing requires a deployed worker. For local testing, check the project README for details on using tunneling tools.

---

Testing

1. Confirm the Worker is Live

Visit your worker URL in a browser:

https://<your-worker-name>.<your-cf-subdomain>.workers.dev

You should receive a response (even a plain text or JSON message) rather than a connection error.

2. Verify the Webhook is Registered

curl "https://api.telegram.org/bot<YOUR_TELEGRAM_TOKEN>/getWebhookInfo"

Look for "url" in the response — it should match your worker's webhook URL. "pending_update_count" should be 0 after a moment.

3. Send a Test Message

1. Open Telegram and navigate to your bot
2. Send /start — the bot should reply with a greeting or prompt
3. Send a plain message like Hello, who are you? — the bot should respond using the AI model

If the bot replies, your deployment is working correctly.

---

Troubleshooting

| Problem | Likely Cause | Fix | |---------|-------------|-----| | Bot does not respond to messages | Webhook URL is not set or is incorrect | Re-run the setWebhook curl command and verify with getWebhookInfo that the URL matches your deployed worker | | wrangler deploy fails with auth error | Wrangler is not authenticated or session has expired | Run wrangler login again and retry the deploy command | | Worker deploys but returns 500 errors | Missing or misconfigured environment variables | Check that TELEGRAM_AVAILABLE_TOKENS and OPENAI_API_KEY are set; use wrangler secret list to verify secrets are present | | OpenAI returns a 401 Unauthorized error | API key is invalid or not properly set | Confirm the key is correct in OpenAI Dashboard; re-set it with wrangler secret put OPENAI_API_KEY | | pnpm install fails or packages are missing | Wrong Node.js version or pnpm not installed | Ensure Node.js ≥ 18 (node --version) and pnpm is installed (npm install -g pnpm) | | Multiple bots not working | Token list format is wrong | Ensure TELEGRAM_AVAILABLE_TOKENS contains tokens separated by commas with no spaces, e.g. token1,token2 | | Build fails with TypeScript errors | Dependency mismatch or stale cache | Run pnpm install again, then pnpm run build:workers; check the GitHub Issues for known build problems |