沟通中台（聚合聊天）JSSDK

一、引入 JSSDK 文件

将以下代码插入 HTML

<script src="https://qiyeweixin.gnlab.cn/jssdk/quntool-jssdk-1.1.0.js"></script>

二、使用 QunTool JSSDK

沟通中台 JSSDK 会注册一个全局变量：window.QunTool，格式如下：

window.QunTool = {
  // 当前是否处于 QunTool 环境中，若为 false，则此 JSSDK 不可用
  inQunTool: boolean,
  
  // 执行 QunTool 相关操作，此方法会返回一个 Promise
  // 支持的操作类型见下文
  invoke(type: string, data?: any): Promise<any>
}

调用示例：

window.QunTool.invoke('get-customer-info')
  .then(result => {
    if (result.success) console.log('customer-info', result.data)
    else console.log('信息获取失败', result.error)
  })

window.QunTool.invoke('send-text', 'hello')
  .then(() => alert('消息已发送'))

三、JSSDK 支持的操作列表

获取当前登录账号

window.QunTool.invoke('get-account')
  .then((result: Result) => {})
  
type Result = { success: true, data: Account } | { success: false, error: string }

interface Account {
  id: number // 账号 ID
  parentId: number | null // 当前是子账号时此为主账号 ID；当前是主账号时为 null
  name: string // 昵称或手机号
  avatar: string // 头像
  isSuperAdmin: boolean // 是否是超级管理员。当前是主账号为 true；当前是子账号为 false
  isAdmin: boolean // 当前账号是否有管理员权限。主账号一定有，子账号需由主账号赋予权限。
  token: string // 账号登录凭证。详见“基于 JSSDK 实现身份认证”。
}

获取当前账号登录的企业微信列表

window.QunTool.invoke('get-qywx-list')
  .then((result: Result) => {})
  
 type Result = { success: true, data: Qywx[] } | { success: false, error: string }

interface Qywx {
  wxid: string,
  acctid: string,
  avatar: string,
  mobile: string,
  nickname: string,
  username: string,
  corpid: string,
  corp_name: string,
  corp_short_name: string,
  job_name: string,
  position: string,
}

获取当前联系人信息

window.QunTool.invoke('get-current-contact')
  .then((result: Result) => {})
  
type Result = { success: true, data: BaseContactInfo } | { success: false, error: string }

interface BaseContactInfo {
  type: string,            // 联系人类型。external 客户；internal 员工；group 群
  wxid: string,            // 联系人所属企业微信的 wxid
  contactUserId: string,   // 联系人自己的 userId
  nickname: string,        // 联系人昵称
}

2023年8月30日：支持群和员工；新增 type 字段

获取客户 ID

window.QunTool.invoke('get-customer-info')
  .then((result: Result) => {})
  
type Result = { success: true, data: CustomInfo } | { success: false, error: string }

interface CustomInfo {
  contactUserId: string,
  externalUserId: string,
  corpId: string,
  corpIdOrigin: string,
  unionId: string,
}

发送文本消息

window.QunTool.invoke('send-text', text)

发送图片

window.QunTool.invoke('send-image', url)

发送视频

window.QunTool.invoke('send-video', url)

发送文件

window.QunTool.invoke('send-file', url)

发送超链接卡片

window.QunTool.invoke('send-link', {
  title: string, 
  desc: string,
  url: string, 
  imageUrl: string,
})

获取小程序列表

window.QunTool.invoke('load-miniprograms')
  .then((list: Miniprogram[]) => {})

interface Miniprogram {
  id: number,       // 小程序 ID，用于后续发送小程序消息
  title: string,    // 小程序标题
  headimg: string,  // 小程序图标
}

发送小程序

window.QunTool.invoke('send-miniprogram', id)
  .then((result: Result) => {})
  
type Result = { success: true } | { success: false, error: string }

发送小程序（直接传入数据）

window.QunTool.invoke('send-miniprogram-by-data', data)

interface MiniProgram {
  username: string // gh_3a18fa53cb80@app
  appid: string // wx723bb5bb25362f6c
  appname: string // 小程序名称
  appicon: string // 小程序 logo
  title: string // 小程序标题
  page_path: string // 页面路径
  cover_path: string // 封面图片
}

需确保小程序数据是真实有效的，否则会发送失败。

发送一组消息

window.QunTool.invoke('batch-send', [
  { type: 'text', data: 'string' },
  { type: 'image', data: 'url' },
  { type: 'file', data: 'url' },
  { type: 'video', data: 'url' },
  { type: 'link', data: { ... },  // 格式见'发送超链接卡片'
  { type: 'miniprogram', data: 1 }, // data 为小程序 ID
  
  ...
])

调用后，会在 QunTool 界面中弹出一个编辑框，
文本消息可在其中编辑，其他消息暂时只能查看和删除。
在编辑框中点“发送”完成发送。

打开与指定客户的聊天窗口

window.QunTool.invoke('switch-contact', {
  wxid: 'string',
  externalUserId: 'string',
})

判断是否处于“观察者模式”

观察者模式是由管理员查看其他员工的聊天情况。此模式下，调用 JSSDK 的“账号信息”接口，取得的是管理员而不是被观察的账号信息。

window.QunTool.invoke('get-is-observing')
  .then((result: Result) => {})

// result.data === true 代表处于观察者模式
type Result = { success: true, data: boolean }

四、基于 JSSDK 实现身份认证

若加载 JSSDK 的网页需要和自己的后端进行身份认证，可基于如下流程实现：

网页通过 JSSDK 的 get-account 操作取得当前账号 token，传给后端
后端用 token 请求光年的 账号信息 接口，检查其是否合法，并取得账号信息
后端基于账号信息，重新生成一个自己的 token 返回给前端

光年 账号信息 接口请求格式：

Method: GET
URL: https://account.gnlab.com/api/current
Headers: token

CURL 请求示例：

curl 'https://account.gnlab.com/api/current' -H 'token: 1212'

成功返回值（JSON）：

// 当前账号是主账号：
{
  "code": 0,
  "msg": "success",
  "data": {
    // 2 主账号；3 子账号
    "RoleId": 2, 

    "ID": 111, // 主账号 ID
    "Phone": "13133113311", // 主账号注册手机号
    "WxAvatar": "https://abc.jpg", // 主账号微信头像（绑定微信才有）
    "WxNickname": "测试账号", // 主账号微信昵称（绑定微信才有）
    "Company": "光年实验室（测试账号）", // 公司名称

    "SubUserId": 0,
    "SubUserName": "",
    "SubWxAvatar": ""
  }
}

// 当前账号是子账号：
{
  "code": 0,
  "msg": "success",
  "data": {
    // 2 主账号；3 子账号	
    "RoleId": 3,
    
    // 所属主账号信息（不是当前账号自己的信息）
    "ID": 111,
    "Phone": "13133113311",
    "WxAvatar": "https://thirdwx.qlogo.cn/mmopen/vi_32/Q0j4TwGTfTKEkWE932ZtVicLodibnOCROPGUIFJhpqwgdlFSFmrSLw50Kv0suTtkdib2a5QOFkkDU0G8vlPW8wTibw/132",
    "WxNickname": "测试账号",
    "Company": "光年实验室（测试账号）",
    
    // 子账号信息
    "SubUserId": 222, // 子账号 ID
    "SubWxAvatar": "https://def.jpg", // 子账号微信头像
    "SubUserName": "测试子账号", // 子账号微信昵称
  }
}

失败返回值（JSON）：

{ "code": -4, "msg": "TOKEN错误" }

五、ChangeLog

2023年10月10日

新增 get-is-observing 方法，用于判断是否处于观察者模式

2023年8月30日

get-account 的增加 token 返回值，用于身份认证。

2023年8月11日

新增 send-miniprogram-by-data 操作

2023年8月7日

新增 get-account 操作

更新时间：2023-11-24 15:55