私信消息撤回

我的收藏

接口说明

•

该接口用于撤回私聊消息；

•

与接收私信事件配合使用，开发者应先订阅相关 webhook 事件；

使用限制

•

当前开放用户范围：认证企业号及其员工号和小程序品牌号及员工号；后续将基于抖音经营者实际诉求逐步拓展开放用户范围

•

需要申请权限在开发者后台-设置-关联设置-抖音号管理为小程序经营者申请小程序消息撤回能力，当前仅支持一个用户授权一个应用;

•

小程序通过试运营期

•

可撤回内容、时间限制与抖音端内保持一致

基本信息

名称	描述
HTTP URL	https://open.douyin.com/im/recall/msg/
HTTP Method	POST
Scope	im.recall_message
权限要求	•需要申请权限在开发者后台-设置-关联设置-抖音号管理为小程序经营者申请小程序消息撤回能力

请求头

名称	字段类型	是否必填	示例	描述
access-token	String	是		通过 BusinessToken 进行调用，示例`bus_act.1d1021d2aee3d41fee2d2adfwdf56badMFZnrhFhfWotu3Ecuiuka27L56lr`
content-type	String	是		固定值"application/json"

请求参数

Query

名称	字段类型	是否必填	示例	描述
open_id	String	是	ba253642-0590-40bc-9bdf-9a1334b94059	•小程序登录获取 •通过控制台-能力-私信和群聊-私信管理授权用户详情页中获取 •其他 OpenID 获取方式获取

Body

名称	字段类型	是否必填	示例	描述
conversation_id	String	是	@72MqHzC5kqIEgB56A10333ntucyQ/A1Wn33333Vk9xDdDQrU9MpJSYEVV6/2hKHKVaRbE67Vx7Jd6yxgnq/g==	会话 ID：来源于私信 webhook 接收私信消息事件，对应 im_send_msg 事件 content 里的 conversation_short_id 字段
conversation_type	Int32	是	1	会话类型 1- 单聊 2- 群聊
msg_id	String	是	@7211MqHzC5kqIEgB56229n1ntu80T/MxUH6Wfj32VkdzCNbYrU9MpJSYEVV6/2hKL3r7seeHSYoexQTg/Prp5A==	消息 id：来源于私信 webhook 接收私信消息事件，对应 im_send_msg 事件 content 里的 server_message_id 字段

请求示例

Bash复制
curl --location 'https://open.douyin.com/im/recall/msg/?open_id=abcd-abcd-abcd-21221' \
\
--header 'Content-Type: application/json' \
--header 'access-token: act.d2o2u8ogtuoi2io2ruio2r2' \
\
--data-raw '{
    "msg_id":"@72MqHzC522kqIEgB56229n1ntu80T/MxUH6Wfj32VkdzCNbYrU9MpJSYEVV6/2hKL3r7seeHSYoexQTg/Prp5A==",
 \
   "conversation_id":"@72MqHzC5kqIEgB56A10333ntucyQ/A1Wn33333Vk9xDdDQrU9MpJSYEVV6/2hKHKVaRbE67Vx7Jdfs6yxgnq/g==",
 \
   "conversation_type":1
}'

响应参数

Body

名称	字段类型	是否必填	示例	描述
err_msg	String	是	消息发出已超过72小时无法撤回	错误信息
err_no	Int32	是	0	错误信息
log_id	String	是	20230202192209192B1185C6C1408E4EDB	日志ID

响应示例

正常响应示例

JSON复制
{
  "err_msg": "",
  "err_no": 0,
  "log_id": "202302021924599A4FB64DA382950444C7"
}

异常响应示例

JSON复制
{
  "err_msg": "消息发出已超过时间无法撤回",
  "err_no": 28003036,
  "log_id": "20230202192209192B1185C6C1408E4EDB"
}

错误码

http状态码	错误码	错误码描述	排查建议
200	28003035	无权限撤回此条消息	检查是否有撤回消息权限
200	28003036	消息发出已超过时间无法撤回	消息发出时间超过72小时，无法撤回