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

## 一、功能介绍

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

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

| 能力               | 说明                                                                            | 图示                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| 聊天成员相关能力   | 开发者可调用聊天成员选择器并获取成员相关id，通过open-data渲染聊天成员的头像昵称 | ![](https://res8.wxqcloud.qq.com.cn/wxdoc/00e686eb-b6c5-4731-a707-f25c01003a1e.png) |
| 发送内容到聊天能力 | 开发者可发送文本、提醒、图片、表情、视频等内容类型到聊天中                      | ![](https://res8.wxqcloud.qq.com.cn/wxdoc/3d68ee21-ee40-4a9d-bda9-2d846d089f0b.png) |
| 动态消息能力       | 小程序卡片上的辅标题可以动态更新，在用户完成/参与了活动后下发系统消息           | ![](https://res8.wxqcloud.qq.com.cn/wxdoc/3050c9e4-fd01-4cb8-b66e-fde9e4a15d4b.png) |

支持有「交易保障」标识的小程序，或「社交」、「金融-证券/期货」、「金融-公募基金」、「金融-银行」类目的小程序申请相关接口权限。开发者需要登录小程序管理后台 ，在「管理-开发管理-其他接口-聊天工具」中申请获得接口权限，审核通过后可使用。

## 二、开发指南

> 从基础库 3.12.0 版本开始支持
>
> 支持平台：iOS 8.0.65 及以上版本；Android 8.0.65 及以上版本

### 1. 进入聊天工具模式

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

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

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

#### 1.1 wx.getGroupEnterInfo

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

入参：

| 属性            | 类型    | 说明                                          |
| --------------- | ------- | --------------------------------------------- |
| allowSingleChat | boolean | 为 true 时才会返回单聊下的 open_single_roomid |
| needGroupOpenID | boolean | 为 true 时才会返回 group_openid               |

返回参数（数据加密返回，解密请参考：[wx.getGroupEnterInfo](/miniprogram/dev/api/open-api/group/wx.getGroupEnterInfo.md)）：

| 属性               | 类型   | 说明                                                                                         |
| ------------------ | ------ | -------------------------------------------------------------------------------------------- |
| opengid            | string | 群聊唯一标识，绑定的聊天室为群聊时返回                                                       |
| open_single_roomid | string | 单聊唯一标识，绑定的聊天室为单聊时返回                                                       |
| group_openid       | string | 当前微信用户在此聊天室下的唯一标识，同一个用户在不同的聊天室下id不同                         |
| chat_type          | number | 微信聊天类型，1：微信联系人单聊；2：企业微信联系人单聊；3：普通微信群聊；4：企业微信互通群聊 |

#### 1.2 wx.getChatToolInfo

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

返回参数（数据加密返回，解密请参考：[wx.getGroupEnterInfo](/miniprogram/dev/api/open-api/group/wx.getGroupEnterInfo.md)）：

| 属性               | 类型   | 说明                                                                                         |
| ------------------ | ------ | -------------------------------------------------------------------------------------------- |
| opengid            | string | 群聊唯一标识，绑定的聊天室为群聊时返回                                                       |
| open_single_roomid | string | 单聊唯一标识，绑定的聊天室为单聊时返回                                                       |
| group_openid       | string | 当前微信用户在此聊天室下的唯一标识，同一个用户在不同的聊天室下id不同                         |
| chat_type          | number | 微信聊天类型，1：微信联系人单聊；2：企业微信联系人单聊；3：普通微信群聊；4：企业微信互通群聊 |

#### 1.3 wx.selectGroupMembers

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

请求参数：

| 属性           | 类型   | 必填 | 说明         |
| -------------- | ------ | ---- | ------------ |
| maxSelectCount | number | 否   | 最多可选人数 |

返回参数：

| 属性    | 类型     | 说明                                                               |
| ------- | -------- | ------------------------------------------------------------------ |
| members | string[] | 所选用户在此聊天室下的唯一标识，同一个用户在不同的聊天室下 id 不同 |

#### 1.4 `<open-data-list>` `<open-data-item>`

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

属性：

`<open-data-list>`

| 属性    | 类型     | 必填 | 说明                                   |
| ------- | -------- | ---- | -------------------------------------- |
| type    | string   | 是   | 渲染类型，固定为`groupMembers`         |
| members | string[] | 是   | 需要展示的用户此聊天室下的唯一标识列表 |

`<open-data-item>`

| 属性 | 类型   | 必填 | 说明                                                          |
| ---- | ------ | ---- | ------------------------------------------------------------- |
| type | string | 是   | 开放数据类型，userNickName：用户昵称；userAvatarUrl：用户头像 |

代码示例：

```html
<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>
```

#### 1.1 wx.exitChatTool

功能描述：退出聊天工具开放模式

代码示例：

```ts
wx.exitChatTool({
  success() {},  // 成功回调
  fail() {},  // 失败回调
})
```

### 2. 发送到聊天能力

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

#### 2.1 wx.shareAppMessageToGroup

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

请求参数：

| 属性     | 类型   | 必填 | 说明                                                                                                            | 默认值                   |
| -------- | ------ | ---- | --------------------------------------------------------------------------------------------------------------- | ------------------------ |
| title    | string | 是   | 小程序卡片标题                                                                                                  |                          |
| opengid  | string | 否   | 通过 `wx.selectGroups` 选择聊天后，opengid 为必填；通过`wx.selectGroupMembers` 选择单个聊天后，opengid 无需填写 |                          |
| path     | string | 否   | 转发路径                                                                                                        | 聊天工具的 entryPagePath |
| imageUrl | string | 否   | 自定义图片路径，可以是本地文件路径、代码包文件路径或者网络图片路径。支持 PNG 及 JPG。显示图片长宽比是 5:4       | 使用默认截图             |

返回参数：

| 属性   | 类型   | 说明     |
| ------ | ------ | -------- |
| errMsg | string | 错误信息 |

#### 2.2 wx.notifyGroupMembers

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

请求参数：

| 属性         | 类型     | 必填 | 说明                                                                                                            | 默认值 |
| ------------ | -------- | ---- | --------------------------------------------------------------------------------------------------------------- | ------ |
| title        | string   | 是   | 文字链标题                                                                                                      |        |
| opengid      | string   | 否   | 通过 `wx.selectGroups` 选择聊天后，opengid 为必填；通过`wx.selectGroupMembers` 选择单个聊天后，opengid 无需填写 |        |
| members      | string[] | 是   | 需要提醒的用户 group-openid 列表                                                                                |        |
| entrancePath | string   | 是   | 文字链跳转路径                                                                                                  |        |
| type         | string   | 是   | 展示的动词：participate：“请参与”；complete：“请完成”                                                           |        |

返回参数：

| 属性   | 类型   | 说明     |
| ------ | ------ | -------- |
| errMsg | string | 错误信息 |

#### 2.3 form 组件

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

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

属性：

`<form>`

| 属性               | 类型   | 必填 | 说明                                 |
| ------------------ | ------ | ---- | ------------------------------------ |
| bind:submitToGroup | string | 是   | 用户触发发送文本到聊天后会触发的事件 |

`<button>`

| 属性               | 类型    | 必填 | 说明                                                                                                            | 默认值                   |
| ------------------ | ------- | ---- | --------------------------------------------------------------------------------------------------------------- | ------------------------ |
| form-type          | string  | 是   | 需填入 `submitToGroup`，表示将文本发送到聊天                                                                    |                          |
| opengid            | string  | 否   | 通过 `wx.selectGroups` 选择聊天后，opengid 为必填；通过`wx.selectGroupMembers` 选择单个聊天后，opengid 无需填写 |                          |
| need-show-entrance | boolean | 否   | 是否在文本消息下展示进入小程序的小尾巴                                                                          | true                     |
| entrance-path      | string  | 否   | 小尾巴跳转路径                                                                                                  | 聊天工具的 entryPagePath |

#### 2.4 wx.shareImageToGroup

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

请求参数：

| 属性             | 类型   | 必填 | 说明                                                                                                            | 默认值                   |
| ---------------- | ------ | ---- | --------------------------------------------------------------------------------------------------------------- | ------------------------ |
| imagePath        | string | 是   | 图片路径，可以是本地文件路径或临时路径                                                                          |                          |
| opengid          | string | 否   | 通过 `wx.selectGroups` 选择聊天后，opengid 为必填；通过`wx.selectGroupMembers` 选择单个聊天后，opengid 无需填写 |                          |
| needShowEntrance | string | 否   | 是否在图片消息下展示进入小程序的小尾巴                                                                          | true                     |
| entrancePath     | string | 否   | 小尾巴跳转路径                                                                                                  | 聊天工具的 entryPagePath |

返回参数：

| 属性   | 类型   | 说明     |
| ------ | ------ | -------- |
| errMsg | string | 错误信息 |

#### 2.5 wx.shareEmojiToGroup

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

请求参数：

| 属性             | 类型   | 必填 | 说明                                                                                                            | 默认值                   |
| ---------------- | ------ | ---- | --------------------------------------------------------------------------------------------------------------- | ------------------------ |
| imagePath        | string | 是   | 表情路径，可以是本地文件路径或临时路径                                                                          |                          |
| opengid          | string | 否   | 通过 `wx.selectGroups` 选择聊天后，opengid 为必填；通过`wx.selectGroupMembers` 选择单个聊天后，opengid 无需填写 |                          |
| needShowEntrance | string | 否   | 是否在表情消息下展示进入小程序的小尾巴                                                                          | true                     |
| entrancePath     | string | 否   | 小尾巴跳转路径                                                                                                  | 聊天工具的 entryPagePath |

返回参数：

| 属性   | 类型   | 说明     |
| ------ | ------ | -------- |
| errMsg | string | 错误信息 |

#### 2.6 wx.shareVideoToGroup

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

请求参数：

| 属性             | 类型   | 必填 | 说明                                                                                                             | 默认值                   |
| ---------------- | ------ | ---- | ---------------------------------------------------------------------------------------------------------------- | ------------------------ |
| videoPath        | string | 是   | 视频路径，可以是本地文件路径或临时路径                                                                           |                          |
| opengid          | string | 否   | 通过 `wx.selectGroups` 选择聊天后，opengid 为必填；通过 `wx.selectGroupMembers` 选择单个聊天后，opengid 无需填写 |                          |
| thumbPath        | string | 否   | 缩略图路径，若留空则使用视频首帧                                                                                 |                          |
| needShowEntrance | string | 否   | 是否在视频消息下展示进入小程序的小尾巴                                                                           | true                     |
| entrancePath     | string | 否   | 小尾巴跳转路径                                                                                                   | 聊天工具的 entryPagePath |

返回参数：

| 属性   | 类型   | 说明     |
| ------ | ------ | -------- |
| errMsg | string | 错误信息 |

#### 2.7 wx.shareFileToGroup

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

请求参数：

| 属性             | 类型   | 必填 | 说明                                                                                                            | 默认值                   |
| ---------------- | ------ | ---- | --------------------------------------------------------------------------------------------------------------- | ------------------------ |
| filePath         | string | 是   | 文件路径，可以是本地文件路径或临时路径                                                                          |                          |
| opengid          | string | 否   | 通过 `wx.selectGroups` 选择聊天后，opengid为必填；通过 `wx.selectGroupMembers` 选择单个聊天后，opengid 无需填写 |                          |
| needShowEntrance | string | 否   | 是否在文件消息下展示进入小程序的小尾巴                                                                          | true                     |
| entrancePath     | string | 否   | 小尾巴跳转路径                                                                                                  | 聊天工具的 entryPagePath |

返回参数：

| 属性   | 类型   | 说明     |
| ------ | ------ | -------- |
| errMsg | string | 错误信息 |

### 3. 动态消息能力

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

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

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

该功能的开发步骤包括：

1.  服务端通过[创建activity_id](/miniprogram/dev/server/API/mp-message-management/updatable-message/api_createactivityid.md)接口创建 activity_id

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

| 属性               | 类型     | 必填 | 说明                                                                                                                                                |
| ------------------ | -------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| withShareTicket    | boolean  | 是   | 是否使用带 shareTicket 的转发，固定为 `true`                                                                                                        |
| isUpdatableMessage | boolean  | 是   | 是否是动态消息，固定为 `true`                                                                                                                       |
| activityId         | string   | 是   | 动态消息的 activityId，通过步骤1中的接口获取                                                                                                        |
| useForChatTool     | boolean  | 是   | 聊天工具模式特殊动态消息                                                                                                                            |
| chooseType         | number   | 是   | 指定成员的方式                                                                                                                                      |
| participant        | string[] | 是   | 需参与用户此聊天室下的唯一标识列表                                                                                                                  |
| templateInfo       | Object   | 是   | 动态消息的模板信息，固定为 `{templateId: '4A68CBB88A92B0A9311848DBA1E94A199B166463'}` 或 `{templateId: '2A84254B945674A2F88CE4970782C402795EB607'}` |

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

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

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

代码示例：

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

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

| templateId                               | 4A68CBB88A92B0A9311848DBA1E94A199B166463                                                                                                                                                                                      | 2A84254B945674A2F88CE4970782C402795EB607                                                                                                                                                                                      |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 动态消息发布者在小程序卡片中看到的辅标题 | target_state=1或2：X人已完成

target_state=3：已结束                                                                                                                                                                    | target_state=1或2：X人已参与

target_state=3：已结束                                                                                                                                                                    |
| 参与者在小程序卡片中看到的辅标题         | participator_state=0时：

● target_state=1：未完成

● target_state=2：即将截止

● target_state=3：已结束

participator_state=1时：

● target_state=1或2：已完成

● target_state=3：已结束 | participator_state=0时：

● target_state=1：未参与

● target_state=2：即将截止

● target_state=3：已结束

participator_state=1时：

● target_state=1或2：已参与

● target_state=3：已结束 |
| 非参与者在小程序卡片中看到的辅标题       | target_state=1或2：你无需完成

target_state=3：已结束                                                                                                                                                                   | target_state=1或2：你无需参与

target_state=3：已结束                                                                                                                                                                   |
| 参与者变为完成态下发的系统消息文案       | aaa 已完成 bbb 发布的 XXX                                                                                                                                                                                                     | aaa 已参与 bbb 发布的 XXX                                                                                                                                                                                                     |

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

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

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

请求参数：

| 属性                   | 类型          | 必填 | 说明                                                                              |
| ---------------------- | ------------- | ---- | --------------------------------------------------------------------------------- |
| access_token           | string        | 是   | 接口调用凭证                                                                      |
| activity_id            | string        | 是   | 动态消息的 activityId，通过步骤1中的接口获取                                      |
| target_state           | number        | 是   | 活动状态，初始值为1（表示开始收集态），此处可设置为2（即将截止态）、3（已结束态） |
| participator_info_list | array | 否   | 更新后的聊天室成员状态，当target_state=1时必填，target_state=2或3时无需填写       |
| version_type           | number        | 是   | 系统消息文字链打开的小程序版本，0 正式版，1 开发版，2 体验版                      |

participator_info_list参数如下：

| 属性         | 类型   | 必填 | 说明                                                                                         |
| ------------ | ------ | ---- | -------------------------------------------------------------------------------------------- |
| group_openid | string | 是   | 聊天室成员在此聊天室下的唯一标识                                                             |
| state        | number | 是   | 用户对卡片事件的完成状态。所有参与者的初始值为0（未完成态），此处仅支持设置为1，表示完成态。 |

调用示例：

```json
//变更单个成员状态
{
  "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. 聊天工具模式内禁用的能力

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

| 能力项                       | 禁用说明                                                                   |
| ---------------------------- | -------------------------------------------------------------------------- |
| `<button open-type=share>`   | 聊天工具模式禁用普通转发能力，请使用上文「发送到聊天能力开放」中的接口实现 |
| 小程序右上角「…-发送给朋友」 |
| navigateToMiniProgram        | 聊天工具模式希望服务尽可能闭环在小程序中，外跳类接口暂不支持使用           |
| openEmbeddedMiniProgram      |
| openOfficialAccountArticle   |
| openChannelsUserProfile      |
| openChannelsLive             |
| openChannelsEvent            |
| openChannelsActivity         |
| ad                           | 聊天工具模式暂不支持广告                                                   |
| ad-custom                    |