企业内部开发 客户端API 小程序 会话 私密消息
私密消息

目录

  • 概述
  • 使用说明
  •       1. 分享
  •       2. 验证
  • 接口说明
  •       setShareAttr
  •       getContext
  •       getShareInfo
  • 注意事项
  •       state的作用
  •       curReceiver的作用
  •       加密数据encryptedData解密算法
  •       旧版本的兼容
  •       微信客户会话的问题
  • 概述

    企业微信从3.1.8版本开始,支持将网页或小程序转发时设置为私密消息。当企业成员将网页或小程序分享给其他成员或群聊后,其他成员打开网页或小程序时,开发者可判断当前用户是否为消息的直接接收人。同时,私密消息具有不可二次转发性,即在3.1.8及以后的版本,私密消息没有转发入口。企业微信的私密消息与微信小程序私密消息类似,不过有几个差异点:

    • 企业微信的私密消息支持网页与小程序。
    • 企业微信的私密消息通过调用setShareAttr进行声明,声明时指定withShareTicket为true,即将消息声明带shareticket,在企业微信里,带shareticket的消息即为私密消息。
    • 企业微信的私密消息没有引入动态消息activity_id,而是以开发者自定义的state值来替代。
    • 企业微信通过getContext返回shareTicket,并通过getShareInfo返回加密的群id、state值、当前用户open_userid.

     

    使用说明

    1. 分享

    在用户分享网页或小程序前,先调用setShareAttr,将本页面的转发声明为shareticket消息。声明之后,该页面被转发之后都有shareticket属性,转发途径包括:右上角菜单、聊天附件栏页面的底部“发送”按钮、聊天附件栏或聊天工具栏调用sendChatMessage接口等。

    场景一: 个人分享给个人
    A --> B

    场景二: 个人分享给群
    A --> [B, C, D, E]

    注意:分享之后,被移出群的成员将不再有该shareticket消息的访问权限,而后来进群的成员则自动拥有了访问权限。

     

    2. 验证

    带有shareticket的消息卡片,用户打开网页或小程序,开发者调用getContext时,可以得到shareticket。再根据shareticket调用getShareInfo,如果当前用户是消息的直接接收者,则企业微信会返回加密的encryptedData,如果不是直接接收者,则接口会返回错误。

     

    接口说明

    setShareAttr

    接口定义

    wx.qy.setShareAttr ({
    	withShareTicket:true,
        state: "STATE",
    	success: function(res) {
        	
      }
    })
    必须先调用过wx.qy.login,且session_key未过期,开发者可调用checkSession 检查当前登录态
    当前成员必须在应用的可见范围

    传入参数

    参数名类型是否必须说明
    withShareTicketBoolean默认为false
    stateString详见state的作用

     

    getContext

    接口定义详见“wx.qy.getContext”,以下是示例代码:

    wx.qy.getContext ({
      success: function(res) {
        var entry = res.entry; //返回进入小程序的入口类型
    	var shareTicket = res.shareTicket;
      }
    })

     

    getShareInfo

    接口定义

    wx.qy.getShareInfo ({
      shareTicket:"xxxx",
      success: function(res) {
        var encryptedData = res.encryptedData; //转发信息的加密数据
    	var iv = res.iv; //加密算法的初始向量 
      }
    })
    需要wx.qy.login,且session_key未过期,开发者可调用checkSession 检查当前登录态
    当前成员必须在应用的可见范围

    传入参数

    参数名类型是否必须说明
    shareTicketString调用getContext时获取到的shareTicket

    返回结果

    参数名类型是否必须说明
    encryptedDataString转发信息的加密数据
    ivString加密算法的初始向量

    将encryptedData解密得到的开放数据为以下 json 结构(解密算法详见“加密数据encryptedData解密算法”):

    {
         "chatId": "CHATID",
         "state": "STATE",
         "curReceiver": "CURRECEIVER",
    }

    json结构说明:

    参数名类型是否必须说明
    chatIdString群聊时返回,群id,单聊时返回空字符串
    stateStringsetShareAttr时传入的state参数,详见state的作用
    curReceiverString当前接收者的userid,对于自建应用返回的是明文userid,对于第三方应用返回的是加密的open_userid。详见curReceiver的作用

    注意事项

    state的作用

    调用setShareAttr时,可以传一个state参数,该参数值由开发者自由指定。shareticket消息分享之后,当接收者打开消息的H5页面或小程序时,开发者调用getShareInfo,企业微信会将state值加密返回,开发者可在后台解密并加以校验。

    curReceiver的作用

    用户进入网页时,网页通过oauth2可获得用户的userid(第三方应用可获得open_userid)。调用getShareInfo时,企业微信会将当前用户的userid或open_userid通过curReceiver加密在encryptedData里返回。
    为了避免encryptedData被重放攻击,我们建议开发者检查curReceiver与oauth2获得的userid(或open_userid)是否一致。

    加密数据encryptedData解密算法

    1. 解密使用的算法为 AES-128-CBC,数据采用PKCS#7填充。
    2. 对称解密的目标密文为 Base64_Decode(encryptedData)。
    3. 对称解密秘钥 aeskey = Base64_Decode(session_key), aeskey长度为16字节。
    4. 对称解密算法初始向量 为Base64_Decode(iv),其中iv由数据接口返回。

     

    旧版本的兼容

    在企业微信的旧版本里,shareticket消息是可以长按转发到其他会话里的,所以开发者一定要通过getShareInfo的返回值来检查当前用户是否消息的直接接收者。

    微信客户会话的问题

    企业微信的shareticket属性不支持同步到微信,当shareticket消息分享到包含微信用户的会话中,用户在微信打开时是没法获取到shareticket的。

    上一篇
    wx.qy.sendChatMessage
    下一篇
    wx.qy.createCorpGroupChat