ServiceChat API 文件

整合方式

網站 Widget

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

Bot API

商戶後端可建立聊天室、寫入訊息與讀取訊息。

社群通路

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

網站 Widget

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

<script src="https://your-service-chat-domain/widget/servicechat-widget.js"
        data-tenant-key="YOUR_WIDGET_PUBLIC_KEY"
        data-customer-name="Guest"
        data-inbox-category-code="sales"
        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 可把新聊天室放入指定收件匣分類；分類不需預先建立，聊天室建立後分類固定。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 Key 只能放在 server 端，不應放在瀏覽器前端。

X-ServiceChat-ApiKey: sc_live_xxx

建立或取得聊天室

POST /api/service-chat/customer/room
Content-Type: application/json
X-ServiceChat-ApiKey: sc_live_xxx

{
  "customerAccount": "user-10001",
  "customerDisplayName": "Customer 10001",
  "customerLanguage": "zh-TW",
  "inboxCategoryCode": "sales"
}

代表客戶送出文字訊息

POST /api/service-chat/customer/messages/text
Content-Type: application/json
X-ServiceChat-ApiKey: sc_live_xxx

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

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

讀取聊天室訊息

GET /api/service-chat/customer/messages?page=1
X-ServiceChat-ApiKey: sc_live_xxx

媒體上傳

官方 Widget 會自動處理分段上傳與續傳。自建整合可使用 upload session 流程：初始化、上傳 chunk、完成上傳。

POST /api/service-chat/customer/media 建立上傳工作。
PUT /api/service-chat/customer/media/{id}/chunks/{index} 上傳分段。
POST /api/service-chat/customer/media/{id}/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 測試工具。

前往後台