ServiceChat API 文件

整合方式

網站 Widget

貼上一段 script，在網站啟用客服聊天視窗。

Bot API

商戶後端可建立聊天室、寫入訊息與讀取訊息，Pro 方案另有工單 API。

社群通路

Telegram、LINE、WhatsApp、Messenger 等通路由後台設定；查看申請教學。

網站 Widget

公開範例使用 YOUR_WIDGET_PUBLIC_KEY 佔位。登入後台後，請到 API 專區複製包含實際前端整合 Key 的版本。

<script src="https://your-service-chat-domain/widget/servicechat-widget-loader.js"
        data-tenant-key="YOUR_WIDGET_PUBLIC_KEY"
        data-customer-name="Guest"
        data-inbox-category-code="sales"
        data-primary-color="#0f766e"
        data-theme="soft"
        data-launcher-label="Service"
        data-launcher-icon="https://example.com/chat-icon.svg"
        data-launcher-position="left-bottom"
        async></script>

前端整合 Key 是公開識別碼，不是 Bot API Key。租戶管理員可在後台 API 專區重建，重建後舊 key 會立即失效，網站上的嵌入碼也要同步更新。data-inbox-category-code 可把新聊天室放入指定收件匣分類，也會套用後台「自助選單」中該收件匣指定的 Widget 選單組；分類不需預先建立，聊天室建立後分類固定。data-primary-color（也可用 data-accent-color 或 data-color）可針對單一網站覆蓋主色，data-theme（也可用 data-widget-theme）可覆蓋 widget theme；未設定時使用後台預設配色。data-launcher-label 可調整按鈕文字；data-launcher-icon 可填圖片 URL，或填 none 隱藏 icon；data-launcher-position 可用 right-bottom、left-top、right-top、left-bottom，也可填座標，例如 100,100 從左上計算，100,-100 表示左 100、下 100。

前端控制 API

window.ServiceChatWidget.open();
window.ServiceChatWidget.close();
window.ServiceChatWidget.toggle();
window.ServiceChatWidget.getUnreadCount();
window.ServiceChatWidget.markRead();

Bot API 認證

Bot API 使用商戶後台建立的 API Key，路徑前綴為 /api/public/v1。API Key 只能放在 server 端，不應放在瀏覽器前端。

X-ServiceChat-ApiKey: sc_live_xxx

建立或取得聊天室

POST /api/public/v1/rooms
Content-Type: application/json
X-ServiceChat-ApiKey: sc_live_xxx

{
  "customerAccount": "user-10001",
  "customerDisplayName": "Customer 10001",
  "channel": "bot",
  "customerLanguage": "zh-TW",
  "inboxCategoryCode": "sales",
  "initialMessage": "我想了解方案內容"
}

customerAccount 相同時會回到同一個房間，回應中的 roomId 是後續呼叫要帶的房間識別碼。initialMessage 為選填，填入後會直接寫成客戶的第一則訊息。

代表客戶送出文字訊息

POST /api/public/v1/rooms/{roomId}/messages/customer-text
Content-Type: application/json
X-ServiceChat-ApiKey: sc_live_xxx

{
  "text": "我想了解方案內容",
  "clientMessageId": "browser-generated-guid"
}

clientMessageId 為選填，建議由前端在送出前產生 GUID。系統回送訊息時會帶回同一個值，方便自建前端先顯示本機訊息，再用正式訊息替換，避免 HTTP 回應與即時推送先後抵達造成重複顯示。

讀取聊天室訊息

GET /api/public/v1/rooms/{roomId}/messages?page=1
X-ServiceChat-ApiKey: sc_live_xxx

依建立時間由舊到新排序，每頁 100 筆。

工單 API

工單 API 與 Bot API 使用同一組 API Key，需要 Pro 以上方案；方案不符會回 403。

查詢工單列表

GET /api/public/v1/tickets?page=1&pageSize=20&status=open&keyword=&formCode=&customerAccount=
X-ServiceChat-ApiKey: sc_live_xxx

讀取單一工單

GET /api/public/v1/tickets/{ticketId}
X-ServiceChat-ApiKey: sc_live_xxx

建立工單

POST /api/public/v1/tickets
Content-Type: application/json
X-ServiceChat-ApiKey: sc_live_xxx

{
  "formCode": "support",
  "title": "無法登入",
  "description": "客戶回報登入後白畫面",
  "customerAccount": "customer@example.com",
  "customerDisplayName": "Customer 10001",
  "customerLanguage": "zh-TW",
  "priority": 2,
  "fieldValues": []
}

新增回覆

POST /api/public/v1/tickets/{ticketId}/comments
Content-Type: application/json
X-ServiceChat-ApiKey: sc_live_xxx

{
  "content": "已排入處理",
  "visibility": "internal",
  "authorDisplayName": "CRM"
}

visibility 未填時視為 internal；填 public 才會通知客戶。

變更工單狀態

POST /api/public/v1/tickets/{ticketId}/status
Content-Type: application/json
X-ServiceChat-ApiKey: sc_live_xxx

{
  "status": "resolved",
  "actorDisplayName": "CRM"
}

status 必須是該表單工作流程既有的狀態代碼；不認得的代碼會回 400，並在訊息中列出可用代碼。

媒體上傳

媒體上傳屬於 Widget 房間流程，不是 Bot API：它認的是建立房間時取得的房間權杖 X-ServiceChat-Room-Token，帶 API Key 沒有作用。官方 Widget 會自動處理分段上傳與續傳，自建整合需依序呼叫初始化、上傳 chunk、完成上傳，每次都要帶房間權杖與 tenantKey。

POST /api/service-chat/customer/rooms 建立房間，回應中的 accessToken 即房間權杖。
POST /api/service-chat/customer/rooms/{roomId}/media-uploads 建立上傳工作。
POST /api/service-chat/customer/rooms/{roomId}/media-uploads/{uploadId}/chunks/{index} 上傳分段。
POST /api/service-chat/customer/rooms/{roomId}/media-uploads/{uploadId}/complete 完成並建立聊天室訊息。

方案限制

Free 方案沒有 Bot API Key 配額；即使降級前曾建立 key，公開 Bot API 也會拒絕使用。
Starter 以上可使用 Bot API；可建立的 API Key 數量依目前方案配額為準。
Widget 媒體依方案啟用：Free 可使用圖片，Starter 可使用圖片與語音，Pro 以上可使用圖片、語音、影片與一般檔案/大型分段上傳。
社群通路整合、AI 翻譯、AI 客服、AI 知識庫、AI 外部工具、AI 記憶維護與聊天室記事/重要檔案標記需要 Pro 以上方案。
帳號席次依目前方案檢查啟用中的客服數；停用帳號不佔席次，重新啟用時仍會重新檢查方案上限。

後台 API 專區

登入後台後可管理 Bot API Key、複製帶有前端整合 Key 的 Widget 範例、使用 API 測試工具。

前往後台