docs: add webhook preset templates and Telegram push docs (#884)

docs: add webhook preset templates and Telegram per-user push docs (#769)

Add Telegram Bot, WeChat Work, Discord webhook preset templates to
frontend and documentation. Add per-user mail push and global push
documentation for Telegram Bot.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

CHANGELOG.md

@@ -20,6 +20,12 @@
 
 - test: |E2E| 新增自动回复触发 E2E 测试，覆盖空前缀、前缀匹配、正则匹配和禁用状态场景
 
+### Docs
+
+- docs: |Telegram| 新增每用户邮件推送和全局推送功能说明文档（#769）
+- docs: |Webhook| 新增 Telegram Bot、企业微信、Discord 等常用推送平台的 Webhook 模板示例
+- feat: |Webhook| 前端预设模板新增 Telegram Bot、企业微信、Discord 三个模板
+
 ### Improvements
 
 ## v1.4.0

CHANGELOG_EN.md

@@ -20,6 +20,12 @@
 
 - test: |E2E| Add auto-reply trigger E2E tests covering empty prefix, prefix matching, regex matching, and disabled state
 
+### Docs
+
+- docs: |Telegram| Add per-user mail push and global push documentation (#769)
+- docs: |Webhook| Add webhook template examples for Telegram Bot, WeChat Work, Discord and other common push platforms
+- feat: |Webhook| Add Telegram Bot, WeChat Work, Discord preset templates to frontend webhook settings
+
 ### Improvements
 
 ## v1.4.0

frontend/src/components/WebhookComponent.vue

@@ -117,6 +117,55 @@ const presets: WebhookPreset[] = [
             }, null, 2),
         },
     },
+    {
+        name: 'Telegram Bot',
+        doc: 'https://core.telegram.org/bots/api#sendmessage',
+        settings: {
+            enabled: true,
+            url: 'https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage',
+            method: 'POST',
+            headers: JSON.stringify({
+                'Content-Type': 'application/json',
+            }, null, 2),
+            body: JSON.stringify({
+                "chat_id": "YOUR_CHAT_ID",
+                "text": "New Email\nFrom: ${from}\nTo: ${to}\nSubject: ${subject}\nURL: ${url}"
+            }, null, 2),
+        },
+    },
+    {
+        name: 'WeChat Work',
+        doc: 'https://developer.work.weixin.qq.com/document/path/91770',
+        settings: {
+            enabled: true,
+            url: 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY',
+            method: 'POST',
+            headers: JSON.stringify({
+                'Content-Type': 'application/json',
+            }, null, 2),
+            body: JSON.stringify({
+                "msgtype": "text",
+                "text": {
+                    "content": "New Email\nFrom: ${from}\nTo: ${to}\nSubject: ${subject}\nURL: ${url}"
+                }
+            }, null, 2),
+        },
+    },
+    {
+        name: 'Discord',
+        doc: 'https://discord.com/developers/docs/resources/webhook',
+        settings: {
+            enabled: true,
+            url: 'https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN',
+            method: 'POST',
+            headers: JSON.stringify({
+                'Content-Type': 'application/json',
+            }, null, 2),
+            body: JSON.stringify({
+                "content": "**New Email**\nFrom: ${from}\nTo: ${to}\nSubject: ${subject}\nURL: ${url}"
+            }, null, 2),
+        },
+    },
 ]
 
 const presetDropdownOptions: DropdownOption[] = presets.map((preset, index) => ({

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

@@ -55,6 +55,31 @@ You need to configure `TG_ALLOW_USER_LANG = true` in worker variables to enable
 
 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.
+
 ## Mini App
 
 Can be deployed via command line or UI interface

vitepress-docs/docs/en/guide/feature/webhook.md

@@ -26,6 +26,77 @@ This project uses [songquanpeng/message-pusher](https://github.com/songquanpeng/
 
 ![telegram](/feature/address-webhook.png)
 
+## Webhook Template Examples
+
+### Telegram Bot Push
+
+Push email notifications by calling the Telegram Bot API directly via webhook. Suitable for scenarios where you don't want to deploy the full Telegram Bot integration or need a custom push format.
+
+- **URL**: `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/sendMessage`
+- **Method**: `POST`
+- **Headers**:
+
+```json
+{
+    "Content-Type": "application/json"
+}
+```
+
+- **Body**:
+
+```json
+{
+    "chat_id": "YOUR_CHAT_ID",
+    "text": "New Email\nFrom: ${from}\nTo: ${to}\nSubject: ${subject}\nURL: ${url}"
+}
+```
+
+> [!TIP]
+> To get your `chat_id`: send a message to the Bot, then visit `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates` and look for the `chat.id` field in the response
+
+### WeChat Work Bot Push
+
+- **URL**: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY`
+- **Method**: `POST`
+- **Headers**:
+
+```json
+{
+    "Content-Type": "application/json"
+}
+```
+
+- **Body**:
+
+```json
+{
+    "msgtype": "text",
+    "text": {
+        "content": "New Email\nFrom: ${from}\nTo: ${to}\nSubject: ${subject}\nURL: ${url}"
+    }
+}
+```
+
+### Discord Webhook Push
+
+- **URL**: `https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN`
+- **Method**: `POST`
+- **Headers**:
+
+```json
+{
+    "Content-Type": "application/json"
+}
+```
+
+- **Body**:
+
+```json
+{
+    "content": "**New Email**\nFrom: ${from}\nTo: ${to}\nSubject: ${subject}\nURL: ${url}"
+}
+```
+
 ## Webhook Data Format
 
 To get the url, you need to configure the worker's `FRONTEND_URL` to your frontend address, or you can construct the url yourself using `id` = `${FRONTEND_URL}?mail_id=${id}`

vitepress-docs/docs/zh/guide/feature/telegram.md

@@ -55,6 +55,31 @@ Telegram Bot 支持中英文切换，用户可以通过 `/lang` 命令设置语
 
 语言偏好会保存到 KV 中，每个用户可以独立设置。
 
+## 每用户邮件推送
+
+Telegram Bot 支持 **每用户独立推送**，用户绑定地址后，该地址收到的邮件会自动推送给对应用户。
+
+### 用户操作流程
+
+1. 在 Telegram 中找到你部署的 Bot
+2. 使用 `/new [name@domain]` 创建新邮箱地址，或使用 `/bind <credential>` 绑定已有地址
+3. 绑定后，该地址收到邮件时会 **自动推送通知给你**
+4. 使用 `/address` 查看已绑定的地址列表
+5. 使用 `/unbind <address>` 解绑地址
+
+> [!TIP]
+> 每个用户最多可绑定 `TG_MAX_ADDRESS`（默认 5）个地址
+
+### 全局推送
+
+管理员可以在后台 `设置` -> `Telegram` 页面开启 **全局邮件推送**，将所有邮件推送给指定的 Telegram 用户 ID 列表。
+
+- `enableGlobalMailPush`: 是否开启全局推送
+- `globalMailPushList`: 接收全局推送的 Telegram 用户 ID 列表
+
+> [!NOTE]
+> 全局推送和每用户推送可以同时生效。如果某地址已绑定用户，同时该用户也在全局推送列表中，则会收到两条通知。
+
 ## Mini App
 
 可以通过命令行部署，或者 UI 界面部署

vitepress-docs/docs/zh/guide/feature/webhook.md

@@ -26,6 +26,77 @@
 
 ![telegram](/feature/address-webhook.png)
 
+## Webhook 模板示例
+
+### Telegram Bot 推送
+
+通过 Webhook 直接调用 Telegram Bot API 推送邮件通知，适合不想部署完整 Telegram Bot 集成或需要自定义推送格式的场景。
+
+- **URL**: `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/sendMessage`
+- **Method**: `POST`
+- **Headers**:
+
+```json
+{
+    "Content-Type": "application/json"
+}
+```
+
+- **Body**:
+
+```json
+{
+    "chat_id": "YOUR_CHAT_ID",
+    "text": "New Email\nFrom: ${from}\nTo: ${to}\nSubject: ${subject}\nURL: ${url}"
+}
+```
+
+> [!TIP]
+> 获取 `chat_id`：向 Bot 发送一条消息，然后访问 `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates` 查看返回结果中的 `chat.id` 字段
+
+### 企业微信机器人推送
+
+- **URL**: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY`
+- **Method**: `POST`
+- **Headers**:
+
+```json
+{
+    "Content-Type": "application/json"
+}
+```
+
+- **Body**:
+
+```json
+{
+    "msgtype": "text",
+    "text": {
+        "content": "New Email\nFrom: ${from}\nTo: ${to}\nSubject: ${subject}\nURL: ${url}"
+    }
+}
+```
+
+### Discord Webhook 推送
+
+- **URL**: `https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN`
+- **Method**: `POST`
+- **Headers**:
+
+```json
+{
+    "Content-Type": "application/json"
+}
+```
+
+- **Body**:
+
+```json
+{
+    "content": "**New Email**\nFrom: ${from}\nTo: ${to}\nSubject: ${subject}\nURL: ${url}"
+}
+```
+
 ## webhook 数据格式
 
 要获取 url 需要配置 worker 的 `FRONTEND_URL` 为你的前端地址，或者你可以通过 `id` 自己拼接 url = `${FRONTEND_URL}?mail_id=${id}`