个人资料

关系能力

内容能力

互动评论

私信群聊

私信管理

群聊管理

意向用户管理

经营工具

企业号开放能力（内测结束暂不开放）

生活服务开放能力

工具能力

服务市场开放能力

小程序推广计划

联合授权

接收私信消息事件

我的收藏

概述

Webhooks 说明文档可参考：Webhooks 概述

•

Scope: im.direct_message

•

需要申请权限。

◦

新能力上线能力实验室后，经营者可在“控制台-能力管理-能力实验室”中申请。

◦

后期能力若转为正式开放能力，可在“控制台-能力管理-互动管理”中申请。

•

需要用户授权

接收私信消息事件包括事件如下:

事件名	事件介绍
im_receive_msg	接收私信，用户收到私信触发
im_send_msg	发送私信，用户发送私信触发

使用限制

图片消息和视频分享消息不返回具体 URL，需到抖音端内 APP 内查看。

事件参数

参数			类型	含义
event			string	事件名，唯一标识 •接收到的私信：im_receive_msg •发送出去的私信：im_send_msg
from_user_id			string	发送方 open_id
to_user_id			string	接收方 open_id
client_key			string	开发者唯一标识
log_id			string	事件推送 log_id ，用于抖音内部排查问题使用
content			struct	具体内容，类型：结构体
	conversation_short_id		string	会话 ID
	server_message_id		string	消息 ID
	conversation_type		int	会话类型（1：私聊）
	message_type		string	消息类型（不同类型消息参数见下方介绍） •text：文本 •image：图片 •emoji：动图表情，非动图表情为text类型 •video：视频 •retain_consult_card：留资卡片 •other：其他不同类型消息参数见下方介绍
	source		string	区分发出应用 •通过发送私信消息接口发送，会显示具体的 clientkey •通过端上主动发送，该字段默认为空
	create_time		int	消息创建时间，13位毫秒时间戳
	user_infos		list<struct>	用户基本信息，包括：昵称和头像
		open_id	string	用户 open_id
		nick_name	string	昵称
		avatar	string	头像链接

文本消息

{
  "event": "im_receive_msg",
  "client_key": "asdfavetgbvasf",
  "from_user_id": "ac6479a5-d7a6-4018-84be-c29bfc00000",
  "to_user_id": "aaa-7ae0-4399-914a-5eb1df5861ba",
  "log_id":"201120482481297091527498902AASD",
  "content": {
    "conversation_short_id": "@c29bfc000+MNggFhRkwGuX1ntuc0QfA0VnmRejrzWUBwDdDYrU9MpJSYEVV6/2hKU0il5iay8J99+0t5j3zrbA==",
    "server_message_id": "@c29bfc000+MNggFhRkwGuX1ntuc0RPc0VHKefj/yWEJ8DtjUrU9MpJSYEVV6/2hKrOcqY1gIxctCXW23v4oW/Q==",
    "conversation_type": 2,
    "create_time": 1656571939562,
    "message_type": "text",
    "text": "你好，抖音"
  }
}

参数	含义
message_type	消息类型，text
text	消息文本

表情消息

{
  "event": "im_receive_msg",
  "client_key": "asdfavetgbvasf",
  "from_user_id": "eeb0ea9b-bed4-4b70-913d-c29bfc00000",
  "to_user_id": "aaa-7ae0-4399-914a-5eb1df5861ba",
  "content": {
    "conversation_short_id": "@c29bfc000+MNggFhRkwGuX1ntucyQ/A1Wn+VfTX3Vk9xDdDQrU9MpJSYEVV6/2hK6gbUC8gjaV/y3CS18WtfMw==",
    "server_message_id": "@c29bfc000+MNggFhRkwGuX1ntuc1RPw2VXmSfjn/VE9zCtHSrU9MpJSYEVV6/2hKk8cLQDaYzbQpImhvw1Y4FQ==",
    "conversation_type": 1,
    "create_time": 1656671771668,
    "message_type": "emoji",
    "resource_type": "gif",
    "resource_width": 450,
    "resource_height": 450,
    "resource_url": ""
  }
}

参数	含义
message_type	消息类型，emoji：动图表情消息，非动图表情消息为text类型
resource_type	资源类型
resource_height	资源高度
resource_width	资源宽度
resource_url	资源链接

图片消息

{
  "event": "im_receive_msg",
  "client_key": "asdfavetgbvasf",
  "from_user_id": "ac6479a5-d7a6-4018-84be-c29bfc00000",
  "to_user_id": "8067f050-f8cf-4fa3-9357-c29bfc00000",
  "content": {
    "conversation_short_id": "@c29bfc000+MNggFhRkwGuX1ntuc0QfA0VnmRejrzWUBwDdDYrU9MpJSYEVV6/2hKU0il5iay8J99+0t5j3zrbA==",
    "server_message_id": "@c29bfc000+MNggFhRkwGuX1ntuc0RPc0VHKefj/yWEJ8DtjUrU9MpJSYEVV6/2hKrOcqY1gIxctCXW23v4oW/Q==",
    "conversation_type": 1,
    "create_time": 1656571939562,
    "message_type": "image"
  }
}

参数	含义
message_type	消息类型 •image: 通过抖开发送私信消息 OpenAPI 或其他平台发送的图片消息

视频分享消息

{
  "event": "im_receive_msg",
  "client_key": "asdfavetgbvasf",
  "from_user_id": "eeb0ea9b-bed4-4b70-913d-c29bfc00000",
  "to_user_id": "8067f050-f8cf-4fa3-9357-c29bfc00000",
  "content": {
    "conversation_short_id": "@c29bfc000+MNggFhRkwGuX1ntucyQ/A1Wn+VfTX3Vk9xDdDQrU9MpJSYEVV6/2hK6gbUC8gjaV/y3CS18WtfMw==",
    "server_message_id": "@c29bfc000+MNggFhRkwGuX1ntuc1RPw2VXmSfjn/VE9zCtHSrU9MpJSYEVV6/2hKk8cLQDaYzbQpImhvw1Y4FQ==",
    "conversation_type": 1,
    "create_time": 1656671771668,
    "message_type": "video",
    "item_id": "@72NwHyW53+MNggFhRkwGuX1ntuc2RfUyVnKfdTzwU0F0CtjUrU9MpJSYEVV6/2hKy3NMVbBhh6BW27IsDFieLg=="
  }
}

参数	含义
message_type	消息类型 •video: 视频分享消息，即用户在抖音首页相关视频点击右下角分享按钮 - 选择分享的用户 - 分享的视频消息
item_id	加密后的视频 ID

本地图片消息

{
  "event": "im_receive_msg",
  "client_key": "asdfavetgbvasf",
  "from_user_id": "ac6479a5-d7a6-4018-84be-c29bfc00000",
  "to_user_id": "8067f050-f8cf-4fa3-9357-c29bfc00000",
  "content": {
    "conversation_short_id": "@c29bfc000+MNggFhRkwGuX1ntuc0QfA0VnmRejrzWUBwDdDYrU9MpJSYEVV6/2hKU0il5iay8J99+0t5j3zrbA==",
    "server_message_id": "@c29bfc000+MNggFhRkwGuX1ntuc0RPc0VHKefj/yWEJ8DtjUrU9MpJSYEVV6/2hKrOcqY1gIxctCXW23v4oW/Q==",
    "conversation_type": 1,
    "create_time": 1723994885174,
    "message_type": "user_local_image"
  }
}

参数	含义
message_type	消息类型 •user_local_image: 用户本地图片消息，即用户在聊天框中点击右下角+号 - 选择相册 - 勾选具体需要发送的图片 - 点击发送按钮，发送给另一用户的图片消息。可以通过获取消息中的多媒体资源接口获取用户本地图片消息中的图片资源 URL

本地视频消息

{
  "event": "im_receive_msg",
  "client_key": "asdfavetgbvasf",
  "from_user_id": "eeb0ea9b-bed4-4b70-913d-c29bfc00000",
  "to_user_id": "8067f050-f8cf-4fa3-9357-c29bfc00000",
  "content": {
    "conversation_short_id": "@c29bfc000+MNggFhRkwGuX1ntucyQ/A1Wn+VfTX3Vk9xDdDQrU9MpJSYEVV6/2hK6gbUC8gjaV/y3CS18WtfMw==",
    "server_message_id": "@c29bfc000+MNggFhRkwGuX1ntuc1RPw2VXmSfjn/VE9zCtHSrU9MpJSYEVV6/2hKk8cLQDaYzbQpImhvw1Y4FQ==",
    "conversation_type": 1,
    "create_time": 1723995366187,
    "message_type": "user_local_video"
  }
}

参数	含义
message_type	消息类型 •user_local_video: 用户本地视频消息，即用户在聊天框中点击右下角 + 号 - 选择相册 - 勾选具体需要发送的视频 - 点击发送按钮，发送给另一用户的视频消息。可以通过获取消息中的多媒体资源接口获取用户本地视频消息中的视频资源 URL

留资卡片消息（包含空白态和完成态）

注：通过抖音开放平台创建/更新留资卡片接口创建的留资卡片才能收到事件回调。

空白态

{
  "event": "im_receive_msg",
  "client_key": "asdfavetgbvasf",
  "from_user_id": "ac6479a5-d7a6-4018-84be-c29bfc00000",
  "to_user_id": "8067f050-f8cf-4fa3-9357-c29bfc00000",
  "content": {
    "conversation_short_id": "@c29bfc000+MNggFhRkwGuX1ntuc0QfA0VnmRejrzWUBwDdDYrU9MpJSYEVV6/2hKU0il5iay8J99+0t5j3zrbA==",
    "server_message_id": "@c29bfc000+MNggFhRkwGuX1ntuc0RPc0VHKefj/yWEJ8DtjUrU9MpJSYEVV6/2hKrOcqY1gIxctCXW23v4oW/Q==",
    "conversation_type": 1,
    "create_time": 1656571939562,
    "message_type": "retain_consult_card",
    "card_id": "@72MqAjfymKYS1xNrB0sG4X1iidgOeMsMbUSpQwLJb3kYzJh7eXsSr5+aH2GTsvEv",
    "card_status": 1 //1:空白态；2:完成态
  }
}

完成态

{
  "event": "im_receive_msg",
  "client_key": "asdfavetgbvasf",
  "from_user_id": "ac6479a5-d7a6-4018-84be-c29bfc00000",
  "to_user_id": "8067f050-f8cf-4fa3-9357-c29bfc00000",
  "content": {
    "conversation_short_id": "@c29bfc000+MNggFhRkwGuX1ntuc0QfA0VnmRejrzWUBwDdDYrU9MpJSYEVV6/2hKU0il5iay8J99+0t5j3zrbA==",
    "server_message_id": "@c29bfc000+MNggFhRkwGuX1ntuc0RPc0VHKefj/yWEJ8DtjUrU9MpJSYEVV6/2hKrOcqY1gIxctCXW23v4oW/Q==",
    "conversation_type": 1,
    "create_time": 1656571939562,
    "message_type": "retain_consult_card",
    "card_id": "@72MqAjfymKYS1xNrB0sG4X1iidgOeMsMbUSpQwLJb3kYzJh7eXsSr5+aH2GTsvEv",
    "card_status": 2, //1:空白态；2:完成态
    "card_data": [
      {
        "label": "姓名",
        "value": "Tonality"
      },
      {
        "label": "手机号",
        "value": "12345678901"
      },
      {
        "label": "城市",
        "value": "北京市北京市海淀区"
      }
    ]
  }
}

参数	含义
message_type	消息类型，retain_consult_card：留资卡片消息

其他消息

{
  "event": "im_receive_msg",
  "client_key": "asdfavetgbvasf",
  "from_user_id": "ac6479a5-d7a6-4018-84be-c29bfc00000",
  "to_user_id": "8067f050-f8cf-4fa3-9357-c29bfc00000",
  "content": {
    "conversation_short_id": "@c29bfc000+MNggFhRkwGuX1ntuc0QfA0VnmRejrzWUBwDdDYrU9MpJSYEVV6/2hKU0il5iay8J99+0t5j3zrbA==",
    "server_message_id": "@c29bfc000+MNggFhRkwGuX1ntuc0RPc0VHKefj/yWEJ8DtjUrU9MpJSYEVV6/2hKrOcqY1gIxctCXW23v4oW/Q==",
    "conversation_type": 1,
    "create_time": 1656571939562,
    "message_type": "other",
    "text": "你收到一条新消息，请打开抖音app查看"
  }
}

参数	含义
message_type	消息类型，other：其他消息

事件参数示例

{
  "event": "im_receive_msg",
  "client_key": "asdfavetgbvasf",
  "from_user_id": "aaa-ae9b-4dbf-add1-bf67e4093fab",
  "to_user_id": "aaa-7ae0-4399-914a-5eb1df5861ba",
  "content": {
    "conversation_short_id": "@9Vxc1/yDU8sqaS+gN4koEc7912foPPiLPZVyrQmgKVQabPH460zdRmYqig357zEBMaXjKvvhvwY02ISB7llsWQ==",
    "server_message_id": "@9Vxc1/yDU8sqaS+gN4koEc7912foPPyAPpF2rgykLFgbafb560zdRmYqig357zEBmWXVPshhwyd/y/7BQpXy/w==",
    "conversation_type": 1,
    "create_time": 1681303285997,
    "message_type": "text",
    "source": "",
    "text": "捷途70",
    "user_infos": [
      {
        "open_id": "aaa-ae9b-4dbf-add1-bf67e4093fab",
        "nick_name": "刘东",
        "avatar": "https://p3.douyinpic.com/aweme/720x720/xxxxx-avatar/mosaic-legacy_3795_3047680722.jpeg?from=3782654143"
      },
      {
        "open_id": "aaa-7ae0-4399-914a-5eb1df5861ba",
        "nick_name": "毕节--捷途万丰店",
        "avatar": "https://p3.douyinpic.com/aweme/720x720/xxxxxx-avatar/tos-cn-avt-0015_6c9ae9afb4e62e2263f98809e3dc5b6a.jpeg?from=3782654143"
      }
    ]
  }
}