跳至主要内容

向 Voxsig 發送資訊

關於聯絡人的額外資訊總是很有用的。Voxsig 網站的 SDK 確保您可以發送有關用戶的額外資訊。

如果您已在您的網站上安裝了我們的程式碼，SDK 會暴露 window.$chatwoot 物件。

為了確保 SDK 完全載入，請確保您按照以下方式監聽 chatwoot:ready 事件：

window.addEventListener("chatwoot:ready", function () {
  // 在此使用 window.$chatwoot
  // ...
});

如果您想在 Widget 中監聽消息，可以使用以下事件。

window.addEventListener("chatwoot:on-message", function (e) {
  console.log("chatwoot:on-message", e.detail);
});

SDK 設定​

要隱藏氣泡，您可以使用以下提到的設定。

注意：如果您使用這個，那麼您也必須觸發 Widget。

window.chatwootSettings = {
  hideMessageBubble: false,
  position: "left", // 這可以是 left 或 right
  locale: "en", // 設定語言
  useBrowserLanguage: true, // 從使用者的瀏覽器設定 Widget 語言
  baseDomain: '.mydomain.com',
  type: "standard", // [standard, expanded_bubble]
  darkMode: "auto", // [light, auto]
  autoStartConversation: true, // 用戶進入 Widget 後，會自動跳過 Widget 歡迎頁，直接進入對話
};

在子域名間保留聊天會話 baseDomain 配置​

baseDomain 配置在子域名之間保留用戶聊天會話，確保用戶在瀏覽您的域名頁面時有無縫的聊天體驗。

設定​

將 baseDomain 配置添加到 window.chatwootSettings

window.chatwootSettings = {
  //其他設定
  baseDomain: ".yourdomain.com",
};

將 yourdomain.com 替換為您的域名，保留前面的點。

備註

  • 確保所有子域名都設置了 SSL。
  • 配置適用於子域名，而不是不同的域名。

範例：

baseDomain: '.voxsig.com'

自動在您的即時聊天 Widget 中使用瀏覽器語言​

要在用戶的瀏覽器語言環境中顯示即時聊天 Widget，請在上面提到的 window.chatwootSettings 中將 useBrowserLanguage 設置為 true。

注意：如果 useBrowserLanguage 設置為 true，則將忽略提到的 locale。如果瀏覽器語言不受 Voxsig 支持，則將使用在 locale 下提到的語言環境。如果那也缺失，widget 會回退到客服儀表板的 locale。

暗黑模式​

Voxsig 的即時聊天 Widget 從 v2.4.0 開始支持暗黑模式。要啟用暗黑模式，請按照此處所述的步驟操作。

Widget 設計​

Voxsig 支持 Widget 的兩種設計。

  1. 標準 (預設)

標準氣泡

  1. 展開的氣泡

展開的氣泡

如果您使用展開的氣泡，您可以通過在 chatwootSettings 上設定 launcherTitle 參數來自訂氣泡中使用的文字，如下所述。

window.chatwootSettings = {
  type: "expanded_bubble",
  launcherTitle: "與我們聊天",
};

啟用彈出視窗​

要啟用彈出視窗，請將以下配置添加到 chatwootSettings。此選項預設是禁用的。

window.chatwootSettings = {
  // ...其他配置
  showPopoutButton: true,
}

您也可以使用 popoutChatWindow() 方法程式化地彈出聊天視窗。

程式化地打開彈出視窗​

您可以使用 popoutChatWindow() 方法程式化地打開彈出視窗。

要啟動此功能，請按以下方式呼叫該方法。

window.$chatwoot.popoutChatWindow();

切換 Widget 氣泡的可見性​

如果您想隱藏/顯示 Voxsig widget 氣泡，可以使用 toggleBubbleVisibility('show/hide') 進行。

範例

window.$chatwoot.toggleBubbleVisibility("show"); // 顯示氣泡
window.$chatwoot.toggleBubbleVisibility("hide"); // 隱藏氣泡

觸發 widget 而不顯示氣泡​

window.$chatwoot.toggle();

// 通過傳遞狀態來切換 widget
window.$chatwoot.toggle("open"); // 打開 widget
window.$chatwoot.toggle("close"); // 關閉 widget

在 widget 中設置用戶​

window.$chatwoot.setUser("<用戶的唯一標識符鍵>", {
  email: "<用戶的電子郵件地址@your-domain.com>",
  name: "<用戶的名稱>",
  avatar_url: "<用戶的頭像URL>",
  phone_number: "<用戶的電話號碼>",
});

setUser 接受一個標識符，可以是您數據庫中的 user_id 或代表用戶的任何唯一參數。您可以傳遞 email、name、avatar_url、phone_number 作為參數。支持其他參數正在進行中。

確保在用戶從您的應用程序登出時重置會話。

使用 HMAC 進行身份驗證​

為了防止冒充並保持與您的客戶的私密對話，我們建議在 Voxsig 中設置身份驗證。通過使用 SHA256 根據 identifier 屬性生成 HMAC（基於哈希的消息驗證代碼）來啟用身份驗證。除 identifier 外，您還可以傳遞 identifier_hash，如下所示，以確保用戶是正確的。

window.$chatwoot.setUser(`<用戶的唯一標識符鍵>`, {
  name: "", // 用戶的名稱
  avatar_url: "", // 頭像URL
  email: "", // 用戶的電子郵件
  identifier_hash: "", // 根據 webwidget hmac_token 生成的標識符哈希
  phone_number: "", // 用戶的電話號碼
  description: "", // 關於用戶的描述
  country_code: "", // 兩個字母的國家代碼
  city: "", // 用戶的城市
  company_name: "", // 公司名稱
  social_profiles: {
    twitter: "", // Twitter 用戶名
    linkedin: "", // LinkedIn 用戶名
    facebook: "", // Facebook 用戶名
    github: "", // Github 用戶名
  },
});

要生成 HMAC，請閱讀 身份驗證。

請注意，實施 HMAC 身份驗證將允許聊天歷史保持在多個會話中。

設定自定義屬性​

對於一個聯絡人​

為了設定關於客戶的額外資訊，您可以使用客戶自定義屬性欄位。詳細了解自定義屬性在此。

要設定自定義屬性，呼叫 setCustomAttributes 如下：

window.$chatwoot.setCustomAttributes({
  accountId: 1,
  pricingPlan: "paid",

  // 這裡的鍵已在自定義屬性中定義
  // 值應該基於類型 (目前支持 Number, Date, String 和 Number)
});

您可以在對話的側邊面板中查看這些資訊。

要刪除自定義屬性，使用 deleteCustomAttribute 如下：

window.$chatwoot.deleteCustomAttribute("attribute-key");

對於一次對話​

您也可以從 SDK 為活動中的對話設置自定義屬性。要設置自定義屬性，請如下呼叫 setConversationCustomAttributes。

window.$chatwoot.setConversationCustomAttributes({
  productName: "iPhone",
  productCategory: "Smartphone",
});

您可以在對話的側邊面板中查看這些資訊。

要刪除自定義屬性，使用 deleteConversationCustomAttribute 如下。

window.$chatwoot.deleteConversationCustomAttribute("productName");

手動設定語言​

window.$chatwoot.setLocale("en");

要手動設定語言，使用 setLocale 函數。

在對話上設定標籤​

請注意，如果用戶尚未開始對話，對話上將設定標籤。在那種情況下，以下項目將不會產生任何效果：

window.$chatwoot.setLabel("support-ticket");

window.$chatwoot.removeLabel("support-ticket");

刷新會話（在您從應用程序中登出用戶時使用這個）​

window.$chatwoot.reset();

Widget 錯誤​

為了查看 widget 中的任何錯誤，請確保您按照以下方式監聽 chatwoot:event 事件：

window.addEventListener("chatwoot:error", function () {
  // ...
});

注意：此功能在 v2.3.0 或更高版本中可用。