跳到主要内容

向 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 或更高版本中可用。