# 小程序聊天工具开放模式开发指南

# 一、功能介绍

聊天工具模式是为了帮助小程序更好与微信聊天结合而推出的模式，可用于实现群问卷、群拼单、群接龙等功能。其与小程序普通模式区别在于：

1.  开放更多与聊天紧密结合的能力：

能力	说明	图示
聊天成员相关能力	开发者可调用聊天成员选择器并获取成员相关id，通过open-data渲染聊天成员的头像昵称
发送内容到聊天能力	开发者可发送文本、提醒、图片、表情、视频等内容类型到聊天中
动态消息能力	小程序卡片上的辅标题可以动态更新，在用户完成/参与了活动后下发系统消息

# 二、开发指南

从基础库 3.12.0 版本开始支持

支持平台：iOS 8.0.65 及以上版本；Android 8.0.65 及以上版本

# 1. 进入聊天工具模式

开发者调用 wx. enterChatToolMode 后，可选择在 chatToolRooms 传入 opengid 以进入聊天模式，并获得聊天成员相关接口的调用权限；如果未传入 opengid，则将拉起群聊选择器；

开发者可通过 wx.isChatTool 判断当前是否处于聊天工具模式；

聊天工具模式下应使用 group_openid 作为用户唯一标识。

# 1.1 wx.getGroupEnterInfo

功能描述：进入聊天工具模式前，获取群聊 id 信息

入参：

返回参数（数据加密返回，解密请参考：https://developers.weixin.qq.com/miniprogram/dev/api/open-api/group/wx.getGroupEnterInfo.html）：

# 1.2 wx.getChatToolInfo

功能描述：进入聊天工具模式后，获取群聊 id 信息

返回参数（数据加密返回，解密请参考：https://developers.weixin.qq.com/miniprogram/dev/api/open-api/group/wx.getGroupEnterInfo.html）：

# 1.3 wx.selectGroupMembers

功能描述：选择聊天室的成员，并返回选择成员的 group-openid。若当前为群聊，则会拉起成员选择器；若当前为单聊，则直接返回对方用户的 group-openid

请求参数：

返回参数：

# 1.5

功能描述：用于渲染聊天成员的头像昵称

属性：

<open-data-list>

<open-data-item>

代码示例：

<open-data-list type="groupMembers" members="[groupOpenID1, groupOpenID2]">
  <view class="userinfo" slot:index>
    <open-data-item class="avatar " type="userAvatar" index="{{index}}" />     <open-data-item class="" type="userNickName" index="{{index}}" />
  </view>
</open-data-list>

# 2. 发送到聊天能力

可支持小程序卡片、提醒消息、文本、图片、表情、文件的发送，如果选择了多个群聊，单次仅支持将内容发送到特定的单个群聊中。

# 2.1 wx.shareAppMessageToGroup

功能描述：将小程序卡片发送到绑定的聊天室

请求参数：

返回参数：

# 2.2 wx.notifyGroupMembers

功能描述：提醒用户完成任务，发送的内容将由微信拼接为：@的成员列表+“请完成：”/"请参与："+打开小程序的文字链，如「@alex @cindy 请完成：团建报名统计」

请求参数：

返回参数：

# 2.3 form 组件

<form bind:submitToGroup="onSubmitToGroup"> <button form-type="submitToGroup">

功能描述：将输入框内的文本内容发送到绑定的聊天室，可携带返回聊天工具模式的小程序的小尾巴

属性：

<form>

<button>

# 2.4 wx.shareImageToGroup

功能描述：将图片发送到绑定的聊天室，可携带返回聊天工具模式的小程序的小尾巴

请求参数：

返回参数：

# 2.5 wx.shareEmojiToGroup

功能描述：将表情发送到绑定的聊天室，可携带返回聊天工具模式的小程序的小尾巴

请求参数：

返回参数：

# 2.6 wx.shareVideoToGroup

功能描述：将视频发送到绑定的聊天室，可携带返回聊天工具模式的小程序的小尾巴

请求参数：

返回参数：

# 2.7 wx.shareFileToGroup

功能描述：将文件发送到绑定的聊天室，可携带返回聊天工具模式的小程序的小尾巴

请求参数：

返回参数：

# 3. 动态消息能力

从聊天模式中发送的小程序卡片，可以获得动态消息能力，该能力的用户表现包括：

1.  小程序卡片上的辅标题可以动态更新

2.  可以在聊天中下发系统消息，内容为：成员A+“完成了”/"参与了"+成员B+“发布的”+打开小程序的文字链，如「alex 完成了 cindy 发布的 团建报名统计」

该功能的开发步骤包括：

1.  服务端通过创建activity_id接口创建 activity_id

2.  前端通过 wx.updateShareMenu 声明要分享的卡片为动态消息，请求参数如下：

useForChatTool 为 true 时，chooseType 和 participant 才会生效

chooseType = 1，表示按指定的 participant 当作参与者

chooseType = 2，表示群内所有成员均为参与者（包括后加入群）

代码示例：

wx.updateShareMenu({
  withShareTicket: true,
  isUpdatableMessage: true,
  activityId: 'xxx',
  useForChatTool: true,
  chooseType: 1,
  participant: that.data.members,
  templateInfo: {
    templateId:  '4A68CBB88A92B0A9311848DBA1E94A199B166463'
  }
})

模版区别（target_state 与 participator_state 含义见步骤3）：

1.  服务端通过 setChatToolMsg 接口更新活动状态或用户完成情况，调用方式：

POST https://api.weixin.qq.com/cgi-bin/message/wxopen/chattoolmsg/send?access_token=ACCESS_TOKEN

也可通过云开发调用，接口名 chattoolmsg.send

请求参数：

participator_info_list参数如下：

调用示例：

//变更单个成员状态
{
  "activity_id": "xxx",
  "target_state":1,
  "version_type": 0,
  "participator_info_list": [
    {
      "group_openid": "aaa",
      "state": 1
    },
    {
      "group_openid": "bbb",
      "state": 1 
    }
  ]
}

//变更动态消息状态
{
  "activity_id": "xxx",
  "target_state":3,
  "version_type": 0,
}

# 4. 聊天工具模式内禁用的能力

以下能力暂不支持聊天工具模式下使用，请开发者做好适配