> For the complete documentation index, see [llms.txt](https://help.firstline.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.firstline.cc/feature/channels/headless-api.md).

# 自訂管道

透過自訂管道，將企業自行開發的網站、App 或服務介面連接至 FIRST LINE，使用 AI 代理、交談腳本與真人客服。

{% hint style="info" %}
**自訂管道目前為 Beta 功能，預計為 2027 Q1 正式發佈。** 功能、API 規格與可用範圍可能持續調整，實際使用時請以 FIRST LINE 系統介面及最新公告為準。
{% endhint %}

## 概述

**自訂管道** 讓企業不必使用 FIRST LINE 提供的聊天視窗，也能透過自行開發的網站、App 或其他服務介面，將客戶訊息傳送至 FIRST LINE，並接收後續回覆。

例如，企業已有自己的會員中心或 App，希望沿用現有介面，卻也想讓客戶透過 FIRST LINE 的 **Fancy AI 代理**、**交談腳本**或**真人客服**獲得協助，就可以使用自訂管道。

運作方式如下：

1. 客戶在企業自有介面輸入訊息。
2. 企業後端透過 Headless Conversation API 將訊息送到 FIRST LINE。
3. FIRST LINE 依照管道的接待設定，由 AI 代理或交談腳本處理；需要時也能轉交真人客服。
4. 企業後端透過 Webhook 或事件查詢取得回覆，再顯示在自家介面。

自訂管道提供的是**對話服務的串接能力**，不會自動產生網站聊天介面。訊息呈現、使用者登入及前端互動等部分，仍由企業自行開發與維護。

{% hint style="info" %}
這項功能適合具備開發資源、希望保留自有介面與操作體驗的企業。若只是希望快速在網站上加入 FIRST LINE 聊天視窗，建議使用既有的 [即時聊天](/feature/channels/live-chat.md) 管道。
{% endhint %}

***

## 建立自訂管道

{% stepper %}
{% step %}
**進入自訂管道**

登入 FIRST LINE，從左側選單開啟「自訂管道」，進入管理列表。
{% endstep %}

{% step %}
**新增管道**

點選「新增」，在「一般」分頁填寫名稱，可依需求補充描述並選擇所屬管道分類。名稱為必填欄位。

建議使用容易辨識的名稱，例如「會員中心聊天服務」或「行動 App 客服」。
{% endstep %}

{% step %}
**儲存並保管 API 憑證**

點選「儲存」建立帳號。系統會產生 API Client ID、Client Secret 與 Webhook Secret，並在一次性視窗中顯示。

請立即複製並安全保存這些憑證，因為密鑰視窗關閉後，便無法再次讀取原本的明文密鑰。
{% endstep %}

{% step %}
**設定接待者**

建立完成後，回到「一般」分頁設定由誰接待客戶。可依實際需求選擇 **AI 代理**或**交談腳本**，並完成必要的設定。

若選擇 Fancy AI 代理，客戶訊息將依該代理的指示及路由邏輯處理；若選擇交談腳本，則按腳本設定執行。
{% endstep %}

{% step %}
**設定 Webhook（選用）**

在「Webhook」分頁填入企業用來接收事件的 HTTPS 網址，並選擇要訂閱的事件，再儲存設定。

如果暫時不使用 Webhook，也可由企業後端透過事件查詢 API 取得對話進度。
{% endstep %}

{% step %}
**啟用並測試**

確認接待者、API 憑證、訊息接收及事件處理程式均已完成後，啟用管道，並以測試訊息確認完整收發流程。
{% endstep %}
{% endstepper %}

***

## 管道設定說明

### 一般

| 設定     | 說明                         |
| ------ | -------------------------- |
| 啟用     | 決定此管道是否可供外部系統使用。新建管道預設不啟用。 |
| 名稱     | 用來辨識此管道的名稱，為必填項目。          |
| 描述     | 記錄使用目的或所連接的系統。             |
| 所屬管道分類 | 依企業管理需求歸類。                 |
| 接待者    | 帳號建立後可設定 AI 代理或交談腳本。       |

### API 憑證

API 憑證用於讓企業後端安全地存取 FIRST LINE 的 Headless Conversation API。

| 憑證             | 用途                            |
| -------------- | ----------------------------- |
| Client ID      | 辨識此 API 管道的應用程式。              |
| Client Secret  | 搭配 Client ID 取得 API 存取權杖。     |
| Webhook Secret | 驗證 FIRST LINE 發出的 Webhook 通知。 |

{% hint style="warning" %}
**Client Secret 與 Webhook Secret 只在首次建立或重新產生時顯示一次。** 請保存於企業後端的密鑰管理系統，不應放在前端 JavaScript、手機 App 安裝檔或公開的程式碼儲存庫中。
{% endhint %}

如果密鑰遺失，可在「API 憑證」分頁使用「重新產生」。請注意：

* 重新產生 API 憑證後，舊的 Client 與已核發的存取權杖會失效，企業後端必須改用新憑證。
* 重新產生 Webhook Secret 後，舊密鑰會立即失效。接收端必須同步更新驗證設定，否則可能無法通過簽章驗證。

### Webhook

Webhook 讓 FIRST LINE 在對話出現新訊息、完成一輪處理或改變狀態時，主動通知企業後端。

**Webhook 網址必須使用 HTTPS，且須能解析至公開可連線的 IP 位址。** 本機位址及私有網路位址不能當作正式接收端點。

Webhook 可依需求選擇訂閱新訊息、回合完成、轉交真人、對話結束及 AI 工具執行等事件。未勾選的事件不會推送；詳細事件名稱與資料格式請參考 [Headless Conversation API](/developer/api/jin-jie/headless-conversation-api.md)。

{% hint style="info" %}
`turn.completed` 代表目前這一輪已完成，不等於整段對話已結束。當 AI 尚在處理訊息時，系統可能先接收請求，再於稍後提供回覆事件。
{% endhint %}

***

## 給開發人員的串接文件

如需將網站或 App 接上 FIRST LINE，請交由企業的開發人員參考 [Headless Conversation API](/developer/api/jin-jie/headless-conversation-api.md)。技術文件提供身分驗證、訊息傳送、接收回覆、Webhook 驗簽與錯誤處理範例。

***

## 常見問題

### 自訂管道會自動產生聊天視窗嗎？

不會。企業需要自行開發聊天介面及與 FIRST LINE 溝通的後端服務。若希望直接使用現成的網站聊天介面，可考慮「即時聊天」。

### 可以使用 Fancy AI 代理嗎？

可以。建立管道後，在接待者設定中選擇適合的 AI 代理，便能讓外部送入的客戶訊息交由該代理處理。實際回覆仍依代理指示、可用知識與路由設定運作。

### 傳送訊息成功，為什麼沒有立即得到 AI 答案？

訊息傳送 API 的回覆是接收確認，AI 代理可能由背景工作執行。請透過 `message.created`、`turn.completed` 等事件取得後續結果。

### Webhook 沒有收到訊息怎麼辦？

請檢查管道是否已啟用、Webhook URL 是否為可公開連線的 HTTPS 網址、相關事件是否勾選，以及接收端是否正確驗證密鑰。必要時可透過事件查詢 API 檢查是否已有事件產生。

### 訊息和事件能保留多久？

事件查詢提供一定期限內的資料。企業如有長期保存或稽核需求，請依自身資料管理政策保存必要的事件與對話紀錄；詳細的串接及重送原則可參考開發文件。

***

## 正式啟用前的檢查

* 自訂管道已建立，且設定了正確的接待者。
* Client ID、Client Secret 與 Webhook Secret 已保存於安全的後端環境。
* 已確認 Access Token 可以正常使用，且沒有將密鑰暴露在客戶端。
* 傳送測試訊息後，可以透過 Webhook 或 Polling 接收到 `message.created`。
* 若使用 AI 代理，已測試多輪對話、轉交真人與交談腳本路由。
* 已設計網路逾時、重送、憑證換發及事件保存的處理方式。