Douyin short video matrix system--Private message group chat capability upgrade

introduction

As the world's largest short video platform, Douyin's short video marketing has become an important channel for brand promotion and product sales. In order to better meet user needs and improve marketing effects, the Douyin short video matrix system has been continuously upgraded and optimized, and the enhancement of the private message group chat function has brought new breakthroughs in marketing. This article will introduce in detail the upgrade of the private message group chat capability of the Douyin short video matrix system, so that readers can understand its technical details and practical applications.

Ability Introduction

This ability is currently a capability lab capability, and there may be recycle or adjustment of the scope of capability opening. For specific capability descriptions, you can view the detailed description in the developer background console-My App-Ability Management-Ability Lab.

Private messaging and group management capabilities are the interface & data open services provided by the Douyin open platform based on the basic functions of Douyin and Douyin Express Instant Messaging. It supports business accounts in Douyin to obtain and send Douyin through authorized third-party applications Private messages, group messages, and support rich media message types, including but not limited to text, pictures, videos, message cards, etc.

scenes to be used

Successful access to the IM open capability of the Douyin open platform can help you efficiently connect users on Douyin and support the organization of related services based on session units.

1. Main scene 1: private message scene
   1. Under the condition of effective authorization, users can use the application built by the developer to realize private message management, and do a good job in customer acceptance, promotion and transformation.
      1. Supports personalized message replies, greetings, auto-reply, etc. Developers can build private message sending and receiving strategies that meet business demands, set different scripts and sending times, avoid user loss, and improve retention & transaction conversion.
      2. It supports a variety of message cards. Currently, it supports investment retention cards and mini-program guide cards. In the future, it will support more styles, template cards and authorized business components covering different demand scenarios.
      3. It supports the TikTok mini program for directing traffic through private messages, and promotes the activity of the mini program through rich mini program guide cards, and promotes revisiting, repurchasing and retention of funds.
2. Main scene 2: group chat scene
   1. Under the condition of effective authorization, users can use the application built by the developer to realize group management and group message sending, further enhancing the activity of the group.
      1. Support the creation of fan groups, the upper limit of the number of fans is higher than that of ordinary groups
      2. With the group message sending and receiving capability, the content of group messages can be flexibly managed
      3. Group owners and administrators have more operation tools: group entry review, group notification, group promotion, group fission, etc. The updated works and live broadcast content of the group owner support automatic synchronization within the group.
      4. Support more efficient group management, improve the efficiency of group building and customize parameters through the interface, and obtain group information and status in real time for targeted promotion. At the same time, it supports the group entry approval interface capability, which can meet the developer's custom group threshold setting.
3. Support efficient message operation across scenarios
   1. Card template management supports the creation, query and deletion of standardized mini-program guidance cards and retention cards and other tools, and supports cross-scenario sending.
   2. Supports identification of intended users based on interactive behavior events, through private messages/group message webhook callback events and authorized users' followed/liked events, to accumulate target user groups, fully mine clues, user intention tags and other information, and achieve refined operations (customized messages send, etc.).
4. Application example of multi-capability combination
   1. Through the mini-program guide card, more services are extended and presented in the mini-program to achieve the goals of online and offline mutual guidance/investment retention, transaction conversion, interaction, transaction conversion, customized activities, and coupon issuance.
      1. For example: the brand displays different authorized stores for users through the mini program (it can recommend nearby stores based on geographical location authority), attracts users to the store through store activities/privileges (such as offline exclusive services/discounts), and provides one-click "booking "Access to the store" function to collect user intentions; after the user arrives at the store, the "offline check-in" function can be provided, and the user can receive relevant benefits after clicking to confirm that the user has completed the conversion to the store, and the attribution ability provided by the mini program can be used to clarify the store The channel source of clues; for users who have completed purchases/high interest, they can be guided to join the brand Douyin fan group, and then send mini-program guidance cards through the fan group, and complete transaction conversion, interaction, coupon issuance and other goals through the mini-program.

Capability map

Note: For scopes that require user authorization:

1. A user can only authorize one application A; when the user authorizes the second application B, the platform will prompt the user "Authorizing B means canceling the corresponding authorization of A"
2. Authorization method: only supports web code scanning authorization
3. Obtaining Scope authorization results is not currently supported (upgrading): For scopes that require user authorization, when the developer obtains the code and calls the /oauth/access_token/ interface, the returned scope parameter will no longer include the scope; authorization (authorize), The scope parameter in the unauthorize (unauthorize) Webhook event will also not include the scope, and developers can still use the access_token to call this interface. Authorized users can view/cancel authorized IM capabilities in Settings-Account and Security-Authorization Management-Operation Authorization . The Douyin open platform will soon complete the ability of access_token to return the relevant scope.
4. Quota for interface calls: For the time being, the application for raising the quota or paying for the quota is not supported. If you have special needs, please transfer to the manual customer service/submit a non-technical work order consultation through the online consultation portal of the platform; the long-term platform will support the authorization account based on the default free quota Please pay attention to the platform announcement

Ability name	scope name	Whether the application must apply for scope permission	Whether user authorization is required	user authorization item	Ability Introduction	Introduction to Typical Usage Scenarios
Private message management	im.direct_message (Daily call limit: 10w)	yes	yes	Private message management Receive and send TikTok private messages	For Douyin operator accounts with limited conditions, they are allowed to receive and send Douyin private messages through the developer's application if authorized by them	Receiving private messages: It can receive all private messages received by the authorized Douyin account in the terminal, sent by the terminal or by each application, and supports the distinction of message type and whether the application sends it Private message reply: After the user sends a message, the developer can call this interface to help enterprise customers reply to the message Active touch: In addition, when the user enters the private message session page, it supports the initiative to send messages based on this interface
Group message management	im.group_message (Daily call limit: 10w)	yes	yes	Group message management Receive and send Douyin group chat messages	For Douyin operator accounts with limited conditions, they are allowed to receive and send Douyin fan group messages through the developer's application, subject to their authorization	Accept group chat messages: You can receive all the messages of the fan group received by the authorized Douyin account in the terminal, sent by the terminal or by various applications Group message reply: After the user sends a message, the developer can call this interface to help enterprise customers reply to the message Actively send group messages: within the scope of frequency control, support to actively send messages based on this interface
fan base management	im.group_fans.create_list (Daily call limit: 1w)	yes	yes	fan base management create groups, management group	In the case of authorization, the third-party application can provide the operator with a binding brand/employee number to create a fan group and manage the group	Group creation, review, work synchronization, live room synchronization, etc.
intended user identification	user.intention (Daily call limit: 1w)	yes	yes	Private message management Like/follow the event	With authorization, the third-party application can obtain the list of users who have interacted with the operator through IM	Callback events based on IM interaction behaviors and authorized users' likes/following events precipitate intended users, which can be used to customize information sending and interaction implementation, etc.
Message card management	im.message_card (Daily call limit: 1w)	no	yes	Message card management Create, query, delete message cards	For Douyin operator accounts with limited conditions, they are allowed to send message cards in private messages and group chat sessions through the developer's application under the condition of their authorization	Card type: This time, the capital retention card will be launched first, and more authorized business components such as group chat invitations, enterprise account phone calls, etc. will be supported in the future
Small program guide card	im.microapp_card (Daily call limit: 1w)	no	no	-	Send information with large pictures, mini programs/mini games (can be empty), titles, copywriting, etc. on the private message/group chat page, and guide users to jump to other pages in the mini program/Douyin
Private message/group message withdrawal	im.recall_message (Daily call limit: 1w)	no	yes	Message withdrawal management Withdraw private messages and group chat messages	For Douyin operator accounts with limited conditions, they are allowed to withdraw private messages/group messages sent by themselves through the developer's application under the condition of their authorization	-
Upload image tool	tool.image.upload (Daily call limit: 1w)	no	no	-	Upload image url in exchange for media_id, which can be used for private message/group message sending interface	Sending pictures in private messages/group messages: You need to upload the pictures first, get the media_id of the pictures, and then send them through the message sending interface

Access Requirement

For the operator account in Douyin to obtain and send Douyin private messages and group messages through third-party applications, the "third-party application" and "operator's Douyin account" need to meet the following conditions:

third-party usage

The entry requirements for the ability are as follows:

1. The application has entered the Douyin open platform, and it has been launched as an "official application"
2. Application type is "Mobile Application" or "Web Application"
3. 应用须为面向经营者的ToB SaaS，功能模块以“互动管理（私信/群/评论等）”为主（ToC类应用、内容创作工具类应用暂不做准入）

同时，对于实验室能力，平台保留定期对应用进行走查、回收能力的权限。可能回收能力的原因，包括不限于：

1. 接入3个月内，scope下的OpenAPI日均调用OpenID数未达到100；若应用触发能力回收条件，平台可能通过站内信触达开发者提醒，30天后若仍未达标，则进行能力回收；开发者如有特殊原因希望保留，可通过平台首页客服入口转人工客服提交工单申请
2. 发现应用绕过平台风控规则，或存在不符合抖音开放平台运营规范的行为，平台可能通知开发者同时、即刻回收相关权限

经营者抖音号

当前准入条件：小程序品牌号及员工号、认证企业号及其员工号；后续将逐步拓展能力开放的经营者范围。

特殊说明

1. 本功能是平台为开发者提供的实验室能力，平台有权利根据法律法规变更、自身业务调整等原因，修改/关闭功能，或变更功能的开放范围。
2. 若对本文档所述能力有疑问，请通过抖音开放平台首页-在线咨询提交技术工单，或键入“转人工”咨询人工客服，相关问题将流转至开放能力建设团队值班同学

接入流程

接入前准备

应用入驻

• 开发者需要入驻抖音开放平台，创建一个以消息管理为核心功能场景之一的网站应用，获取应用clientkey

接入抖音授权

• 目前消息管理相关能力仅支持web扫码授权

能力申请

开发者可在抖音开放平台“控制台-能力管理-能力实验室”中申请，具体步骤见下图：

步骤	能力申请步骤描述
1	在抖音开放平台“控制台-能力管理-能力实验室”中找到“私信/群消息管理”能力，点击“申请开通”
2	选择需要开通的功能（scopes），并填写&提交申请材料 注意事项： 私信/群消息管理能力下scopes支持同时申请多个，但最终准入为scope粒度，可能存在部分scope申请通过、部分未通过的情况；开发者如判断未通过功能必要，可重新提交材料继续申请； 申请信息及材料请务必按照规则要求完整填写&提交，若材料不完整或信息不符合要求，审核默认不通过
3	等待审核通过； 注意事项：能力上线初期，各项准入标准仍在持续完善中，申请量大且人工审核成本高，暂定审核周期在7个工作日左右，请开发者耐心等待

各能力使用步骤及规则详解

私信管理

步骤	能力使用步骤描述
1	请求用户授权抖音私信消息收发 增加授权项：开发者需要先在合适的场景及实际，引导用户进行「私信消息管理」能力的授权； 在应用内提供拉起抖音web授权页面的入口，并引导用户打开抖音，扫码完成授权； 用户账号身份校验：当开发者申请的授权项包含「私信消息管理」时，抖音会自动校验该用户账号身份是否满足授权条件；当用户账号身份不满足条件时，授权失败（后续会在redict_url中提示授权失败的scopes，需求流程中） 是否支持授权多应用：否；仅支持一个用户授权一个应用「私信消息管理」权限 用户账号身份不满足条件： 用户账号身份满足条件：
2	使用限制 场景一：默认仅支持消息回复 仅支持消息回复，需要开发者前置订阅“收到私信消息事件”，从 webhook 解析出 msg_id 字段，时效为 24小时。 仅支持消息回复，在用户未发送下一条消息前，24小时内可向用户发送 6条 消息 默认支持的消息类型：文字、图片、授权账户自己投稿的公开视频（须通过video.list.bind请求用户授权）；消息卡片须在获取「消息卡片管理 im.message_card」「小程序引导卡片 im.microapp_card」权限后，遵循相关卡片创建/审核/内容规则进行消息发送 非互关时，不支持图片和视频消息（同app内发消息），接口在文字消息基础上，额外支持了“非互关发送消息卡片”能力 最新规则以抖音 app 内发送消息为准，小程序经营身份可参考小程序平台对外公告，企业号可参考企业号/企业员工号的私信规则（可对外） 场景二：用户主动进入私信会话页 需要开发者订阅“用户进入私信会话页webhook能力”，从 webhook 解析出相关字段，同时调用本接口时 scene 字段要传 im_enter_direct_msg 在接收到用户进入私信会话页事件 30s 内，可使用该接口发送消息，单次可发最多 3条 消息，单日最多 3次，两次发送时间需间隔 1小时 以上（最新规则以抖音 app 内发送消息为准） 调用本接口时 scene 字段需传入 im_enter_direct_msg 需要开发者订阅“用户进入私信会话页webhook能力”，从 webhook 解析 conversation_short_id 字段 用户每次进入会话页触发接收用户进入会话页事件 webhook 开发者需要在接收用户进入私信会话页事件 webhook 30 秒内，调用本接口发送消息 对于每条接收用户进入会话页 webhook，开发者最多可以调用 3 次本接口，发送 3 条消息；单日最多回复 3 条 webhook （单日总计可向同一用户发送 1 - 9 条消息） 两次回复 webhook 的时间间隔需在 1 小时以上 最新规则以抖音 app 内发送消息为准
3	消息发送成功后，用户侧接收消息 消息审核&风控：消息内容会通过抖音内容审核&反作弊校验，若出现违规，则可能被自见；对用户举报、极端作弊case，可能导致抖音经营者（授权使用开发者应用的账号）账号封禁、开发者应用权限收回等处罚；因此，开发者有义务监管使用其服务的抖音用户合规使用抖音消息收发能力 App内展现：消息发送成功后，将在用户的抖音/抖音极速版app私信会话页内展现 私信会话页hint提示：

群消息管理

步骤	能力使用步骤描述
1	请求用户授权抖音群消息收发 增加授权项：开发者需要先在合适的场景及实际，引导用户进行「群消息管理」能力的授权； 在应用内提供拉起抖音web授权页面的入口，并引导用户打开抖音，扫码完成授权； 用户账号身份校验：当开发者申请的授权项包含「群消息管理」时，抖音会自动校验该用户账号身份是否满足授权条件；当用户账号身份不满足条件时，授权失败（后续会在redict_url中提示授权失败的scopes，需求流程中） 是否支持授权多应用：否；仅支持一个用户授权一个应用「群消息管理」权限 用户账号身份不满足条件： 用户账号身份满足条件：
2	接收粉丝群消息 获取方式：订阅群消息回调事件 群聊消息事件：订阅此事件可获取该授权用户创建的粉丝群内产生的所有消息
2-1	调用接口发送抖音粉丝群消息限制 默认支持的消息类型：文字、图片、授权账户自己投稿的公开视频（须通过video.list.bind请求用户授权）；消息卡片须在获取「消息卡片管理 im.message_card」「小程序引导卡片 im.microapp_card」权限后，遵循相关卡片创建/审核/内容规则进行消息发送
3	消息发送成功后 消息审核&风控：消息内容会通过抖音内容审核&反作弊校验，若出现违规，则可能被自见；对用户举报、极端作弊case，可能导致抖音经营者（授权使用开发者应用的账号）账号封禁、开发者应用权限收回等处罚 App内展现：消息发送成功后，将在用户的抖音/抖音极速版app粉丝群会话内展现 进入群聊会话页notice提示：“为提供更好的服务，群主可能使用第三方工具管理群聊信息”

消息&卡片类型使用规范

卡片类型	使用规范	样式
文本消息	建议字数<100，具体以抖音app内规则为准，接口侧无额外限制	-
图片消息	需通过tool.image.upload上传图片url换取media_id来发送；基于用户隐私&风控策略考量，当前图片消息暂不支持webhook下载，需到抖音app端查看	-
视频消息	仅支持授权账户自己投稿的公开视频（须通过video.list.bind请求用户授权）	-
小程序引导卡片 需获取im.microapp_card权限；无需用户授权	同一小程序，可以配置多张小程序引导卡片模板，调用限制为近 30 天可创建 / 更新小程序引导卡片模板 100 次 跳转能力：仅支持跳转小程序，可跳转小程序任意页面；两种实现方式： 方案一：传appid+query+path：发消息接口直接传入，无需提前生成 方案二：传schema+app_id：「schema」生成方式： 通过接口生成 Generate 在小程序界面点击右上角 ... > 分享 > 复制链接 注：平台将对小程序跳转链接合法性进行校验，不合法链接会导致消息发送失败
留资卡片 需获取im.message_card权限；需要用户授权	默认可配置字段：姓名、城市、手机号（最少选1个） 当前行业定制字段仅支持“意向车系”，其他行业暂无特定字段

接口列表

OpenAPI 列表

请求域名 抖音开放平台

产品能力	OpenAPI	描述	对应Scope权限	权限名	是否需要用户授权
私信管理	发送私信 API 接口	发送抖音私信消息	im.direct_message	私信消息管理：接收和发送抖音私信消息	是
群消息管理	发送群消息 API 接口	发送抖音群聊消息	im.group_message	Group message management: receive and send Douyin group chat messages	yes
fan base management	Query group information	Query group information	im.group_fans.create_list	You can create a fan group for your Douyin account and query group information by authorizing the app	yes
	Create a fan group	Create a fan group	im.group_fans.create_list	You can create a fan group for your Douyin account and query group information by authorizing the app	yes
	Query the user's remaining group building quota	Query the user's remaining group building quota	im.group_fans.create_list	You can create a fan group for your Douyin account and query group information by authorizing the app	yes
	Query the group application status of users in the group owner's group	Query the group application status of users in the group owner's group	im.group_fans.create_list	You can create a fan group for your Douyin account and query group information by authorizing the app	yes
intended user identification	Interactive User Record Query	Interactive User Record Query	user.intention	Intended user management	yes
Message card management	Create/update retention card	Create/update retention card	im.message_card	Message card management	yes
	Query retention card	Query retention card	im.message_card	Message card management	yes
	delete card	delete card	im.message_card	Message card management	yes
Small program guide card	Create/Update Mini Program Bootstrap Card Template	Create/modify mini program guide card template	im.microapp_card	Mini program guide card template management	no
	Query Mini Program Guidance Card Template	Query Mini Program Guidance Card Template	im.microapp_card	Mini program guide card template management	no
	Delete Mini Program Guide Card Template	Delete Mini Program Guide Card Template	im.microapp_card	Mini program guide card template management	no
Private message/group message withdrawal	Message withdrawal API interface	Withdraw private messages and group chat messages	im.recall_message	Message withdrawal management	yes
Upload image tool	upload picture	Upload image tool	tool.image.upload	upload image	no

Webhook event subscription