Merge pull request #41 from flashcatcloud/doc-review/2026-04-06-160000

docs: consolidate Zoom/Telegram bot config into notifications page

Author: ysyneu

docs.json

@@ -238,9 +238,7 @@
                       "zh/on-call/integration/instant-messaging/wecom",
                       "zh/on-call/integration/instant-messaging/dingtalk",
                       "zh/on-call/integration/instant-messaging/slack",
-                      "zh/on-call/integration/instant-messaging/microsoft-teams",
-                      "zh/on-call/integration/instant-messaging/telegram",
-                      "zh/on-call/integration/instant-messaging/zoom"
+                      "zh/on-call/integration/instant-messaging/microsoft-teams"
                     ]
                   },
                   {
@@ -670,9 +668,7 @@
                       "en/on-call/integration/instant-messaging/wecom",
                       "en/on-call/integration/instant-messaging/dingtalk",
                       "en/on-call/integration/instant-messaging/slack",
-                      "en/on-call/integration/instant-messaging/microsoft-teams",
-                      "en/on-call/integration/instant-messaging/telegram",
-                      "en/on-call/integration/instant-messaging/zoom"
+                      "en/on-call/integration/instant-messaging/microsoft-teams"
                     ]
                   },
                   {

en/on-call/configuration/notifications.mdx

@@ -214,6 +214,10 @@ If your team cannot do app integration temporarily, using bots is a simple, quic
   </Tab>
 
   <Tab title="Telegram">
+    <Warning>
+    Telegram services may not be directly accessible in some regions. Ensure the Webhook URL you use is accessible in your current network environment.
+    </Warning>
+
     <Steps>
       <Step title="Create Telegram Bot">
         Search `BotFather` in Telegram and send `/newbot` command, enter bot name, record the returned Token
@@ -222,10 +226,13 @@ If your team cannot do app integration temporarily, using bots is a simple, quic
         Click top left settings → **New Channel**, create Channel and add bot as member
       </Step>
       <Step title="Get Chat ID">
-        Visit `https://api.telegram.org/bot{Token}/getUpdates`, find `chat.id` in returned JSON
+        Visit `https://api.telegram.org/bot{Token}/getUpdates`, find `chat.id` in returned JSON. You can also use tools like [@userinfobot](https://t.me/userinfobot)
       </Step>
       <Step title="Configure Flashduty">
-        Configure Telegram bot in **Channel** → **Escalation Rules**, enter Token and Chat ID
+        Configure Telegram bot in **Channel** → **Escalation Rules**:
+        - **Webhook URL**: Enter the Bot Token or an accessible Telegram service proxy address
+        - **Chat IDs**: Enter group Chat IDs that should receive notifications. Multiple Chat IDs are supported — press Enter after each to confirm
+        - **Alias** (optional): Set an alias to distinguish different notification channels
       </Step>
     </Steps>
   </Tab>
@@ -248,15 +255,25 @@ If your team cannot do app integration temporarily, using bots is a simple, quic
   </Tab>
 
   <Tab title="Zoom">
+    <Warning>
+    Zoom Incoming Webhook connections are tied to the Zoom account that created them. When that user leaves the organization or their account is deactivated, all Webhook connections they created are automatically invalidated. **We strongly recommend using a shared team service account** (rather than a personal account) to create Webhook connections, preventing notification disruptions due to personnel changes.
+    </Warning>
+
     <Steps>
       <Step title="Create Bot">
         Open Zoom app, go to **Apps** → **Add Apps**, search and add the `Incoming Webhook` app. Return to the chat interface and confirm the `Incoming Webhook` app has been added successfully. In any channel or the `Incoming Webhook` app, enter the command: `/inc connect flashduty`. The system will return the app's connection information
       </Step>
       <Step title="Configure Flashduty">
-        Copy the `Endpoint` URL from the returned information and enter it in the Zoom bot `Webhook` field in Flashduty **Channel** → **Escalation Rules**. Copy the `Verification Token` and enter it in the Zoom bot `Verify Token` field
+        Configure Zoom bot in **Channel** → **Escalation Rules**:
+        - **Webhook URL**: Copy the `Endpoint` URL from the returned information
+        - **Verify Token**: Copy the `Verification Token` from the returned information, used to verify request authenticity
+        - **Alias** (optional): Set an alias to distinguish different notification channels
       </Step>
-      <Step title="(Optional) Use @ Mentions">
-        Admin obtains user `user_id` from the Zoom console. Create a mapping table in Flashduty **Integration Center** → Mapping Data, mapping Flashduty member emails to Zoom `user_id`. Associate the corresponding Zoom bot and mapping table in **Escalation Rules**
+      <Step title="(Optional) Enable @ Mentions">
+        When enabled, the system uses the user mapping table to @ mention corresponding responders:
+        1. Admin obtains user `user_id` from the Zoom console
+        2. Create a Zoom-type mapping table in Flashduty **Platform Management** → **Mapping Table Management**, mapping Flashduty member emails to Zoom `user_id`
+        3. Associate the corresponding Zoom bot and mapping table in **Escalation Rules**
       </Step>
     </Steps>
   </Tab>
@@ -266,6 +283,56 @@ If your team cannot do app integration temporarily, using bots is a simple, quic
 **Don't use any of the above IM platforms? You can still use bot notifications.** Flashduty does not validate the domain of bot webhook URLs, so you can select any bot type (e.g., Dingtalk Bot) and set the webhook URL to your own server endpoint. Simply implement the corresponding IM platform's message push protocol on your server to receive Flashduty alert notifications. This approach is ideal for custom notification systems or integrating with non-standard IM tools. For step-by-step instructions, see the [FAQ](/en/on-call/quickstart/faq#i-dont-use-feishudingtalkwecomtelegram--how-can-i-receive-bot-notifications).
 </Tip>
 
+#### Advanced settings
+
+All bot types support the following advanced options, accessible by expanding **Advanced Settings** during configuration:
+
+| Setting | Supported Bot Types | Description |
+| :--- | :--- | :--- |
+| **Alias** | All | Set an alias for the bot to help remember and distinguish different notification channels |
+| **Severity filter** | All | Select which alert severity levels trigger notifications. Incidents with unselected severity levels will not be pushed |
+| **Notification event types** | Feishu/Lark, Dingtalk, WeCom, Slack, Zoom | Select which event types trigger notification pushes (e.g., triggered, acknowledged, closed). All selected by default |
+| **@ Mentions** | Dingtalk, Zoom | When enabled, @ mentions corresponding responders via user mapping. Dingtalk matches by phone number by default; Zoom requires a user mapping table |
+
+<Tip>
+The user mapping table defines the correspondence between Flashduty users and IM platform users. You can create and maintain mapping tables on the **Platform Management** → **Mapping Table Management** page.
+</Tip>
+
+#### FAQ
+
+<AccordionGroup>
+<Accordion title="Telegram message push fails with a network error?">
+Check whether the Webhook URL is accessible in your current network environment. Telegram services may be restricted in some regions. Consider using a reliable proxy service address.
+</Accordion>
+
+<Accordion title="How do I get a Telegram group chat's Chat ID?">
+After adding the Bot to the target group, you can call the Telegram Bot API `getUpdates` method to obtain the group Chat ID. You can also use tools like [@userinfobot](https://t.me/userinfobot).
+</Accordion>
+
+<Accordion title="Zoom notification fails with 'Failed to send bot message'?">
+This error means Zoom cannot send messages through the Webhook. Possible causes include: the Webhook connection has been invalidated, the creator's account was deactivated or removed, or the Webhook was manually deleted.
+
+**Troubleshooting steps:**
+1. Create a new Incoming Webhook connection in Zoom
+2. Test the new Webhook URL in your Flashduty escalation rule
+3. If the new Webhook works, the original connection has been invalidated (commonly caused by the creator leaving the organization) — replace it with the new Webhook
+4. If the new Webhook also fails, check the message content format or contact Zoom support
+
+**Prevention:** Use a shared team service account (rather than a personal account) to create Webhook connections, preventing notification disruptions due to personnel changes.
+</Accordion>
+
+<Accordion title="Where do I find the Zoom Verify Token?">
+After adding the Incoming Webhook app in Zoom, use the `/inc connect flashduty` command. The returned connection information includes the `Verification Token`.
+</Accordion>
+
+<Accordion title="Bot @ mentions are not working?">
+Verify the following:
+- The **@ mentions** toggle is enabled
+- A **user mapping table** is correctly selected (Zoom) or member phone numbers are correct (Dingtalk)
+- The user mappings in the table are correct and complete
+</Accordion>
+</AccordionGroup>
+
 ---
 
 ## General Configuration