---
title: HTTP API
description: LINE Agent SDK 的 HTTP API，給不用 MCP 的程式：建立 LINE 連線、讀取每一步輪到誰，上線後傳訊息。AI 工具碰不到任何金鑰。
url: https://agentlab.cresclab.com/docs/zh-tw/line/api
language: zh-Hant
updated: 2026-10-24
---

# HTTP API

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

## 連線網址

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

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

架設方式見[在 Agent Lab 架設 LINE OA MCP](https://agentlab.cresclab.com/docs/zh-tw/line/quickstart.md)。

> [!NOTE] 用 MCP 比較簡單
> 支援 MCP 的 AI 工具（Claude Code、Codex、Cursor）可以直接用 [LINE OA MCP](https://agentlab.cresclab.com/docs/zh-tw/line/mcp-tools.md)，工具和這份 API 做的事一樣。執行中的服務也會在 `/agent.md` 提供給 AI 讀的說明。

## 驗證

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

```http
Authorization: Bearer <Agent 權杖>
```

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

> [!WARNING] 不要把權杖貼進對話
> 請本人把 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`。

> [!NOTE] 推播會用到額度
> 推播（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，不需要手動貼上。