LINE 訊息組(預覽)
狀態:預覽(
preview),2026-10-19 加入。 契約已定案、可以呼叫,但尚未適用正式版的支援與棄用保證:欄位、錯誤細節與行為在轉為ga之前仍可能調整,調整會照版本與棄用公告。轉為ga時會在變更紀錄公告。
LINE 訊息組是租戶在後台預先編好的一組 LINE 訊息(例如一班課的課前影片與說明文字)。這兩個操作讓租戶自己的後台工具以機器流程讀出它們,再用租戶自己的 LINE 官方帳號送出。
| 能力 | 操作 | 作用 |
|---|---|---|
lightup.line.message_group.read |
GET /v1/line-message-groups?name=… |
以完整名稱查訊息組(最多 10 個) |
lightup.line.message_group.read |
GET /v1/line-message-groups/{groupId} |
讀取一個訊息組 |
本 API 沒有建立、修改、刪除訊息組或代為發送的操作;發送不經過本 API。
範圍與授權
- 只限機器流程。 呼叫者必須持有 service account 的 token(
client_credentials,workload,TTL 15 分,沒有 refresh)。使用者本人的 token 會得到 403profile_not_supported——換成機器流程才行。 - 方案等級 L2 起。 低於 L2 的租戶會得到 403
plan_capability_excluded。 - 資源是租戶。 訊息組是租戶自己的內容,不是某個人的資料;只看得到這張 token 的租戶的訊息組,別的租戶的一律當成不存在(404)。
- 租戶要先核准(見登記與憑證)。在 2026-10-19 之前核准的授權不會自動多出這一項,要用到它,租戶要重新核准;之後新記錄的「開全部」會包含它。
以名稱查:GET /v1/line-message-groups?name=…
GET https://api.lightup.tech/v1/line-message-groups?name=%E6%B0%B8%E5%92%8C%20%E9%80%B1%E5%85%AD%2010%3A00%20%E8%AA%B2%E5%89%8D%E5%BD%B1%E7%89%87
Authorization: Bearer <workload token>
- 只收一個查詢參數
name,而且只能出現一次。 帶了其他參數、重複的name、空白,或去掉前後空白後超過 200 個字元(以 Unicode 字元計),都是 422schema_invalid,在判權之前就回。 - 完全相同才算。 平台把
name與每個訊息組的名稱都去掉前後空白再比,必須一模一樣;這不是模糊搜尋。 - 依 id 排序,最多 10 個。
{
"name": "永和 週六 10:00 課前影片",
"matched": 1,
"truncated": false,
"items": [
{
"id": "6f2d1c0e-9a77-4f39-9b1a-0b5d6a3e2f0c",
"name": "永和 週六 10:00 課前影片",
"updatedAt": "2026-10-18T09:30:15.250Z",
"messages": [
{ "type": "text", "text": "明天見!", "complete": true },
{ "type": "video", "originalContentId": "m-1", "previewImageId": "m-2", "complete": true }
]
}
]
}
| 欄位 | 意思 |
|---|---|
name |
比對用的名稱(去掉前後空白後) |
matched |
回來的訊息組數,等於 items 的長度;沒有符合的也是 200,matched 為 0 |
truncated |
true 表示符合的不只回來的這 10 個 |
items |
符合的訊息組 |
你的流程要求「剛好一個」時(例如一班一個課前影片組),只在 matched 是 1 而且 truncated 是 false 時才用它;其他情況不要自己挑一個,請租戶在後台把名稱整理成唯一。
讀取一個:GET /v1/line-message-groups/{groupId}
GET https://api.lightup.tech/v1/line-message-groups/{groupId}
Authorization: Bearer <workload token>
回傳一個訊息組,形狀與上面 items 裡的一個相同。
groupId是 1–64 個[A-Za-z0-9_-]。從舊系統搬來的 id 原樣保留,所以不一定是 UUID——不要用 UUID 格式去檢查它。形狀不合 → 404,在判權之前就回。- 訊息組不存在,或屬於別的租戶 → 404
not_found,不分辨。
訊息的形狀
訊息組的 updatedAt 是 RFC 3339、UTC、毫秒精度的時間。messages 依原本的順序,每一則只有下面這些欄位:
type |
帶什麼 |
|---|---|
text |
text:訊息文字 |
image、video |
originalContentId、previewImageId:媒體 id,不是網址 |
其他類型,或 null(存的訊息沒有類型) |
只有 type 與 complete: false |
每一則都有 type(字串或 null)與 complete(布林)。
complete: false 的訊息組不要送
complete 是平台告訴你「這則訊息的內容是否完整交給你了」。它在兩種情況會是 false:
- 這一版 API 不認得的訊息類型(例如 Flex 訊息),平台只告訴你它的類型;
- 訊息帶了平台沒有交給你的欄位。
照著不完整的內容送出去,客戶收到的會和租戶編的不一樣。只要訊息組裡有一則 complete 是 false,就不要送這個訊息組,改請租戶在後台處理。
媒體 id 不是網址
originalContentId 與 previewImageId 是平台的媒體 id,不能直接當成網址放進 LINE 訊息。本 API 目前沒有用媒體 id 取得檔案或網址的操作;請依你和租戶約定的方式處理。
錯誤處理
| 狀態與代碼 | 意思 | 怎麼做 |
|---|---|---|
401 invalid_token |
token 本身不可用 | 換一張新的機器 token,再試一次;仍失敗就停 |
403 profile_not_supported |
這是使用者本人的 token | 改用機器流程(workload)的 token |
403 capability_not_granted、plan_capability_excluded、tenant_not_enabled 等 |
授權或方案不准 | 不要重試。照錯誤・限流・重試的 403 表格,找租戶管理員處理 |
404 not_found |
訊息組不存在、不屬於這個租戶,或 groupId 形狀不合 |
確認 id 來自 ?name= 的回應,不是自己拼的 |
422 schema_invalid |
查詢參數不對(不是剛好一個 name、空白、太長,或帶了其他參數) |
修正請求。不要原樣重送 |
429 rate_limited |
限流 | 依 Retry-After 等待後再試,加上抖動 |
503 authorization_unavailable |
現在判不了(授權服務或訊息服務暫時不可用) | 指數退避後重試 |
兩個操作都是 GET,天然冪等,可以安全重送。