菜单

SaleSmartly聊天插件JSSDK开发者文档

一、简介

当您在网站项目中插入 JavaScript 代码后，可以通过以下方法对 ssq(ssq 为全局变量)进行信息修改和聊天窗口调用

Demo示例

二、API

您可以通过将用户信息传递给 SDK，使聊天插件为每个用户创建一个包含这些信息的用户档案，这样可以在 SaleSmartly 系统客户资料的对应处看到这些信息；同时，如果用户更换设备时，也可以通过该方法，同步信息到新设备上

命令状态回调说明

以下 8 个公开 API 支持可选的业务状态回调：setLoginInfo、clearUser、chatOpen、chatClose、sendTextMessage、setInputText、hideUpload、hideCloseIcon。

有业务参数的命令使用 ssq.push(command, payload, callback)。
无业务参数的命令使用 ssq.push(command, callback)。
callback 为可选参数，不影响不传 callback 的原有调用方式。
首版 callback 参数仅包含 { status }，每次命令最多回调一次。

status	说明
`success`	命令执行成功。
`failed`	命令执行失败。
`ignored`	命令已被忽略。

2.1 设置登录信息

js 复制代码

ssq.push('setLoginInfo', {
  user_id: 'b58e64cfxs2ym', // 加密后的用户id, 必填！最大长度300字符
  user_name: 'test_yy', // 对应用户名，可在客户资料查看, 必填
  language: 'ru-RU', // 对应用户语言，可在客户资料查看
  phone: '1592014xxxx', // 对应用户手机号，可在客户资料查看
  email: 'test@test', // 对应用户邮箱，可在客户资料查看
  description: '套餐B\n客户端\n收费客户', // 对应用户的描述信息，例如套餐信息，可在客户资料查看
  label_names: ['标签值1', '标签值2'], // 对应用户标签，仅支持传系统已创建的标签值，可在客户资料查看
  update_label_type: 'update', // 标签传递方式 append-追加标签 update-覆盖之前的标签
  custom_fields_ext: {"1210":"test11","more":["s1","s2"]}, // 自定义字段，到项目设置的自定义字段中找到id和对应值进行填入（选择类型以数组形式传入），可在客户资料查看
}, function(result) {
  console.log('setLoginInfo 状态：', result.status);
});

回调状态：

success：token 已取得并保存，用户 Store 已完成应用；不等待实时连接或入房。
failed：token 请求失败或未返回有效 token。
ignored：待处理期间被新的身份请求替代。
相同身份的并发调用共享登录任务，但每次调用都会分别回调一次。

专属链接传参

专属链接支持将用户信息传给现有的 setLoginInfo，字段与上方示例一致。页面会在根 install.js 加载前，将用户信息加入 ssq 队列。

方式一：通过 URL 传递

适用于浏览器直接打开或复制专属链接的场景。setLoginInfo 的值必须是经过 URL 编码的 JSON 对象。

js 复制代码

const loginInfo = {
  user_id: 'b58e64cfxs2ym', // 加密后的用户id, 必填！最大长度300字符
  user_name: 'test_yy', // 对应用户名，可在客户资料查看, 必填
  language: 'ru-RU', // 对应用户语言，可在客户资料查看
  phone: '1592014xxxx', // 对应用户手机号，可在客户资料查看
  email: 'test@test', // 对应用户邮箱，可在客户资料查看
  description: '套餐B\n客户端\n收费客户', // 对应用户的描述信息，例如套餐信息，可在客户资料查看
  label_names: ['标签值1', '标签值2'], // 对应用户标签，仅支持传系统已创建的标签值，可在客户资料查看
  update_label_type: 'update', // 标签传递方式 append-追加标签 update-覆盖之前的标签
  custom_fields_ext: {"1210":"test11","more":["s1","s2"]}, // 自定义字段，到项目设置的自定义字段中找到id和对应值进行填入（选择类型以数组形式传入），可在客户资料查看
};

const serviceLink =
  'https://chat.example.com/service/example-id?setLoginInfo='
  + encodeURIComponent(JSON.stringify(loginInfo));

最终链接格式：

text 复制代码

https://chat.example.com/service/example-id?setLoginInfo=<URL 编码后的 JSON>

该方式会让姓名、手机号、邮箱等信息出现在 URL、浏览器历史或相关访问日志中，请根据实际隐私要求使用。

方式二：App WebView 通过 postMessage 传递

text 复制代码

https://chat.example.com/service/example-id?loginSource=postMessage

WebView 页面加载完成后，通过 WebView 的 JavaScript 执行能力在当前页面执行：

js 复制代码

window.postMessage(
  JSON.stringify({
    type: 'service-link-login',
    version: 1,
    payload: {
      user_id: 'b58e64cfxs2ym', // 加密后的用户id, 必填！最大长度300字符
      user_name: 'test_yy', // 对应用户名，可在客户资料查看, 必填
      language: 'ru-RU', // 对应用户语言，可在客户资料查看
      phone: '1592014xxxx', // 对应用户手机号，可在客户资料查看
      email: 'test@test', // 对应用户邮箱，可在客户资料查看
      description: '套餐B\n客户端\n收费客户', // 对应用户的描述信息，例如套餐信息，可在客户资料查看
      label_names: ['标签值1', '标签值2'], // 对应用户标签，仅支持传系统已创建的标签值，可在客户资料查看
      update_label_type: 'update', // 标签传递方式 append-追加标签 update-覆盖之前的标签
      custom_fields_ext: {"1210":"test11","more":["s1","s2"]}, // 自定义字段，到项目设置的自定义字段中找到id和对应值进行填入（选择类型以数组形式传入），可在客户资料查看
    },
  }),
  window.location.origin,
);

loginSource=postMessage 用于明确告诉页面：用户信息将由 App 随后发送。页面收到合法消息前不会加载 SDK，避免先创建匿名用户再切换为实名用户。

未传 setLoginInfo 和 loginSource=postMessage 时，保持原有行为，SDK 会立即加载并按匿名访客运行。
URL 中存在有效的 setLoginInfo 时，URL 用户信息优先，页面不会再等待 App 消息。
消息数据必须是 JSON 字符串，type 必须为 service-link-login，version 必须为 1，payload 必须是非数组对象。
页面只接收当前窗口、当前页面来源发送的消息，不支持传入其他 SDK 命令，也不支持运行中切换用户。
3 秒内未收到合法消息时，页面不会加载 SDK，并显示无效链接提示；刷新、返回重进或 WebView 重建后，App 需要重新发送。

2.1.1 插件语言

使用 ssq.push 方法设置用户的登录信息，并为聊天插件指定用户语言

js 复制代码

<script>
  ssq.push('setLoginInfo', {
    language: 'ru-RU',         // 插件语言，选填
  });

  // 语言选项（根据需要选择并设置）
  // 'en-US': 'English',       英语
  // 'zh-CN': '中文',          简体中文
  // 'zh-HK': '繁體中文',      繁体中文
  // 'ru-RU': 'русский',      俄语
  // 'th-TH': 'ภาษาไทย',     泰语
  // 'vi-VN': 'Tiếng Việt',   越南语
  // 'mn': 'Монгол',          蒙古语
  // 'ja-JP': 'やまと',        日语
  // 'fr': 'français',        法语
  // 'pt': 'português',       葡萄牙语
  // 'es': 'español',         西班牙语
  // 'ar': 'العربية',         阿拉伯语
  // 'de': 'Deutsch'           德语
  //  ro: 'română', // 罗马尼亚语
  //  pl: 'polski', // 波兰语
  //  id: 'Bahasa Indonesia', // 印度尼西亚语
  //  ko: '한국어', // 韩语
  //  nl: 'Nederlands', // 荷兰语
  //  da: 'Dansk', // 丹麦语
  //  it: 'Italiano', // 意大利语
  //  tr: 'Türkçe', // 土耳其语
  //  bn: 'বাংলা', // 孟加拉语
</script>

2.2 清理用户登录信息

在 PWA（渐进式 Web 应用）站点中，当用户退出登录后，尤其是在没有刷新页面的情况下，可用于手动清理用户的登录信息。通过调用 ssq.push('clearUser')，可以将用户信息清除，切换到访客模式；确保用户隐私和安全、以及提供无缝的用户体验

js 复制代码

ssq.push('clearUser', function(result) {
  console.log('clearUser 状态：', result.status);
});

回调状态：

success：本地用户、token 和身份状态已经清理；重复清理仍按成功处理。
合法调用下不会返回 failed，且结果不等待远端离房确认。

2.3 打开聊天窗口

在某些特殊场景下（如支付失败、账户、操作引导问题等），需要引导访客主动联系客服支持。您可以通过程序手动打开聊天窗口，确保用户能够快速获得帮助。

js 复制代码

ssq.push('chatOpen', function(result) {
  console.log('chatOpen 状态：', result.status);
});

回调状态：

success：打开流程和动画已经结束，窗口最终保持展开。
failed：打开窗口所需的 token 准备失败。
ignored：窗口已经展开、策略阻止打开、打开过程被关闭命令打断或身份发生变化。
同一时间发起的多个打开命令可以共享同一次打开流程，但每次调用都会分别回调一次。

2.4 关闭聊天窗口

可能需要手动关闭聊天窗口，例如在用户完成问题解决后，或在需要用户专注于当前任务时。通过调用 ssq.push('chatClose')，可以使用程序自动关闭聊天窗口

js 复制代码

ssq.push('chatClose', function(result) {
  console.log('chatClose 状态：', result.status);
});

回调状态：

success：关闭延迟和动画已经结束，窗口最终保持关闭。
ignored：窗口已经关闭或关闭过程被打开命令打断。
合法调用下不会返回 failed。

2.5 监听未读信息

监听未读消息，用于自定义消息通知。

js 复制代码

ssq.push('onUnRead', function(obj) {
    console.log(obj.num); // 未读数量
    console.log(obj.list); // 未读内容
});

2.6 隐藏图标

用户可以在插件初始化时设置隐藏图标，同时可以使用自定义图标按钮打开聊天窗，结合“监听未读信息”和“打开聊天窗口”的方式

js 复制代码

  //引入SalesSmartly 聊天插件的JavaScript 外部脚本 换成自己的，【确保聊天插件处于打开状态！】
  <script src="https://assets.salesmartly.com/js/project_23232_xxxxx_xxxxxxxxxx.js"></script>

  <script>
   // 隐藏图标（注: 代码放在引入聊天插件js之后执行）
   window.__ssc.setting = { hideIcon: true }; //true为隐藏，false为不隐藏

	// 自定义按钮事件
    function openChat() {
        // 打开聊天窗
        ssq.push('chatOpen');
    }
 </script>

2.7 监听发送消息

监听访客发送消息，访客发送消息可进行数据统计或者上报，可用于广告效果统计或归因。

js 复制代码

ssq.push('onSendMessage', function(obj) {
   // 在这里执行任何需要的上报或行为
});

2.8 监听接收消息

监听访客接收信息的事件，并在信息接收到时执行特定的操作（例如，接收到的对象 obj）。这是广告效果统计或归因分析的常见用法，通常用于记录访客在特定条件下的行为或反应。ssq.push('onReceiveMessage', function(obj) {...}) 的实现方式通常依赖于具体的第三方统计或广告平台。

js 复制代码

ssq.push('onReceiveMessage', function(obj) {
    console.log(obj);
});

2.9 监听窗口打开

监听聊天窗口的打开事件，并在窗口打开时进行数据统计或上报，常用于广告效果统计或归因分析

js 复制代码

ssq.push('onOpenChat', function() {
    // 在这里执行数据上报或其他操作
    // 例如，可以发送事件到分析平台，记录用户打开聊天窗口的行为
});

2.10 监听窗口关闭

用于监听聊天窗口的关闭事件，并在窗口关闭时进行数据上报或执行其他操作，以便进行分析或其他处理。通过监听聊天窗口的关闭事件，您可以分析用户的行为模式，例如用户在聊天窗口中停留的时间、关闭窗口的频率等，从而为你的营销策略或用户体验优化提供数据支持

js 复制代码

ssq.push('onCloseChat', function() {
    // 在这里执行你需要的操作，比如数据上报
});

2.11 监听打开信息收集

监听打开信息收集（聊前调查和离线留资），可在回调中进行数据上报

js 复制代码

ssq.push('onOpenCollection', (obj) => {
  // obj.type = 'offline' 离线留资
  // obj.type = 'survey' 聊前留资
});

2.12 监听完成信息收集

监听完成信息收集（聊前调查和离线留资），可以上报数据进行分析。如果想要知道是否有用户完成了信息收集可以在 onCollectionInfo 的回调里面去进行处理，回调数据需自行处理，salesmartly 后台是没有的

js 复制代码

ssq.push('onCollectionInfo', (obj) => {
  //obj包含了用户在信息收集过程中提供的数据
});

2.13 监听图标点击事件

通过监听不同的插件图标点击事件来执行相应的操作。这种做法可以帮助你追踪用户的交互行为，了解他们对哪些沟通工具更感兴趣，并基于此优化你的应用或服务

js 复制代码

// 监听点击Line图标
ssq.push('onOpenLine', (obj) => {
  // 在这里执行点击Line图标后的操作
  console.log('Line icon clicked', obj);
});

// 监听点击Messenger图标
ssq.push('onOpenMessenger', (obj) => {
  // 在这里执行点击Messenger图标后的操作
  console.log('Messenger icon clicked', obj);
});

// 监听点击Email图标
ssq.push('onOpenEmail', (obj) => {
  // 在这里执行点击Email图标后的操作
  console.log('Email icon clicked', obj);
});

// 监听点击Telegram图标
ssq.push('onOpenTelegram', (obj) => {
  // 在这里执行点击Telegram图标后的操作
  console.log('Telegram icon clicked', obj);
});

// 监听点击Whatsapp图标
ssq.push('onOpenWhatsapp', (obj) => {
  // 在这里执行点击Whatsapp图标后的操作
  console.log('Whatsapp icon clicked', obj);
});

// 监听点击微信图标
ssq.push('onOpenWeixin', (obj) => {
  // 在这里执行点击微信图标后的操作
  console.log('Weixin icon clicked', obj);
});

// 监听点击VKontakte图标
ssq.push('onOpenVKontakte', (obj) => {
  // 在这里执行点击VKontakte图标后的操作
  console.log('VKontakte icon clicked', obj);
});

// 监听点击TikTok图标
ssq.push('onOpenTikTok', (obj) => {
  // 在这里执行点击TikTok图标后的操作
  console.log('TikTok icon clicked', obj);
});

// 监听点击自定义图标
ssq.push('onOpenCustom', (obj) => {
  // 在这里执行点击自定义图标后的操作
  console.log('custom icon clicked', obj);
  // obj = {
  //     id, // custom_1、custom_2、custom_3
  //     content,
  // }
});

// 监听点击Zalo图标
ssq.push('onOpenZalo', (obj) => {
  // 在这里执行点击Zalo图标后的操作
  console.log('Zalo icon clicked', obj);
});

// 监听点击LineApp图标
ssq.push('onOpenLineApp', (obj) => {
  // 在这里执行点击LineApp图标后的操作
  console.log('LineApp icon clicked', obj);
});

2.14 监听插件资源加载完成

监听插件内部资源加载完成并在资源加载完成后执行特定事件，可以使用 ssq.push('onReady', () => { /* ... */ }); 方法。这可以确保在资源完全加载后执行你定义的操作，比如打开聊天窗口或进行其他初始化工作。

js 复制代码

ssq.push('onReady', () => {
  // 执行其他事件
});

// 使用示例：
<script id="ss_chat" defer src="https://example.js"></script>

<script>
   const ss_chat = document.getElementById('ss_chat');
   ss_chat.addEventListener('load', (e) => {
      window.ssq && window.ssq.push('onReady', () => {
        // 执行事件
      });
   })
</script>

2.15 自定义 WhatsApp 跳转文案

当用户点击 whatsapp 图标跳转到 whatsapp 官方网站时，允许您设置在跳转到 WhatsApp 官方网站时显示的问候语或自定义消息。

js 复制代码

ssq.push('createWhatsappGreeting', function(msg){
    // msg默认为Hello.
    return msg + 'tony'; // 输出结果：Hello.tony
    // 如果需要完全自定义，可直接返回自定义的文字，如：
    // return '你好' // 输出结果：你好
});

2.16 在客户端发送文本消息

实现让访客能够主动发起信息的功能，例如在软件中发生错误或浏览商品时咨询，可以使用类似 ssq.push('sendTextMessage', 'your message') 的方法来发送消息。或者是在浏览商品中点击商品咨询，可以直接发送一些商品信息等

js 复制代码

ssq.push('sendTextMessage', 'it is an error', function(result) {
  console.log('sendTextMessage 状态：', result.status);
});

#示例1捕获错误信息并发送到客服：
function handleError(error) {
    // 发送错误信息到客服系统
    ssq.push('sendTextMessage', `Error encountered: ${error.message}`);
}

// 示例：捕获并处理错误
try {
    // 你的代码逻辑
} catch (error) {
    handleError(error);
}

#示例2点击按钮发送咨询信息
<!-- 示例 HTML 按钮 -->
<button onclick="sendProductInquiry('Product Name')">咨询商品</button>

<script>
    function sendProductInquiry(productName) {
        // 发送商品咨询信息到客服系统
        ssq.push('sendTextMessage', `咨询关于商品: ${productName}`);
    }
</script>

回调状态：

success：消息生成 c_m_id 后，20 秒内收到服务端成功回执。
failed：从生成 c_m_id 开始，20 秒内始终没有收到成功回执。
ignored：当前正在进行流式回复，或身份切换取消了发送。
ready 前的排队时间不计入 20 秒结果窗口。
窗口内的中间发送失败不会提前返回 failed，内部自动重试仍可能成功。
窗口结束后的晚到回执不会修改原回调状态，用户手动重试也不会复用原回调。

2.17 关闭上传功能

可用于实现关闭访客端对应的上传功能

js 复制代码

ssq.push('hideUpload', ['img', 'video', 'document'], function(result) {
  console.log('hideUpload 状态：', result.status);
});
// 'img' 图片类型
// 'video' 视频类型
// 'document' 附件类型

// 如果设置了关闭，想要在某个操作中将功能重新开放出来，则将数组中的对应项去除，重新调用
// 例：ssq.push('hideUpload', [])

回调状态：

success：上传入口配置已经写入；重复写入相同配置仍按成功处理。
合法数组参数调用下不会返回 failed。

2.18 隐藏关闭窗口按钮

当聊天插件入口收起时，可通过该方法将聊天窗口右上角处的关闭窗口按钮隐藏

js 复制代码

ssq.push('hideCloseIcon', function(result) {
  console.log('hideCloseIcon 状态：', result.status);
});

回调状态：

success：关闭按钮隐藏状态已经写入；重复调用仍按成功处理。
合法调用下不会返回 failed。

2.19 获取插件入口高度

用于获取当前聊天插件入口区域在页面中的实际展示高度，单位为 px。
这里的“入口区域”包括侧边栏收起态、侧边栏展开态、单图标入口、渠道图标列等当前可见的插件入口元素。SDK 会计算这些可见入口元素在垂直方向上的整体占用高度，并通过回调返回。

该 API 适合用于宿主页面需要避让聊天插件入口的场景，例如调整自定义悬浮按钮、自定义通知浮层、底部工具栏或其他固定定位元素的位置。

js 复制代码

ssq.push('getSidebarHeight', function(height) {
    console.log(height); // 插件入口区域当前占用高度，单位 px
});

推荐在 onReady 后调用，确保插件配置和入口元素已经完成初始化：

js 复制代码

ssq.push('onReady', function() {
    ssq.push('getSidebarHeight', function(height) {
        // 例如：根据插件入口高度调整宿主页面悬浮元素位置
        console.log('Current sidebar height:', height);
    });
});

2.20 预填输入框内容

用于将指定文本预填到聊天插件的输入框中，访客可以继续编辑并手动发送。调用该 API 不会自动打开聊天窗口、切换当前页面、聚焦输入框或发送消息。

text 必须为字符串，插件会按照 JavaScript text.slice(0, 1000) 保存前 1000 个 UTF-16 单元。传入空字符串可清空当前草稿；多次调用时，以最后执行的一次为准。

js 复制代码

ssq.push('setInputText', '请输入需要预填的内容', function(result) {
  console.log('setInputText 状态：', result.status);
});

// 清空输入框草稿
ssq.push('setInputText', '');

回调状态：

success：输入框草稿已经写入；重复写入相同文本仍按成功处理。
合法字符串参数调用下不会返回 failed。

常见问题：

1.Uni-app 端支持调用 ssq.push 方法吗？

暂时不支持，JSSDK 在 uni-app 上只能运行在 h5 环境上使用的，别的环境暂时还不支持

2.ssq is not defined（ssq 未定义或声明它）

互换下 JSSDK 和 JavaScript 代码顺序，JavaScript 代码在上面，JSSDK 在下面。如图：

3.在App内安装了聊天插件点击图片、视频、附件上传没有反应？

原因：只能在H5环境下使用，因为SDK需要挂在到window对象上，在 UniApp 中，不同的平台有不同的全局对象。window 对象是 Web 浏览器的全局对象，但在一些非浏览器环境（如App、微信小程序、支付宝小程序等）中，是没有 window 对象的.

解决措施：
(1). 安卓端可以使用Android SDK的8、文件选择回调，详情查看：https://help.salesmartly.com/docs/ma4Mfu#8、文件选择回调
(2). 使用 Web-view 组件来加载一个 H5 页面，然后在这个 H5 页面中使用SDK（可能会出现一些问题，Web-view 组件默认情况下并不能直接调用原生应用的功能，需要对方的技术人员进行处理，例如文件上传）

上一个

如何设置 SaleSmartly 以进行 Google Analytics（分析）跟踪

下一个

SaleSmartly Android SDK开发者文档

最近修改: 2026-08-11Powered by

大纲