> ## Documentation Index
> Fetch the complete documentation index at: https://docs.panguard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 通知問題

> 排解 Telegram、Slack、Email、Webhook 通知送不到的問題。

## 收不到通知

不管哪個頻道都收不到的話，從這些基本項目開始檢查：

<AccordionGroup>
  <Accordion title="1. 看通知狀態">
    ```bash theme={null}
    panguard chat status
    ```

    會顯示：

    * 哪些頻道有開
    * 上次成功送達時間
    * 有沒有 pending 的錯誤
    * 目前的最低嚴重性設定
  </Accordion>

  <Accordion title="2. 送測試通知">
    ```bash theme={null}
    # 測試所有開啟的頻道
    panguard chat test

    # 測試特定頻道
    panguard chat test --channel telegram
    ```

    測試成功但真正的通知沒到，問題可能出在嚴重性門檻或冷卻時間。
  </Accordion>

  <Accordion title="3. 看嚴重性門檻">
    通知只在事件嚴重性達到或超過設定值時才送：

    ```bash theme={null}
    panguard config get notification.minSeverity
    ```

    設成 `critical` 的話就只有 critical 事件才會通知。調低一點：

    ```bash theme={null}
    panguard config set notification.minSeverity medium
    ```
  </Accordion>

  <Accordion title="4. 看冷卻時間">
    冷卻機制防止重複通知洗版。短時間內很多類似事件的話，只有第一個會觸發：

    ```bash theme={null}
    panguard config get notification.cooldownMinutes
    ```

    覺得太久可以縮短：

    ```bash theme={null}
    panguard config set notification.cooldownMinutes 5
    ```
  </Accordion>

  <Accordion title="5. 重跑頻道設定">
    以上都沒用的話，重跑一次設定：

    ```bash theme={null}
    panguard chat setup telegram
    # 或
    panguard chat setup slack
    ```

    會重新驗證憑證跟重新加密 config。
  </Accordion>
</AccordionGroup>

***

## Telegram 問題

<AccordionGroup>
  <Accordion title="Bot token 無效">
    ```
    Error: Telegram API returned 401: Unauthorized
    ```

    Bot token 不對或被撤銷了。

    **解法：**

    1. 到 Telegram 找 [@BotFather](https://t.me/BotFather)
    2. 送 `/mybots` 選你的 bot
    3. 需要的話重新產生 token
    4. 重跑設定：
       ```bash theme={null}
       panguard chat setup telegram
       ```
  </Accordion>

  <Accordion title="Chat ID 不對">
    ```
    Error: Telegram API returned 400: Bad Request: chat not found
    ```

    Chat ID 錯了或 bot 還沒加進群組。

    **解法：**

    1. 先隨便傳一則訊息給你的 bot（Telegram 規定的）
    2. 群組的話，把 bot 加進去
    3. 重跑設定讓它自動抓 chat ID：
       ```bash theme={null}
       panguard chat setup telegram
       ```
  </Accordion>

  <Accordion title="要先傳訊息給 bot">
    Telegram bot 不能主動發起對話。你必須先傳訊息給 bot，它才能傳訊息給你。

    1. 開 Telegram 用 username 找到你的 bot
    2. 傳 `/start` 或隨便一則訊息
    3. 然後跑：
       ```bash theme={null}
       panguard chat test --channel telegram
       ```
  </Accordion>

  <Accordion title="群組權限">
    Bot 沒辦法在群組發訊息的話：

    1. 確認 bot 是群組成員
    2. 群組有限制發言的話，把 bot 設成管理員
    3. 在 BotFather 確認 **Group Privacy** 是關的（`/mybots` > Bot Settings > Group Privacy > Turn off）
  </Accordion>
</AccordionGroup>

***

## Slack 問題

<AccordionGroup>
  <Accordion title="Webhook URL 無效">
    ```
    Error: Slack webhook returned 403: invalid_token
    ```

    Webhook URL 不對、過期或被撤銷了。

    **解法：**

    1. 到 [api.slack.com/apps](https://api.slack.com/apps)
    2. 選你的 app
    3. 到 **Incoming Webhooks**
    4. 建新的 webhook 或複製現有的 URL
    5. 重跑設定：
       ```bash theme={null}
       panguard chat setup slack
       ```
  </Accordion>

  <Accordion title="找不到頻道">
    ```
    Error: Slack webhook returned 404: channel_not_found
    ```

    設定的頻道不存在或 webhook 沒被授權使用它。

    **解法：**

    * 確認頻道名稱對不對（要帶 `#`）
    * 針對目標頻道建一個新 webhook
    * 重跑設定：
      ```bash theme={null}
      panguard chat setup slack
      ```
  </Accordion>

  <Accordion title="App 權限">
    如果用 Slack App（不只是 incoming webhook），確認 app 有這些 scope：

    * `incoming-webhook` -- 透過 webhook 發訊息
    * `chat:write` -- 發訊息（用 Bot Token 的話）
    * `chat:write.public` -- 發到 bot 不在的頻道

    改了 scope 之後重新安裝 app 到 workspace。
  </Accordion>
</AccordionGroup>

***

## Email 問題

<AccordionGroup>
  <Accordion title="SMTP 連線被拒">
    ```
    Error: connect ECONNREFUSED smtp.gmail.com:587
    ```

    * 確認 SMTP host 跟 port 對不對
    * 看防火牆或 ISP 有沒有擋 port 587
    * 587（TLS）被擋的話試 465（SSL）：
      ```bash theme={null}
      panguard config set channels.email.smtp.port 465
      ```
  </Accordion>

  <Accordion title="SMTP 認證失敗">
    ```
    Error: Invalid login: 535-5.7.8 Username and Password not accepted
    ```

    **Gmail 的話：**

    * 用[應用程式密碼](https://support.google.com/accounts/answer/185833)，不要用帳號密碼
    * 先在 Google 帳號開兩步驟驗證
    * 到 [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords) 產生應用程式密碼

    **其他 provider：**

    * 確認帳號對不對（通常是完整的 email 地址）
    * 看 provider 是不是要用 app 專用密碼
    * 重跑設定：
      ```bash theme={null}
      panguard chat setup email
      ```
  </Accordion>

  <Accordion title="Email 進垃圾郵件">
    * 把 `alerts@panguard.ai`（或你設定的 `from` 地址）加到聯絡人
    * 自架的話幫發送 domain 設好 SPF、DKIM、DMARC 紀錄
    * 用信譽好的 SMTP provider（SendGrid、AWS SES、Mailgun）
  </Accordion>
</AccordionGroup>

***

## Webhook 問題

<AccordionGroup>
  <Accordion title="連線 timeout">
    ```
    Error: Webhook request timed out after 10000ms
    ```

    Webhook endpoint 在 timeout 時間內沒回應。

    * 確認 URL 對不對、伺服器連不連得到
    * 拉長 timeout：
      ```bash theme={null}
      panguard config set channels.webhook.timeout 30000
      ```
    * 直接測 endpoint：
      ```bash theme={null}
      curl -X POST YOUR_WEBHOOK_URL \
        -H "Content-Type: application/json" \
        -d '{"test": true}'
      ```
  </Accordion>

  <Accordion title="SSL 憑證錯誤">
    ```
    Error: unable to verify the first certificate
    ```

    Webhook endpoint 用了自簽或無效的 SSL 憑證。

    * 用有效的 SSL 憑證（Let's Encrypt 免費）
    * 內部 endpoint 的話設 CA 憑證：
      ```bash theme={null}
      export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
      ```
  </Accordion>
</AccordionGroup>

***

## 通知語言不對

通知送來的語言不對的話：

```bash theme={null}
# 看目前語言設定
panguard config get preferences.language

# 改語言
panguard chat setup --lang zh-TW
```

或重跑完整設定重新選語言：

```bash theme={null}
panguard chat setup
```

支援的語言：

| 代碼      | 語言      |
| ------- | ------- |
| `en`    | English |
| `zh-TW` | 繁體中文    |
| `ja`    | 日本語     |

<Info>
  通知語言跟 CLI 語言（`PANGUARD_LANG`）是分開的。CLI
  語言管終端輸出，通知語言管透過通知頻道送出去的訊息內容。
</Info>