HTTP API

LINE Agent SDK 的 HTTP API，給不用 MCP 的程式：建立 LINE 連線、讀取每一步輪到誰，上線後傳訊息。AI 工具碰不到任何金鑰。

最後更新 2026-10-24

連線網址#

API 在你架設的服務底下，路徑都以 /api 開頭：

text

https://line-oa-mcp--<組織>.hosting.agentlab.run/api

架設方式見在 Agent Lab 架設 LINE OA MCP。

用 MCP 比較簡單

支援 MCP 的 AI 工具（Claude Code、Codex、Cursor）可以直接用 LINE OA MCP，工具和這份 API 做的事一樣。執行中的服務也會在 /agent.md 提供給 AI 讀的說明。

驗證#

每個 /api 請求都要帶 Agent 權杖。用 Google 登入控制台後，在 Agent 權杖 頁（/tokens）產生：

http

Authorization: Bearer <Agent 權杖>

沒帶、不對或已撤銷時回傳 401。權杖只顯示一次，不用時在同一頁撤銷。

不要把權杖貼進對話

請本人把 Agent 權杖放進 AI 工具的環境變數（例如 LINE_AGENT_SDK_TOKEN），不要貼在聊天裡。Channel Secret 也一樣，只在控制台的頁面上填。

1. 建立連線#

方法與路徑	用途
`POST /api/connections`	建立一條連線，接上既有的 LINE 官方帳號。回傳連線物件，包含要交給人的 `setupUrl`。
`GET /api/connections`	列出所有連線。
`GET /api/connections/{id}`	讀一條連線目前的狀態。每次讀取時，服務也會順便檢查人在 LINE 那邊做完了沒有。

http

POST /api/connections
Content-Type: application/json

{ "workspace": "acme", "label": "官網客服帳號" }

workspace 和 label 都可以省略。建立後，把回傳的 setupUrl 給本人：Channel ID 和 Channel Secret 只在那個頁面上填。

2. 等每一步完成#

連線物件的 nextStep 說明現在輪到誰、要做什麼、怎麼算完成：

json

{
  "id": "conn_9f3a1c2b4d5e",
  "state": "webhook_active",
  "live": false,
  "nextStep": {
    "key": "webhook_active",
    "title": "打開「Use webhook」",
    "actor": "human",
    "status": "current",
    "doneWhen": "LINE 回報 webhook active = true（每 2 秒自動偵測，不用回來按）",
    "how": "LINE Developers › Messaging API › Webhook settings › Use webhook 打開。",
    "url": "https://developers.line.biz/console/"
  }
}

actor 是 human 時，把 title、how 和 url 告訴本人，然後繼續讀取連線。做完會自動往下走，不用問對方「好了嗎」。
actor 是 ops 時，是架設服務的營運方在處理，告訴本人正在進行中。
actor 是 agent 時，服務會自己完成。
status 是 error 時，原因在 note。

建議每 2 到 5 秒讀一次。live 變成 true 時，第一則 LINE 訊息已經送到本人的手機。

步驟

`key`	誰做	完成條件
`credentials`	人	用 Channel ID 和 Channel Secret 換到 token。
`health`	自動	讀完帳號資訊、聊天模式、webhook、額度與好友數，沒有改任何設定。
`mode`	人	在控制台選定「只發不收／轉發／直接接手」其中一種。
`webhook_set`	自動	把 webhook 網址設成這個服務，並讀回確認。
`webhook_active`	人	在 LINE Developers 打開「Use webhook」，服務自動偵測。
`auto_reply`	人	在 OA Manager 關掉自動回應訊息，並在控制台按「我已關閉」。
`pair`	人	用手機加好友，傳配對碼（`pairingCode`）。
`first_message`	自動	回覆配對訊息成功。

選「只發不收」時，webhook_set、webhook_active、auto_reply 會標成 skipped，pair 改成貼上一個測試用的 userId。選「轉發」時，auto_reply 會略過，原系統的設定維持原樣。

3. 傳訊息#

方法與路徑	用途
`POST /api/connections/{id}/messages`	用推播傳一則文字訊息給配對過的測試帳號。

http

POST /api/connections/conn_9f3a1c2b4d5e/messages
Content-Type: application/json

{ "text": "您的訂單已出貨" }

json

{ "ok": true, "to": "paired test user" }

連線還沒上線時回傳 409，並附上 nextStep。

推播會用到額度

推播（push）算在官方帳號的每月訊息額度裡；回覆（reply）不算。測試帳號傳訊息給官方帳號時，Agent 用回覆回答，只有回覆期限過了才改用推播。

Sandbox#

還沒有官方帳號時，可以先用營運方設定好的共用 Sandbox 帳號試：

方法與路徑	用途
`POST /api/sandbox`	拿一組 join 碼。回傳 `joinText`（例如 `join blue-fox-42`）和 Sandbox 帳號的 `account.addFriendUrl`。
`GET /api/sandbox/{id}`	讀這組 Sandbox 的狀態，`live` 為 `true` 時第一則訊息已送到。

把 addFriendUrl 和 joinText 給本人：加好友後傳那一行字，手機就綁到這個工作區。Sandbox 只能傳給 join 過的手機，好友關係不會帶到正式帳號。

連線物件#

欄位	說明
`id`	連線 ID，之後的呼叫都用它。
`state`	目前那一步的 `key`；全部完成時是 `live`。
`live`	第一則訊息已送到時為 `true`。
`mode`	`push_only`、`relay`、`direct`，還沒選時是 `null`。
`account`	官方帳號的 `basicId`、`displayName` 和 `addFriendUrl`。健檢完成前是 `null`。
`pairingCode`	要在手機上傳給官方帳號的配對碼，例如 `AL-7Q4K`。
`tester`	配對成功的測試帳號 `userId`。
`webhookUrl`	這條連線的 webhook 網址，服務會自己設定到 LINE。
`setupUrl`	交給人的控制台頁面。
`steps`	所有步驟，每一步有 `key`、`title`、`actor`、`status`、`doneWhen`，以及可能有的 `how`、`url`、`note`。
`nextStep`	目前要處理的那一步；全部完成時是 `null`。

錯誤#

狀態碼	意思	要怎麼做
`400`	請求內容不對，例如 `text` 是空的。原因在 `error`。	修正後再送。
`401`	沒帶權杖、權杖不對或已撤銷。	確認 `Authorization: Bearer <Agent 權杖>`。
`404`	找不到這條連線或這組 Sandbox。	確認 `id`。
`409`	連線還沒上線，不能傳訊息。	依照回應裡的 `nextStep` 繼續。

Webhook#

POST /hooks/line/{id} 是給 LINE 平台呼叫的，不需要權杖，但每個請求都要通過 x-line-signature 簽章驗證，不對時回傳 401。這個網址由服務在 webhook_set 那一步自己設定到 LINE，不需要手動貼上。