LightUp 第三方 API 契約已定案・端點已上線 v1.0.0 · 707394544381

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。

範圍與授權

以名稱查: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": "永和 週六 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 裡的一個相同。

訊息的形狀

訊息組的 updatedAt 是 RFC 3339、UTC、毫秒精度的時間。messages 依原本的順序,每一則只有下面這些欄位:

type 帶什麼
text text:訊息文字
image、video originalContentId、previewImageId:媒體 id,不是網址
其他類型,或 null(存的訊息沒有類型) 只有 type 與 complete: false

每一則都有 type(字串或 null)與 complete(布林)。

complete: false 的訊息組不要送

complete 是平台告訴你「這則訊息的內容是否完整交給你了」。它在兩種情況會是 false:

照著不完整的內容送出去,客戶收到的會和租戶編的不一樣。只要訊息組裡有一則 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,天然冪等,可以安全重送。

注意事項