wechat-chat-tool

WeChat Mini Program Chat Tool Development Guide

Supported by Base Library 3.7.8+, Android/iOS WeChat 8.0.56+

Quick Configuration

app.json configuration example

{
  "subPackages": [
    {
      "root": "packageChatTool",
      "pages": ["pages/entry/index"],
      "entry": "entry.js", // 独立分包入口文件（必须）
      "independent": true,
      "componentFramework": "glass-easel",
      "renderer": "skyline"
    }
  ],
  "chatTools": [{
    "root": "packageChatTool",
    "entryPagePath": "pages/entry/index",
    "desc": "功能描述",
    "scopes": []
  }],
  "rendererOptions": {
    "skyline": {
      "disableABTest": true,
      "defaultDisplayBlock": true,
      "defaultContentBox": true
    }
  }
}

Where entry.js code typically:

// 独立分包入口文件
// 用于聊天工具模式的初始化

const enterOptions = wx.getEnterOptionsSync()
console.log('[ChatTool Entry] Enter options:', enterOptions)

Notes:

• Subpackage size must not exceed 500KB
• Must use skyline rendering
• Each Mini Program currently supports configuring only one chat tool

Core APIs

Enter/Exit chat mode

API	Purpose
wx.openChatTool	Open chat tool mode (can pass opengid or open_single_roomid)
wx.getApiCategory	Determine whether in chat tool mode (apiCategory === 'chatTool')
wx.navigateBack	Exit chat tool mode

Get chat information

API	Purpose
wx.getChatToolInfo	Get bound group chat information within the chat tool subpackage
wx.getGroupEnterInfo	Get group chat id information before entering
wx.selectGroupMembers	Select chat room members, return group_openid

ID types

• opengid: Unique identifier for group chat
• open_single_roomid: Unique identifier for single chat
• group_openid: Unique identifier for the user under this chat room

Send to chat

API	Purpose
wx.shareAppMessageToGroup	Send Mini Program card
wx.notifyGroupMembers	Send reminder message (@member + task)
wx.shareImageToGroup	Send image
wx.shareVideoToGroup	Send video
wx.shareFileToGroup	Send file
wx.shareEmojiToGroup	Send emoji

Dynamic message

1. Server-side create activity_id
2. Frontend wx.updateShareMenu declare dynamic message
3. Server-side setChatToolMsg update status

wx.updateShareMenu({
  withShareTicket: true,
  isUpdatableMessage: true,
  activityId: "xxx",
  useForChatTool: true,
  chooseType: 1, // 1=指定成员, 2=全部成员
  participant: members,
  templateInfo: {
    templateId: "4A68CBB88A92B0A9311848DBA1E94A199B166463", // 完成类
    // 或 '2A84254B945674A2F88CE4970782C402795EB607' 参与类
  },
});

Disabled capabilities

Not supported in chat tool mode:

• Normal forwarding (button open-type=share)
• External jump interfaces (navigateToMiniProgram, etc.)
• Ad components (ad, ad-custom)

7. Detailed explanation of chat tool core APIs

wx.openChatTool

Open chat tool.

Parameters

Object object

Property	Type	Default value	Required	Description
url	string		Yes	Page path within the chat tool subpackage
roomid	string		No	Chat room id. If not passed, the group selection box is brought up. You can pass the opengid value of a multi-chat group, or the open_single_roomid value of a single chat group
chatType	number		No	Group chat type
success	function		No	Callback function for successful API call
fail	function		No	Callback function for failed API call
complete	function		No	Callback function for API call completion (executed whether the call succeeds or fails)

Valid values of object.chatType

Value	Description
1	WeChat contact single chat
2	WeCom contact single chat
3	Regular WeChat group chat
4	WeCom interoperable group chat

Example code

wx.openChatTool({
  url: "pages/chat/index", // 示例路径
  chatType: 1, // 微信联系人单聊
  success(res) {
    console.log("打开聊天工具成功", res);
  },
  fail(err) {
    console.error("打开聊天工具失败", err);
  },
});

wx.getApiCategory

wx.getApiCategory()

Supported starting from Base Library 2.22.1; for lower versions, perform compatibility handling。

Get the API category of the current Mini Program.

Return value

string

Current API category.

Valid values

Value	Description
default	Default category
nativeFunctionalized	Native functionality, Mini Programs opened in scenarios such as Channels live commerce, product showcase, etc.
browseOnly	Browsing only, Mini Programs opened in scenarios such as Moments snapshot pages, etc.
embedded	Embedded, Mini Programs opened through the half-screen Mini Program opening capability
chatTool	Mini Program opened by chat tool

Sample code

const apiCategory = wx.getApiCategory();
console.log(apiCategory);

wx.shareAppMessageToGroup

wx.shareAppMessageToGroup(Object object)

Supported since base library 3.7.12; lower versions require compatibility handling。

Forward a Mini Program card to a chat.

Parameters

Object object

Property	Type	Default value	Required	Description
title	string		Yes	Forward title
path	string	Current page	No	Forward path, must be a complete path starting with /, defaults to the current page
imageUrl	string	Screenshot	No	Custom image path, supports PNG and JPG, displayed image aspect ratio is 5:4, defaults to using a screenshot
success	function		No	Callback function for successful API call
fail	function		No	Callback function for failed API call
complete	function		No	Callback function for API call completion (executed whether the call succeeds or fails)

Sample code

wx.shareAppMessageToGroup({
  title: "分享标题",
  path: "/path/to/page",
  imageUrl: "",
});

wx.shareVideoToGroup

wx.shareVideoToGroup(Object object)

Share a video to a chat.

Parameters

Object object

Property	Type	Default value	Required	Description
videoPath	string		Yes	Address of the video to share, must be a local path or temporary path
thumbPath	string		No	Thumbnail path; if left blank, the first frame of the video is used
needShowEntrance	boolean	true	No	Whether the shared image message should include a Mini Program entry
entrancePath	string	''	No	Path to open the Mini Program from the Mini Program entry in the message, defaults to the chat tool launch path
success	function		No	Callback function for successful API call
fail	function		No	Callback function for failed API call
complete	function		No	Callback function for API call completion (executed whether the call succeeds or fails)

Sample code

wx.shareVideoToGroup({
  videoPath: "path/to/video.mp4",
  thumbPath: "path/to/thumb.png",
  needShowEntrance: true,
  success(res) {
    console.log("分享视频成功", res);
  },
  fail(err) {
    console.error("分享视频失败", err);
  },
});

wx.shareImageToGroup

wx.shareImageToGroup(Object object)

Share an image to a chat.

Parameters

Object object

Property	Type	Default value	Required	Description
imagePath	string		Yes	Address of the image to share, must be a local path or temporary path
needShowEntrance	boolean	true	No	Whether the shared image message should include a Mini Program entry
entrancePath	string	''	No	Path to open the Mini Program from the Mini Program entry in the message, defaults to the chat tool launch path
success	function		No	Callback function for successful API call
fail	function		No	Callback function for failed API call
complete	function		No	Callback function for the end of the API call (executed whether the call succeeds or fails)

Sample code

wx.shareImageToGroup({
  imagePath: "path/to/image.png",
  needShowEntrance: true,
  success(res) {
    console.log("分享图片成功", res);
  },
  fail(err) {
    console.error("分享图片失败", err);
  },
});

wx.shareEmojiToGroup

wx.shareEmojiToGroup(Object object)

Share an emoji to a chat.

Parameters

Object object

Property	Type	Default value	Required	Description
imagePath	string		Yes	The address of the emoji to share; must be a local path or temporary path
needShowEntrance	boolean	true	No	Whether the shared emoji message should include a Mini Program entry
entrancePath	string	''	No	The path to open the Mini Program from the message Mini Program entry; defaults to the chat tool launch path
success	function		No	Callback function for a successful API call
fail	function		No	Callback function for a failed API call
complete	function		No	Callback function for the end of the API call (executed whether the call succeeds or fails)

Sample code

wx.shareEmojiToGroup({
  imagePath: "path/to/image.png",
  needShowEntrance: true,
  success(res) {
    console.log("分享表情成功", res);
  },
  fail(err) {
    console.error("分享表情失败", err);
  },
});

wx.selectGroupMembers

wx.selectGroupMembers(Object object)

Select members from a group.

Parameters

Object object

Property	Type	Default value	Required	Description
maxSelectCount	number		No	Maximum number of selectable members
success	function		No	Callback function for a successful API call
fail	function		No	Callback function for a failed API call
complete	function		No	Callback function for the end of the API call (executed whether the call succeeds or fails)

object.success callback function

####### Parameters

######## Object res

Property	Type	Description
members	Array.	The unique identifier of the selected user in this chatroom; the same user has different ids in different chatrooms

Sample code

wx.selectGroupMembers({
  maxSelectCount: 10,
  success(res) {
    console.log("选择成员成功", res.members);
  },
  fail(err) {
    console.error("选择成员失败", err);
  },
});

wx.notifyGroupMembers

wx.notifyGroupMembers(Object object)

Send a message to remind group members.

Parameters

Object object

Property	Type	Default value	Required	Description
title	string		Yes	Text link title; the sent content will be assembled by WeChat as: the list of @-mentioned members + "Please complete:"/"Please participate:" + the text link to open the Mini Program, e.g. "@alex @cindy Please complete: team building registration statistics".
members	Array.		Yes	List of group_openid of the users to remind
entrancePath	string		Yes	Text link redirect path
type	string	complete	No	The verb to display
success	function		No	Callback function for a successful API call
fail	function		No	Callback function for a failed API call
complete	function		No	Callback function for the end of the API call (executed whether the call succeeds or fails)

Valid values for object.type

Value	Description
participate	Please participate
complete	Please complete

Sample code

wx.notifyGroupMembers({
  title: "团建报名统计",
  members: ["openid1", "openid2"],
  entrancePath: "/pages/index/index",
  type: "complete",
  success(res) {
    console.log("提醒成功", res);
  },
  fail(err) {
    console.error("提醒失败", err);
  },
});

Full documentation

See reference.md