串接對話平台：LINE WORKS

LINE WORKS 是 LINE 的企業版通訊工具。串接後，員工可以直接在原本的 LINE WORKS 中與 AI 助理對話，不需要另外開啟其他系統。支援一對一私訊與群組對話。

LINE WORKS 與 LINE 是兩個不同的平台，憑證與設定方式完全不同。若您要串接的是消費者端的 LINE 官方帳號，請參考串接對話平台：LINE。

串接前確認

• 已在 MaiAgent 平台上建立好一個「AI 助理」

• 已擁有 LINE WORKS 的管理員權限（可登入 Admin 後台）

• 可存取 LINE WORKS Developer Console

本串接需要 6 組憑證，且憑證在建立通道後無法修改。請先完成步驟一與步驟二、把 6 組憑證都準備齊全，再進行步驟三。

---

步驟一：建立 Client App 並取得 Service Account

1. 進入 Developer Console 的 ClientApp 頁面

登入 LINE WORKS Developer Console，在左側選單點選 API → ClientApp，再點擊 Add client app 建立一個 App。

Developer Console → API → ClientApp

2. 取得四組憑證

進入該 App 的詳細頁面，取得以下四項：

憑證	在 Console 的位置
Client ID	Client ID 欄位
Client Secret	Client Secret 欄位
Service Account	Service Account 欄位，格式為 xxxxx.serviceaccount@您的網域
Private Key	Private Key 區塊，建立時可下載 .key 檔案

Client App 詳細頁面 — 四組憑證與 OAuth Scopes 都在這一頁

3. 設定 OAuth Scopes

在同一頁的 OAuth Scopes 區塊，需授予以下權限，否則 AI 助理無法收發訊息或查詢成員姓名：

Scope	說明
bot	管理 Bot
bot.message	發送訊息
bot.read	讀取 Bot 設定
user.read	讀取成員資訊（用於在對話中顯示發話者姓名）

同一頁的 Token設定 可調整 Access Token 的有效期限。MaiAgent 會自動管理權杖的簽發與續期，此處維持預設值即可。

Private Key 只能下載一次。 建立 Service Account 時會提供一個 .key 檔案下載，離開頁面後就無法再取得。請先妥善保存，遺失只能重新產生一組——而重新產生會讓現有串接立即失效。

私鑰必須是未加密的 PEM 格式：第一行是 BEGIN PRIVATE KEY 或 BEGIN RSA PRIVATE KEY 標記（該行前後各有五個連字號），最後一行是對應的 END 標記。若您的私鑰有密碼保護，MaiAgent 無法使用，請重新產生一組未加密的。

---

步驟二：建立 Bot 並取得 Bot ID 與 Bot Secret

在 Developer Console 左側選單點選 Bot，建立一個 Bot，取得：

憑證	在 Console 的位置
Bot ID	Bot ID 欄位
Bot Secret	Bot Secret 欄位，用於驗證 LINE WORKS 送來的訊息確實來自您的 Bot

Bot 詳細頁面 — Bot ID 與 Bot Secret 在這裡

需要群組對話時的必要設定

在 Bot 的 修改 頁面找到 Bot政策 → 加入聊天室，勾選 可邀請加入團隊/群組、1:N聊天室。

未勾選時 Bot 只能進行一對一私訊，無法被邀請進群組。

Bot 詳細頁面的 Bot政策 摘要文字，曾觀察到與修改表單中實際的勾選狀態不一致。若兩處說法不同，請以 修改 表單中的勾選狀態為準。

Bot 名稱也在此頁設定。這個名稱會是使用者在群組中 @ 提及 Bot 時要輸入的名稱，請取一個好輸入的名稱。

Callback URL 這一步先跳過。它需要 MaiAgent 產生的 Webhook URL，我們會在步驟四回來填。

---

步驟三：在 MaiAgent 建立 LINE WORKS 對話平台

1. 進入串接對話平台

在 MaiAgent 左側選單點選 對話平台，點擊右上角 串接對話平台，選擇 LINE WORKS。

在平台清單中選擇 LINE WORKS

2. 填寫基本設定

欄位	說明
名稱	為此串接取一個名稱（必填）。這只是 MaiAgent 這側的標籤，與 LINE WORKS 中顯示的 Bot 名稱無關。
AI 助理	選擇要綁定的 AI 助理
Bot ID	步驟二取得（必填）
Bot Secret	步驟二取得（必填）
Client ID	步驟一取得（必填）
Client Secret	步驟一取得（必填）
Service Account	步驟一取得（必填）
Private Key	貼上步驟一下載的 .key 檔案完整內容，包含開頭與結尾的標記行（必填）

表單分為上下兩段。上半段是名稱、AI 助理，以及步驟二取得的 Bot ID 與 Bot Secret：

建立表單上半段 — 名稱、AI 助理、Bot ID、Bot Secret（圖中為範例值）

往下捲動是步驟一取得的 Client App 三項憑證與私鑰：

建立表單下半段 — Client ID、Client Secret、Service Account、Private Key（圖中為範例值）

Bot Secret 與 Client Secret 輸入後會以圓點遮蔽，可點欄位右側的眼睛圖示確認內容。Private Key 請直接貼上 .key 檔案的完整內容，換行會原樣保留。

3. 聊天室設定

設定	說明
群組中需 @Bot 才回覆	開啟後，Bot 在群組對話中只有被 @ 提及時才回覆。建議在群組使用時開啟，否則群組中的每一則訊息都會觸發 AI 助理回覆。
啟用重置命令	開啟後可自訂關鍵字，使用者輸入該關鍵字即可清空對話記憶、重新開始。

「群組中需 @Bot 才回覆」比對的是 Developer Console 設定的 Bot 名稱，不是上方「名稱」欄位填的 Inbox 名稱。若在 Developer Console 改了 Bot 名稱，群組中要 @ 的名稱也會跟著改變。

4. 串接測試

點擊 串接測試，MaiAgent 會實際向 LINE WORKS 取得一次存取權杖，確認憑證組合正確。

失敗時畫面會顯示具體原因。常見的兩種：

• 憑證驗證失敗 — 依序檢查 Private Key 是否完整貼上（包含開頭與結尾標記行，中間換行不可遺漏）、是否為未加密格式、Service Account 是否完整（含 .serviceaccount@網域 後半段）、Client ID 與 Client Secret 是否來自同一個 App、App 是否已授予步驟一列出的四個 Scope

• 此 Bot ID 已綁定於其他收件匣 — 同一個 Bot 不能同時掛在兩個對話平台上。請改用另一個 Bot，或先刪除既有的那個對話平台

失敗訊息會顯示在按鈕左側：

串接測試失敗的訊息位置（此例為 Bot ID 重複綁定）

5. 建立並複製 Webhook URL

點擊 串接對話平台 完成建立。系統會產生一組 Webhook URL，請複製備用——下一步要填回 Developer Console。

您也可以隨時回到該通道的設定頁面，在 API 串接 欄位複製這組 URL。

建立後的設定頁面 — 憑證不再顯示，Webhook URL 可隨時複製

---

步驟四：回到 Developer Console 設定 Callback URL

回到步驟二建立的 Bot，進入 修改 頁面：

1. 將 Callback URL 設為 On，並填入 MaiAgent 產生的 Webhook URL

2. 在 Callback Event Settings 勾選要接收的事件。建議 Message Event 底下全部勾選，讓 AI 助理能處理各類訊息：

事件	對應的使用者行為
TEXT	傳送文字訊息
照片	傳送圖片
檔案	傳送檔案
音訊	傳送語音訊息
視訊	傳送影片
位置分享	分享位置
貼圖	傳送貼圖

1. 若會在群組使用，Join Event 與 Joined Event 也建議勾選

2. 儲存設定

Callback URL 設為 On 並填入 Webhook URL，下方勾選事件型別

未勾選的事件型別，LINE WORKS 不會送給 MaiAgent，該類訊息就會像沒發生過一樣——AI 助理不會回覆，對話中也不會留下記錄。

---

步驟五：在 Admin 後台啟用 Bot

登入 LINE WORKS Admin 後台，在左側 服務 → Bot 點擊右上角 新增Bot，把步驟二建立的 Bot 加進來。

加入後這一頁會列出該 Bot，並可在 使用權限 欄設定哪些成員看得到它（設為 全部 代表全體成員皆可使用）。

Admin 後台 → 服務 → Bot — 加入 Bot 並設定使用權限

這一步很容易漏。Bot 在 Developer Console 建立後還沒有出現在員工的 LINE WORKS 中，必須由租戶管理員在 Admin 後台加入，員工才搜尋得到。

---

開始使用

一對一私訊

在 LINE WORKS 中搜尋 Bot 名稱並開始對話，AI 助理會自動回覆。

在 LINE WORKS 聊天室直接與 AI 助理對話

LINE WORKS 聊天室只顯示純文字，不會渲染 Markdown。若 AI 助理輸出表格或 **粗體**、### 等語法，使用者看到的會是原始符號。建議在助理的角色指令中加一段排版規則，要求以編號與換行呈現清單、不要使用 Markdown 語法。

群組對話

將 Bot 邀請進群組。若已開啟「群組中需 @Bot 才回覆」，輸入 @Bot名稱 你的問題 才會觸發回覆。

在 MaiAgent 的所有對話中，同一個群組會呈現為一則對話，發話者姓名顯示在訊息上。不會因為群組裡有多個人發言而拆成多條平行對話。

支援的訊息型別

使用者傳送	AI 助理的處理方式
文字	直接回答
圖片	可辨識圖片內容
檔案（PDF、Excel、Word 等）	讀取內容後回答相關問題
語音訊息	轉為文字後處理
影片	存為附件，記錄在對話中
位置	顯示為「📍 已分享位置」
貼圖	顯示為「🏷 貼圖」

AI 助理回覆時支援文字與附件。單則文字訊息若超過 LINE WORKS 的 1,000 字上限，系統會自動分段送出，不會被截斷。

---

常見問題

AI 助理突然不回覆了

先到該通道的設定頁面查看是否顯示憑證已失效的警示。

憑證失效最常見的原因是在 Developer Console 重新產生了私鑰或 Service Account。舊憑證一旦被取代，MaiAgent 就無法再取得存取權杖。

由於憑證無法就地修改，請重新建立一個 LINE WORKS 通道並填入新憑證。

憑證失效唯一的外部症狀就是 AI 助理安靜下來——使用者不會收到任何錯誤訊息。若同事回報「機器人沒反應」，這裡是第一個該看的地方。

為什麼憑證不能修改？

憑證屬於敏感資料，MaiAgent 儲存後不會再回傳給前端，設定頁面也不接受修改，以避免憑證在傳輸與畫面上重複曝露。Bot ID、Client ID 與 Service Account 會以唯讀方式顯示，方便您核對目前接的是哪一支 Bot。

需要更換任何一項憑證時，請刪除此通道後重新建立。

群組中 @ 了 Bot 卻沒有反應

• 確認 @ 的名稱與 Developer Console 中的 Bot 名稱一致，而非 MaiAgent 的 Inbox 名稱

• 確認 Bot 修改頁面的 Bot政策 → 加入聊天室 已勾選可邀請加入團隊/群組、1:N聊天室

• 確認 Callback Event Settings 已勾選 TEXT

需要定期更新權杖嗎？

不需要。MaiAgent 使用 Service Account 方式認證，存取權杖由系統自動簽發與續期，不會因為時間經過而失效。只要 Developer Console 的憑證沒有被重新產生，串接就會持續有效。