HiZex Herald

使用手冊

連接訊息管道

每個頻道都是選配：填了憑證才會真的送出，沒填的頻道一律走沙盒（訊息只會出現在主控台的模擬手機，不會送到任何人手上）。下面是主控台「頻道設定」頁會一步一步帶你走的內容——先看過再決定要不要開始，也可以直接進主控台照著做。

順序建議：先連 LINE（多數人只需要這一個）→ 送出第一則確認整條路是通的 → 再視需要加 Email 備援、Web push 或其他管道。主控台的「設定進度」會列出還差什麼。

共同規則

  • 憑證以 HUB_SECRET_KEY 加密儲存，存檔後只顯示「已設定」，任何頁面都不會再把密鑰吐回瀏覽器。
  • 按「驗證並啟用」時 Herald 會先呼叫供應商驗證一次，失敗不會覆蓋原本可用的憑證。
  • 「停用」會刪除該頻道憑證並回到沙盒，已排入佇列的訊息改以沙盒處理。
  • 啟用只代表能送；還要有收件人——LINE 需真人加好友、Email 需聯絡對象有信箱、Web push 需完成訂閱。

LINE 官方帳號

推播、回覆與對話劇本的主要管道。學生與家長最常用，也是唯一支援 LIFF 收件匣的頻道。

還沒有帳號？先準備

  1. 登入 LINE Business ID
    用公司／學校的共用 email 註冊（也可以用個人 LINE 帳號登入，但共用 email 之後交接比較容易）。同一個 Business ID 可以管理多個官方帳號。
    LINE Official Account Manager ↗
  2. 建立 LINE 官方帳號
    按「建立帳號」，填帳號名稱（會顯示在使用者的聊天室與好友清單）、業種與國家。免費方案就能開始，之後再依訊息量升級。
    直接去建立帳號 ↗
  3. 關掉 LINE 內建的自動回應
    新帳號預設會自動回覆罐頭訊息。在該帳號的「設定 → 回應設定」把「自動回應訊息」與「加入好友的歡迎訊息」關閉、把「聊天」打開，改由 Herald 的劇本接手，否則兩邊會同時回話。
  4. 啟用 Messaging API
    在該帳號的「設定 → Messaging API → 啟用」，選一個 Provider（沒有就新建，通常填公司或學校名稱）。這一步會在 LINE Developers 產生對應的 channel——這才是 Herald 要接的東西。
    到 OA Manager 設定 ↗

已經有帳號的話這一段可以整段跳過。

連接到 Herald

  1. 抄下 Channel ID 與 Channel secret
    在 LINE Developers Console 打開該 channel →「Basic settings」分頁：最上方是 Channel ID（10 位數字），往下捲到 Channel secret。
    LINE Developers Console ↗
  2. 發行 Channel access token
    切到「Messaging API」分頁 → Channel access token (long-lived) → 按 Issue，複製整串。這串只會完整顯示一次，先貼到右邊欄位再說。
    LINE Developers Console ↗
  3. 按「驗證並啟用」
    Herald 會用這三個值呼叫 LINE 的 /v2/bot/info；成功才會存檔，失敗會保留原本可用的憑證。
  4. 把 Webhook URL 貼回 LINE
    啟用後複製本頁顯示的 Webhook URL →「Messaging API」分頁 → Webhook settings → 貼上、按 Verify、打開 Use webhook。沒有這一步，使用者的回話與加好友事件不會進到 Herald。
    LINE Developers Console ↗
  5. 用自己的手機加一次好友
    在 OA Manager 取得加好友的 QR 或連結，自己先加一次。有人加好友（follow）Herald 才會建立對應的聯絡對象——剛啟用時好友數是 0，推播自然沒有收件人。
    取得加好友連結 ↗
要填的欄位哪裡拿
Channel IDBasic settings 分頁最上方的數字。必填
Channel secretBasic settings 分頁；Herald 用它驗證 webhook 簽章。必填
Channel access token（long-lived）Messaging API 分頁按 Issue 產生；用來送訊息。必填
回貼 Webhook：貼到 LINE Developers →「Messaging API」→ Webhook settings，並打開 Use webhook。 主控台會在啟用後顯示這個組織專屬的網址。

「測試連線」做什麼：呼叫 LINE 的 /v2/bot/info，成功會顯示官方帳號名稱。不會送出任何訊息。

Email（SMTP）

沒有加好友、或推播失敗時的後備管道；正式通知留存也常靠它。

還沒有帳號？先準備

  1. 準備一個可對外寄信的 SMTP 帳號
    校內／公司郵件主機的服務帳號，或 SendGrid、Amazon SES、Mailgun 等服務開通後給的 SMTP 憑證。已經有現成的寄信帳號就跳過這步。

已經有帳號的話這一段可以整段跳過。

連接到 Herald

  1. 找出主機與連接埠
    587 = STARTTLS（最常見，建議）；465 = SSL。兩者 Herald 都支援，填錯埠會在驗證時就失敗。
  2. 取得帳號與密碼
    外部服務多半以 API key 當密碼（例如 SendGrid 的帳號固定是 apikey，密碼是 SG.xxx）。校內主機若允許內網轉送，帳密可以留空。
  3. 決定寄件地址
    必須是該主機／網域允許的地址，格式可用「台大傳訊 <noreply@ntu.edu.tw>」。請先在 DNS 設好 SPF / DKIM，否則容易被判為垃圾信。
  4. 按「驗證並啟用」
    Herald 會連上 SMTP 主機做一次登入驗證（SMTP verify），不會寄出任何信。
要填的欄位哪裡拿
SMTP 主機郵件主機網域或 IP。必填
連接埠587（STARTTLS）或 465（SSL）。選填
帳號免驗證的內部轉送可留空。選填
密碼 / API key以 HUB_SECRET_KEY 加密後儲存，之後只顯示「已設定」。選填
寄件地址收件者看到的寄件人；必須是主機允許的地址。必填

「測試連線」做什麼：對 SMTP 主機做一次連線與登入驗證（不會寄信）。

瀏覽器推播（Web Push）

學生在校園網站或 LIFF 訂閱後，用瀏覽器通知送達；可另接 FCM 給校園 App。

連接到 Herald

  1. 產生 VAPID 金鑰對
    按下面的「自動產生金鑰並啟用」最省事；也可以自己跑 npx web-push generate-vapid-keys 再貼進來。這一步不需要任何外部帳號。
  2. 填寫聯絡方式（subject）
    以 mailto: 或 https:// 開頭，例如 mailto:noreply@ntu.edu.tw。推播服務（Google／Mozilla）遇到問題時用它聯絡你。
  3. 把公開金鑰放進網頁前端
    網頁訂閱時 pushManager.subscribe 的 applicationServerKey 必須是同一組公開金鑰；換金鑰等於讓所有舊訂閱失效。訂閱成功後把整個 PushSubscription JSON 當作 address 註冊給 Herald（見下方 API）。
    Push API 說明（MDN） ↗
  4. 按「驗證並啟用」
    這個頻道的驗證完全在本機做：確認私鑰推得出公鑰、VAPID JWT 可簽可驗、subject 格式正確，不會連外。

要推到自己開發的 App（Android／iOS）？

同一個頻道也吃 FCM registration token：Herald 依地址形狀自動選 VAPID 或 FCM，所以組織裡有人用瀏覽器、有人用 App 都沒問題。注意同一個人在同一個管道只會保留最新的一筆地址——先訂閱網頁再註冊 App token，網頁那筆會被退役。iOS 也走 FCM（內部轉 APNs），不必另外接 APNs。

  1. 建立 Firebase 專案並加入你的 App
    Firebase 主控台 → 新增專案 → 加入 Android／iOS 應用程式，把 google-services.json／GoogleService-Info.plist 放進 App。iOS 另需在 Firebase 上傳 APNs 金鑰。
    Firebase 主控台 ↗
  2. 下載服務帳戶 JSON 並貼到上面的欄位
    專案設定 → 服務帳戶 → 產生新的私密金鑰，把整份 JSON 貼進「FCM 服務帳戶 JSON」。Herald 會用它換 OAuth token 呼叫 FCM HTTP v1。
    Admin SDK 設定說明 ↗
  3. App 取得 registration token
    Android／iOS 各自用 FCM SDK 取得 token（權限要先向使用者要）。換手機、重裝、清資料都會換一組，所以要在每次啟動時回報。
    Android 用戶端設定 ↗
  4. 把 token 註冊成這個人的地址
    由你的後端呼叫 Identity API：PUT /v1/subjects/{校內帳號}/addresses/webpush，body 帶 {"address":"<FCM token>","providerHint":"fcm","source":"app","verified":true}。同一支 API 重打即可換手機——舊 token 會在同一個請求裡退役。
    API 快速上手 ↗
  5. 確認分類的管道計畫含 webpush
    分類的 channel plan 沒有把 webpush 放進 preferred 或 fallback 的話，訊息永遠不會走這個管道。
要填的欄位哪裡拿
VAPID 公開金鑰base64url，前端訂閱時要用同一組。必填
VAPID 私密金鑰加密儲存；外洩等同可冒名推播。必填
聯絡方式（subject）必須是 mailto: 或 https:// 開頭。必填
FCM 服務帳戶 JSON（推到自製 App 才需要）見下方「要推到自己開發的 App」。選填

「測試連線」做什麼：本機驗證金鑰對與 VAPID JWT，不連外、不推播；FCM 的服務帳戶在第一次送出時才會被使用。

WhatsApp（Cloud API）

境外學生與國際交流常用；24 小時客服視窗外只能送已核准的範本訊息。

還沒有帳號？先準備

  1. 建立 Meta 商業帳號與應用程式
    Meta for Developers → 建立應用程式 → 類型選「企業」。需要一個 Meta 商業帳號（Business Manager），沒有的話建立流程中會一併帶你開。
    Meta for Developers ↗
  2. 加入 WhatsApp 產品並綁定門號
    在應用程式的產品清單加入 WhatsApp，依指示綁定一支可接收簡訊／電話驗證的門號（測試門號也可以）。這一步完成才會有 Phone number ID。
    Cloud API 入門文件 ↗

已經有帳號的話這一段可以整段跳過。

連接到 Herald

  1. 取得 Phone number ID
    WhatsApp → API Setup 頁面上的 Phone number ID（一串數字，不是電話號碼本身）。
  2. 取得 Access token
    同一頁的臨時 token 只能用 24 小時，正式上線請到「企業設定 → 系統使用者」建立 System User 並產生長期 token。
  3. 取得 App secret
    應用程式設定 → 基本資料 → 應用程式密鑰（App secret）。Herald 用它驗證 webhook 簽章。
  4. 自訂 Verify token
    這串由你自己決定（右邊已幫你產生一組），等一下在 Meta 設定 webhook 時要填一模一樣的值。
  5. 設定 Webhook 並訂閱欄位
    WhatsApp → Configuration → Webhook：Callback URL 填本頁的網址、Verify token 填上一步的值，然後訂閱 messages 欄位。
要填的欄位哪裡拿
Phone number IDAPI Setup 頁的數字 ID。必填
Access token建議用 System User 的長期 token。必填
App secret應用程式設定 → 基本資料。必填
Webhook verify token自訂字串；Meta 設定 webhook 時要填一樣的。必填
Graph API 版本（可選）留空則用 v20.0。選填
回貼 Webhook：填到 WhatsApp → Configuration → Webhook 的 Callback URL，並訂閱 messages 欄位。 主控台會在啟用後顯示這個組織專屬的網址。

「測試連線」做什麼：呼叫 Graph API 讀取該門號資料，成功會顯示已驗證名稱與品質評分。

Facebook Messenger

粉絲專頁私訊。24 小時視窗外的推播必須帶訊息標籤（tag）。

還沒有帳號？先準備

  1. 建立 Facebook 粉絲專頁
    客戶是私訊「粉絲專頁」而不是應用程式，所以要先有一個專頁。已經有的話跳過這步。
    建立粉絲專頁 ↗
  2. 建立 Meta App 並加入 Messenger
    Meta for Developers → 建立應用程式 → 在產品清單加入 Messenger。
    Meta for Developers ↗

已經有帳號的話這一段可以整段跳過。

連接到 Herald

  1. 連結粉絲專頁並產生 Page access token
    Messenger → 設定 → 存取權杖 → 加入粉絲專頁 → 產生權杖。專頁 ID 在專頁的「關於」頁或同一區塊可看到。
  2. 取得 App secret
    應用程式設定 → 基本資料 → 應用程式密鑰，用來驗證 webhook 簽章。
  3. 自訂 Verify token
    右邊已幫你產生一組，Meta 設定 webhook 時要填一樣的值。
  4. 設定 Webhook 並訂閱欄位
    Messenger → 設定 → Webhooks：Callback URL 填本頁網址、Verify token 填上一步的值，訂閱 messages 與 messaging_postbacks。
  5. 選一個預設訊息標籤
    超過 24 小時客服視窗的推播，Meta 要求帶 tag。校園通知一般用 CONFIRMED_EVENT_UPDATE（活動提醒）或 ACCOUNT_UPDATE（帳號狀態）。
要填的欄位哪裡拿
粉絲專頁 ID權杖必須屬於這個專頁，否則驗證會失敗。必填
Page access tokenMessenger → 設定 → 存取權杖產生。必填
App secret應用程式設定 → 基本資料。必填
Webhook verify token自訂字串；Meta 設定 webhook 時要填一樣的。必填
預設訊息標籤（可選）超過 24 小時視窗的推播會帶上這個標籤。選填
回貼 Webhook：填到 Messenger → 設定 → Webhooks 的 Callback URL，並訂閱 messages、messaging_postbacks。 主控台會在啟用後顯示這個組織專屬的網址。

「測試連線」做什麼：呼叫 Graph API 的 /me，成功會顯示專頁名稱，並確認權杖屬於填入的專頁 ID。

‹ 登入與單位切換新增訊息三步驟 ›