cloudflare_temp_email/vitepress-docs/docs/en/guide/feature/telegram.md

Configure Telegram Bot

Try it here: @cf_temp_mail_bot

::: warning Note The default worker.dev domain certificate for worker is not supported by Telegram. Please use a custom domain when configuring Telegram Bot. :::

Note

If you want to use Telegram Bot, please bind KV first

If you don't need Telegram Bot, you can skip this step

If you want Telegram to have stronger email parsing capabilities, refer to Configure worker to use wasm for email parsing

Telegram Bot Configuration

Please first create a Telegram Bot, obtain the token, then execute the following command to add the token to secrets

Note

If you find it troublesome, you can also put it in plain text under [vars] in wrangler.toml, but this is not recommended

If you deployed via UI, you can add it under Variables and Secrets in the Cloudflare UI interface

# Switch to worker directory
cd worker
pnpm wrangler secret put TELEGRAM_BOT_TOKEN

Bot

• Can set whitelist users
• Click Initialize to complete the configuration.
• Click View Status to check the current configuration status.

Language Switching

Note

This feature is available since v1.2.0

Telegram Bot supports Chinese and English switching. Users can set their language preference via the /lang command.

Enable Language Switching

You need to configure TG_ALLOW_USER_LANG = true in worker variables to enable this feature.

Usage

• /lang zh - Switch to Chinese
• /lang en - Switch to English
• /lang - View current language setting

Language preferences are saved to KV, and each user can set their preference independently.

Per-User Mail Push

Telegram Bot supports per-user push notifications. After a user binds an address, emails received at that address are automatically pushed to the corresponding user.

User Workflow

1. Find your deployed Bot in Telegram
2. Use /new [name@domain] to create a new address, or /bind <credential> to bind an existing address
3. Once bound, you will automatically receive push notifications when the address receives mail
4. Use /address to view your bound addresses
5. Use /unbind <address> to unbind an address

Tip

Each user can bind up to TG_MAX_ADDRESS (default 5) addresses

Global Push

Admins can enable global mail push in the admin panel under Settings -> Telegram, pushing all emails to a specified list of Telegram user IDs.

• enableGlobalMailPush: Enable global push
• globalMailPushList: List of Telegram user IDs to receive global push

Note

Global push and per-user push can work simultaneously. If an address is bound to a user who is also in the global push list, they will receive two notifications.

Attachment Push

Note

This feature is available since v1.5.0

Set ENABLE_TG_PUSH_ATTACHMENT = true to enable sending email attachments via Telegram push.

• Single file size limit is 50MB (Telegram Bot API limit), oversized attachments are skipped
• Multiple attachments are sent in batches via sendMediaGroup, up to 6 per batch
• The first attachment includes the sender and subject as caption

Mini App

Can be deployed via command line or UI interface

UI Deployment

For other steps, refer to Frontend and Backend Separation Deployment in UI Deployment

Note

Download the zip from here, telegram-frontend.zip

Modify the index-xxx.js file in the zip, where xx is a random string

Search for https://temp-email-api.xxx.xxx, replace it with your worker domain, then deploy the new zip file

Command Line Deployment

cd frontend
pnpm install
cp .env.example .env.prod
# Edit .env.prod and set VITE_IS_TELEGRAM=true
# --project-name can create a separate pages for mini app, you can also share one pages, but may encounter js loading issues
pnpm run deploy:telegram --project-name=<your_project_name>

Warning

Windows users: The inline VITE_IS_TELEGRAM=true environment variable in npm scripts does not work on Windows. Please set VITE_IS_TELEGRAM=true in your .env.prod file manually, then use the regular build command instead:

pnpm run build

• After deployment, please fill in the web URL in the Settings -> Telegram Mini App page Telegram Mini App URL in the admin backend.
• Please execute /setmenubutton in @BotFather, then enter your web address to set the Open App button in the lower left corner.
• Please execute /newapp in @BotFather to create a new app and register the mini app.