這一頁是這個服務的單一參考:設計模型在前,API 契約在後。 閱讀慣例貫穿全篇 —— 襯線體是「為什麼」(設計理由與取捨), 無襯線體是「是什麼」(規格),等寬體是字面值(路徑、代碼、JSON)。 這裡寫的行為不會在沒有預告的情況下改變;沒寫的一律不保證。
為什麼存在
每個專案各自持有 LINE access token 與 Telegram bot token 時,憑證外洩的爆炸半徑是「所有專案」。 把憑證收攏到一個服務之後,新增一個專案就是發一把 token, 而那把 token 送不出任何東西給它範圍以外的人,也永遠看不到憑證本身。
第二個理由是領域無關。訊息契約是 {title, lines, link},
服務不理解訊息在講什麼,也不得依內容改變投遞行為。一旦長出「股票」「策略」這類欄位,
它就不再是通用的 IM 服務,而是某一個產品的一部分。
邊界
這條線是硬的。它決定了每一次「這個功能該做在哪一邊」的爭論。
服務管
- 租戶與其隔離
- channel 憑證(永不外流)
- recipients 名冊與 profile
- topic 訂閱狀態
- fan-out、冪等、投遞紀錄
- 頻率限制與大量發送的佇列
- webhook 驗證與名冊維護
呼叫端管
- 訊息內容與何時發送
- topic 的命名與意義
- 自助訂閱介面(LIFF 等)
- 終端使用者的身分驗證
- 重試策略
- 失敗後要不要讓工作流程失敗
「終端使用者的身分驗證」這一條容易被誤放。服務只看得到呼叫端的 service token, 結構上無法確認請求背後是哪一個真人—— 所以自助訂閱介面必須由呼叫端自己驗(例如驗 LINE 的 ID token),不能把 caller token 下放到前端。
資料模型
delivery 紀錄橫跨全部:(tenant, topic, dedupe_key, recipient) 是冪等的權威
| 關係 | 基數 | 強度 |
|---|---|---|
| recipient → channel | 多對一 | 硬約束。複合外鍵 (tenant_id, channel_id) 加唯一索引,跨租戶的組合在 schema 層級不存在 |
| recipient ↔ topic | 多對多 | 由 subscriptions 建模。取消是標記 cancelled_at 而非刪除,所以「某人在某個時間點該不該收到」可以事後查證 |
| topic ↔ channel | 多對多 | 沒有被建模。經由 recipient 湧現 —— 一個 topic 的收件人可以散在多個 channel |
recipient 屬於且只屬於一個 channel。 同一個人在 LINE 與 Telegram 上是兩筆獨立的 recipient,各自訂閱、各自的封鎖狀態。 這不是簡化,是事實:LINE 的 userId 每個 OA 一組,跨 channel 認同一個人在技術上做不到。
認證與範圍
Authorization: Bearer <caller token>
租戶身分只從 token 解析。
服務不接受以 body、query string 或 header 指定 tenant_id,傳了也不會有任何作用。
每把 token 帶一組 allowed_topics,三種比對模式:
| 模式 | 意義 |
|---|---|
* | 該租戶底下所有 topic |
tw-stock.* | 前綴比對,涵蓋 tw-stock.analysis |
daily | 完全相同 |
萬用字元只在結尾有意義;空字串不是有效模式,不會被當成放行全部。 撤銷即時生效 —— 每次請求直接查資料庫,不快取。
觀察不設限,改變才檢查範圍。 這條原則決定了哪些端點檢查
allowed_topics:讀取類(名冊、訂閱、topic 清單)一律不檢查,
因為看得到誰沒訂閱才能回答「他為什麼沒收到」;寫入類一律檢查,
因為能改變某 topic 的收件範圍,等於一把送不了該 topic 的 token 可以決定那些訊息送給誰。
端點總覽呼叫端可用 5 條
| 端點 | 用途 | 範圍檢查 | 限流 |
|---|---|---|---|
POST /v1/messages |
發送給某個 topic 的訂閱者 | 檢查 | 60 / 60s |
GET /v1/topics |
有哪些 topic、誰在聽、我能送哪些 | 不檢查 | 無 |
PUT /v1/topics |
宣告或撤銷一個 topic | 檢查 | 無 |
GET /v1/recipients |
名冊,含不可投遞者與原因(分頁) | 不檢查 | 無 |
GET /v1/subscriptions |
單一使用者目前訂了什麼 | 不檢查 | 無 |
PUT /v1/subscriptions |
設定某人對某 topic 的訂閱狀態 | 檢查 | 無 |
另有 POST /v1/webhook/{line|telegram}/{channel_id},那是給 LINE 與 Telegram
呼叫的,不對呼叫端開放;以及 /admin/api/*(22 條),由 Cloudflare Access 保護。
發送
{
"topic": "tw-stock.analysis",
"dedupe_key": "analysis-daily-2026-09-07",
"message": {
"title": "9/7 盤後籌碼",
"lines": ["外資買超 120 億", "投信連三買"],
"link": { "text": "看完整報表", "url": "https://analysis.tw-stock.selfcloud.tw/" }
},
"overrides": { "telegram": { "text": "*9/7 盤後*", "parse_mode": "MarkdownV2" } },
"recipients": ["U123abc", "987654321"]
}
| 欄位 | 必填 | 限制與說明 |
|---|---|---|
topic | 是 | ≤ 200 字元。不在 allowed_topics 內回 403 |
message.title | 是 | ≤ 200 字元 |
message.lines | 是 | 非空陣列,≤ 100 行,每行 ≤ 2000 字元 |
message.link | 否 | {text, url},url 必須是絕對的 http/https |
dedupe_key | 否 | ≤ 200 字元。省略即不做重複判定 |
overrides | 否 | channel 原生格式,優先於預設渲染 |
recipients | 否 | ≤ 500 筆,每筆 ≤ 200 字元。只會縮小範圍 |
預設渲染
標題、每一行、連結,以換行串接成純文字:
9/7 盤後籌碼 外資買超 120 億 投信連三買 看完整報表: https://analysis.tw-stock.selfcloud.tw/
超過 channel 上限時截斷而非丟棄(LINE 5000 字元、Telegram 4096),
並在回應中 truncated: true。
指名收件者只會縮小範圍
服務是從訂閱者出發做篩選,而不是從指名出發去查人。
前者不可能送給未訂閱者,後者只要漏一個檢查就會 —— 授權邊界因此是結構性的,
不靠記得檢查。被指名卻不在訂閱者中的識別字會出現在 unmatched,並讓整體不算成功。
空陣列是 400 而不是「送給零個人」:算出零個對象幾乎一定是呼叫端的 bug, 靜默回報成功會讓那個 bug 一直看起來像正常運作。省略這個欄位才是「不指名」。
原生格式覆寫
存在時優先於預設渲染,服務不會退回預設——那會讓呼叫端誤以為覆寫已生效。格式不合法時整則請求回 400,不會先送出一部分。
overrides.line { "messages": [ { "type": "text", "text": "..." } ] } 1–5 則,每則需要 type
overrides.telegram { "text": "...", "parse_mode": "Markdown" } text ≤ 4096
parse_mode: Markdown | MarkdownV2 | HTML
chat_id 與 disable_web_page_preview 由服務填入,傳了也會被覆蓋。
冪等
dedupe_key 的權威是投遞紀錄本身,而且是 per-recipient 的:
- 全部失敗過的請求 → 不佔用 key → 重試會全部重送
- 部分成功過的請求 → 只扣除已成功者 → 重試只補送未成功的人
- 省略
dedupe_key→ 不做任何重複判定,重送就是再送一次
紀錄保留 90 天,之後相同的 key 不再被視為重複。保留期必須明顯長於你的重試間隔。
狀態碼與原因代碼
狀態碼反映的是投遞結果,不是 HTTP 層的成敗。 判準只有一個:每一位該收到的人,是不是都收到了。
| 碼 | 意義 |
|---|---|
| 200 | 是。每位訂閱者不是這次送達、就是先前已送達。沒有訂閱者也算 200 |
| 202 | 收件者超過同步門檻,已排入佇列,本次一則都還沒送出 |
| 207 | 否,但至少有人收到,或未送達的原因不是上游故障(被封鎖而略過、指名的人不在訂閱者裡) |
| 502 | 一位都沒收到,且原因全是投遞失敗 |
{
"topic": "tw-stock.analysis",
"dedupe_key": "analysis-daily-2026-09-07",
"delivered": 12, "failed": 1, "skipped": 2, "already_delivered": 0,
"unmatched": [], "truncated": false,
"results": [
{ "recipient_id": "...", "status": "delivered" },
{ "recipient_id": "...", "status": "failed", "reason_code": "recipient_unreachable" },
{ "recipient_id": "...", "status": "skipped", "reason_code": "recipient_skipped" }
]
}
202 的 delivered: 0 不是失敗。 那批還沒開始送,另有 queued 表示排入人數。用 dedupe_key 到後台的投遞紀錄追進度。
送達零人時會多一個 topic_registered。 true 代表 topic 是真的、只是沒人訂;false 代表沒有人宣告過這個名字,多半是打錯字。只在零人時查詢,順利的路徑不多付成本。
原因代碼
| 代碼 | 性質 | 意義 |
|---|---|---|
channel_quota_exceeded | 暫時 | channel 回報已達發送額度上限 |
channel_timeout | 暫時 | 對 channel 的請求逾時 |
channel_unavailable | 暫時 | channel 回 5xx,或連線失敗 |
channel_unauthorized | 永久 | channel 憑證無效或未授權 |
channel_misconfigured | 永久 | 本服務設定有問題:憑證解不出來,或該 kind 沒有註冊 adapter |
channel_rejected | 永久 | channel 拒絕了這則投遞,原因未分類 |
recipient_unreachable | 永久 | 使用者已封鎖或帳號失效。該 recipient 會被標記為不可投遞 |
recipient_skipped | — | 該 recipient 目前被標記為不可投遞,本次略過 |
channel_rejected 存在的理由是誠實。在它之前,未分類的失敗會被歸成
channel_misconfigured——一個宣稱特定成因的代碼被用在成因未知的地方。
2026-08-12 有一次故障因此把排查引向憑證,花了三輪才發現真正的原因是收件者不存在於該 channel。
現在未分類就是未分類,而真正的線索(channel 回應的狀態碼與原文)留在投遞紀錄裡。
Topic
topic 沒有外鍵、不需要事先註冊。token 範圍允許的前提下,
直接用一個新名字就等於建立了它 —— tw-stock.* 這種 scope 的存在,
就是為了讓 app 自己開新 topic 而不必找人。登記簿因此是描述性的,不是開通手續。
{
"allowed_topics": ["tw-stock.analysis*"],
"topics": [
{ "name": "tw-stock.analysis-digest", "registered": true, "subscribers": 2, "sendable": true },
{ "name": "tw-stock.reports", "registered": false, "subscribers": 4, "sendable": false }
]
}
清單是已宣告 ∪ 實際被訂閱。兩個集合的落差就是訊號:
| 樣態 | 代表 |
|---|---|
| 已宣告、零訂閱者 | topic 是真的,只是還沒有人訂 |
| 未宣告、有訂閱者 | 有人在用一個沒宣告過的名字 |
在 allowed_topics 卻不在清單裡 | 從來沒有人訂過它。如果你的 app 正在對它發送,那就是在空轉 |
{ "name": "tw-stock.analysis-foo", "registered": true }
兩個欄位都必填,name ≤ 200 字元,registered 必須是布林且沒有預設值。
名字放在 body 不放路徑 —— topic 是自由字串,塞進路徑會多一層編碼問題。
撤銷宣告不會取消任何訂閱。 刪掉一個名字不該讓已經在收的人靜默停收,那是兩個不同的決定。
把你在用的 topic 用 PUT /v1/topics 宣告一次,之後看到回應裡的 topic_registered: false 就當成錯誤處理。這比在 CI 對照清單更即時,也不需要額外的部署步驟。
名冊與訂閱
GET /v1/recipients?topic=tw-stock.analysis&channel_id=channel-...&limit=100&cursor=...
{
"recipients": [{
"external_id": "U123abc", "display_name": "Raymond",
"picture_url": "https://...", "deliverable": true,
"undeliverable_reason": null, "undeliverable_at": null,
"topics": ["tw-stock.analysis", "tw-stock.reports"]
}],
"next_cursor": "MjAyNi0wOS0wM..."
}
limit 預設 100、上限 200,超過回 400 而不是默默降低——
默默降低會讓你把「回應比 limit 少」誤讀成「沒有更多了」而忽略 next_cursor。
cursor 解不開同樣回 400,不靜默從頭開始。
回應包含不可投遞者並標示原因。濾掉他們會讓你無法解釋「他為什麼沒收到」。
回應與 PUT 完全同一個形狀——寫進去什麼,讀回來就是什麼。三種情況要分開處理:
| 回應 | 情況 | 介面該做什麼 |
|---|---|---|
| 200 topics 有內容 | 在名冊上、有訂閱 | 顯示已勾選的開關 |
200 topics: [] | 在名冊上、沒訂閱 | 顯示未勾選的開關 |
| 404 | 不在名冊上 | 請他先加好友 |
{ "channel_id": "channel-...", "external_id": "U123abc",
"topic": "tw-stock.analysis", "subscribed": true }
四個欄位都必填;三個字串各 ≤ 200 字元。subscribed 必須是布林且沒有預設值——省略時預設為 true 的話,一個組錯的請求會變成「訂閱」,而訂閱的錯誤方向是把訊息送給不該收的人。
宣告式,不是動詞式。 送的是要的結果,重送同一個請求不產生第二筆。 動詞式介面會逼呼叫端先讀狀態再決定送什麼,而讀與寫之間的空隙在兩個管理員同時操作時會出錯。
不建立 recipient。 指定的組合不存在時回 404。 順手建立的話,一個打錯的識別字會產生一筆在名冊上與真人無異、卻永遠送不到的 recipient。 找不到通常代表對方還沒加好友 —— 而那正是要顯示給操作者的事實。
LIFF 前端 → 你的後端 → im-service。 caller token 帶著整個租戶的發送權限,絕不能出現在瀏覽器裡。後端還必須驗 liff.getIDToken(),否則任何人都能拿別人的 userId 改別人的訂閱。
LIFF 的 LINE Login channel 與 OA 的 Messaging API channel 必須在同一個 provider。 不同 provider 的 userId 是不同的值,名冊裡對不上,PUT 會回 404。好消息是這個失敗很大聲,不會默默長出假人。
收訊行為webhook,不對呼叫端開放
POST /v1/webhook/{line|telegram}/{channel_id} —— 這條路徑必須維持公開,
因為 LINE 與 Telegram 的伺服器在公網上。安全性來自驗證,不是來自隱藏。
| Channel | 驗證方式 | 建立名冊 | 標記不可投遞 |
|---|---|---|---|
| LINE | x-line-signatureHMAC-SHA256,固定時間比較 |
follow |
unfollow → unfollowed |
| Telegram | x-telegram-bot-api-secret-token由服務產生,固定時間比較 |
/startmy_chat_member → member / administrator / creator |
my_chat_member → kicked = blocked→ left = removed |
加入時套用該 channel 的 default_topics。
不可投遞不會刪除訂閱——使用者解除封鎖後重新加入即自動恢復,不需要人工重設。
一般訊息不解讀、不建立 recipient。加入名冊是一個明確的動作,
而兩個平台對每一位私訊使用者都必然先送出加入事件,所以不會因此漏掉任何人。
訂閱指令這類需求屬於呼叫端 —— 指令語彙是產品決定,服務一旦開始解讀訊息內容,
就不再是領域無關的。設定 forward_url 之後原始 payload 會原封轉發給下游自行處理。
運作限制
| 項目 | 值 | 為什麼是這個值 |
|---|---|---|
| 發送頻率 | 60 次 / 60 秒 | key 是 token id 而非租戶,同租戶的不同呼叫端互不影響。超限不建立投遞紀錄、不佔用 dedupe_key |
| 同步 fan-out 上限 | 40 人 | Workers Free plan 每次呼叫 50 個 subrequest,D1 查詢也算。同步路徑約在 43 人斷掉,40 留餘裕。升級 Paid(10,000)後可設到 900 |
| 佇列批次 | 10 則 / 次 | 同一 dedupe_key 併成一次 dispatch,一批約 13 個 subrequest。調大會直接吃掉這個保護 |
| 佇列訊息保留 | 24 小時 | Free plan 不可調。consumer 壞掉超過一天那批就沒了 —— 已知代價 |
| 投遞紀錄保留 | 90 天 | 屆期清除,之後相同 dedupe_key 不再視為重複 |
| Profile 更新 | TTL 7 天 · 50 筆/日 | channel 沒有批次取 profile 的端點,也沒有變更通知,輪詢是唯一手段 |
| 訊息長度 | LINE 5000 · TG 4096 | 超過截斷而非丟棄,並回報 truncated |
刻意不做的事
寫出來是為了讓邊界明確,不是待辦清單。這些不是還沒做,是決定不做。
-
不含領域知識
訊息契約永遠是
{title, lines, link}。需要 channel 的原生表達能力時走 overrides,而不是往契約裡加欄位。 -
不建立 recipient
只有 channel 的真實事件(加好友、
/start、bot 被加進群組)或明確的 provisioning 會建立。bot 本來就無法主動聯繫從未互動過的對象,手動建立只會長出永遠收不到訊息的假人。 - 不讓呼叫端拿到 channel 憑證 這是這個服務存在的主要理由。憑證只在服務內部從 D1 取出,不進 log、不進投遞紀錄、不進佇列訊息。
-
不讓呼叫端繞過訂閱
訂閱是授權邊界。後台有一條不看訂閱的直接推播路徑,那條刻意只給 Cloudflare Access 保護的
/admin/,不對持有 caller token 的呼叫端開放。 - 不重試 暫時性失敗由呼叫端決定要不要重試,而 per-recipient 的冪等機制保證那是安全的。服務自己重試會讓「送了幾次」這件事失去單一答案。
- 不強制 topic 先宣告 目前如此。等登記簿累積出實際使用狀況,再決定要不要把「未宣告即拒送」變成硬規則 —— 屆時只剩 backfill 與一個開關。
後台與存取模型
/admin/ 有六個分頁:推播、收件者、通道、Topic、API token、投遞紀錄。
後台的推播與呼叫端的 POST /v1/messages 走同一條投遞路徑,
所以冪等、投遞紀錄與不可投遞標記完全一致 —— 後台送的訊息與呼叫端送的在資料上是同一種形狀。
| 路徑 | 保護方式 | 狀態 |
|---|---|---|
/admin/* | Cloudflare Access(人) | 已啟用 |
/v1/*(webhook 除外) | caller API token | 已啟用 |
| 同上 | Access Service Token(機器) | 計畫中 |
/v1/webhook/* | 簽章 / secret token | 維持公開 |
caller token 不是要被取代的東西。tenant_id 只能從它解析出來,
它是路由機制而不只是權限機制 —— Access 是額外的一層,不是替代品。