在您的網站上嵌入小工具

您可以通過 <script> 標籤將產品放到自己的網站上。 有兩個小工具，您選擇哪一個取決於訪客是否應該進行對話或運行特定操作。

	Chat widget	Workflow widget
訪客獲得什麼	與助手的對話	一個工作流程，包括其輸入
互動表單	是	否 — 只顯示結果
腳本	chat-widget.js	workflow-widget.js

這兩個小工具都是自包含的：不需要在頁面上使用框架，不需要包含樣式表，也不需要構建。

添加聊天小工具

<script src="https://app.example.com/chat-widget.js"></script>
<script>
  sapajaChat('init', {
    templateId: 'your-template-id',
    token: 'your-embed-token',
  });
</script>

您將從擁有聊天模板的 workspace 獲得模板 ID 和其令牌。令牌是授權小工具的依據，並且與可以使用它的網站列表相關聯 — 從不在該列表中的域使用的令牌將被拒絕，因此複製的令牌在其他地方無法工作。

訪客看到什麼

回覆不是純文本。該小工具渲染與應用內聊天相同的豐富表面 — 卡片、表格、統計數據、徽章、圖表和圖像 — 所以結果以可讀的方式到達，而不是一團 JSON。

聊天小工具還渲染 真實表單。當助手需要詳細信息才能執行某操作時，訪客會看到標記的字段和提交按鈕，而不是被要求將值輸入到一句話中。一些值得了解的行為：

• 不完整的提交會以更正的表單返回，缺少的字段將被標記，而不是顯示錯誤。
• 如果提交無法到達我們，表單保持可編輯狀態並提供重試 — 它從不錯誤報告成功。
• 提交的表單保持可見但凍結，標記為已提交，以便訪客可以看到他們發送的內容。

工作流程小工具顯示結果但不包含表單；它提前收集所需的信息。

訪客的語言

該小工具使用訪客的語言，而不是您的。它按照以下順序確定使用哪種語言：您配置的語言、訪客的瀏覽器語言，然後是英語。

sapajaChat('init', { templateId: '…', token: '…', locale: 'fr' });

支持的語言有： en, fr, es, th, zh 和 zh-HK。普通的瀏覽器標籤也可以 — fr-CA 變為法語，zh-TW 變為繁體中文。任何未識別的語言將回退至英語，而不是失敗。

這涵蓋了小工具自己的控件 和 助手生成的所有內容：狀態行、完成消息、結果卡片標籤及其回覆。按消息適用，因此在對話過程中更改語言的訪客會從下條消息開始接收到新的語言。已發送的內容將不會重新翻譯 — 結果卡將保持在其構建的語言中。

如果一個對話啟動了一個長時間運行的任務，語言會隨之移動，所以即使是幾小時後收到的完成消息也會使用訪客當時使用的語言。

一個例外： 由創建工作流程的人編寫的文本 — 字段描述、澄清提示和自定義顯示 — 將以他們編寫的方式顯示。這是作者內容，而不是產品副本，因此不進行翻譯。

替代構建自己的客戶端

您不必使用小工具。嵌入端點已在 REST API reference 中記錄，並且在每次呼叫時都接受相同的 locale 值 — 發送它，您會獲得相同的行為，省略它則得到英語。

如果某些內容不顯示

• 沒有麥克風按鈕。 語音需要安全的連接。在通過普通 HTTP 提供的頁面上，瀏覽器根本不會授予麥克風訪問權限，因此未顯示該控件。請通過 HTTPS 提供您的頁面。
• 某個組件未渲染。 小工具僅渲染已知的組件類型，並靜默地丟棄任何其他內容，因此無法理解的顯示會被跳過，而不是顯示為破損。
• 小工具停止工作。 如果擁有嵌入的 workspace 不再擁有有效的訂閱，小工具會禮貌地拒絕，而不是向您的訪客顯示計費消息。