入门

小程序框架

自定义组件

基础教程

能力教程

流量入口

通用能力

推广变现

经营能力

接入订阅消息能力

接入 IM 消息收发能力

识别流量来源-标记链接方式指引（视频/直播）

私域经营能力

行业能力

AI/AR 能力

性能优化

安全

接入 IM 消息收发能力
收藏
我的收藏

简介

本教程旨在帮助开发者了解如何接入抖音开放平台 IM，包括如何处理 IM 的回调事件，以及调用 IM 的 OpenAPI 向 C 端用户发送私信。

前置条件

小程序

•

小程序通过试运营期

•

开发者需要在抖音开放平台“控制台 - 设置 - 关联设置 - 抖音号管理”为小程序经营者申请小程序发送私信能力

•

开发者需要在抖音开放平台“控制台 - 开发 - 开发配置 - Webhook”为小程序配置事件回调地址，同时订阅相关事件

网站应用

•

开发者需要在抖音开放平台“控制台 - 能力管理 - 能力实验室 ”为应用申请私信 / 群管理相关能力

•

开发者需要引导用户对应用进行授权，具体步骤可以参考授权概述

•

开发者需要在抖音开放平台“控制台 - 设置 - 开发配置 - Webhooks”为应用配置事件回调地址，同时订阅相关事件

与 Webhook 相关的注意事项可以参考 Webhook 概述

接入流程

抖音开放平台 IM 的整体流程如图所示：

当 C 端用户进入 B 端用户的私信会话页，或者 C 端用户接收和回复 B 端用户的私信等场景时，抖音开放平台 IM 会向开发者配置的事件回调地址发送相关事件的通知。开发者需要合理地处理这些 Webhook 事件通知，从中解析出后续调用 OpenAPI 接口发送消息所需的必要参数取值。

解析得到所需参数取值后，开发者可以调用抖音开放平台 IM 提供的 OpenAPI 接口，将 B 端用户想要回复给 C 端用户的消息发送出去。最后，由抖音开放平台 IM 将具体的消息推送给 C 端用户。因此，开发者接入抖音开放平台 IM，首先需要处理 Webhook 事件通知，然后调用 OpenAPI 发送消息即可。

代码的目录结构及解释如下：


├── README.md
├── client.go    // 客户端初始化
├── common.go    // 常量
├── go.mod
├── go.sum
├── im_authorize_message_test.go    // 主动私信持续触达场景测试
├── im_enter_direct_msg_test.go    // 用户主动进入私信会话页场景测试
├── main.go
├── model.go    // 模型
├── send_msg.go    // 发送私信消息
└── webhook.go    // Webhook 事件处理

Webhook 事件处理

Webhook 是一种用户事件触发反向通知的机制。当小程序或应用订阅了相关事件后，一旦用户触发了特定事件，开发者就会收到相应事件的 Webhook 通知。

抖音开放平台 IM 相关能力的通用事件参数如下：

参数			类型	含义
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	会话类型
	message_type		string	消息类型
	source		string	区分发出应用
	create_time		int	消息创建时间，13位毫秒时间戳
	user_infos		list<struct>	用户基本信息，包括：昵称和头像
		open_id	string	用户 open_id
		nick_name	string	昵称
		avatar	string	头像链接

开发者需要根据所使用的编程语言，构造对应的 Webhook 事件结构体。收到具体的 Webhook 事件后，开发者需要根据事件名称（event）来决定下一步的操作。例如，当收到接收用户进入私信会话页事件（im_enter_direct_msg）时，开发者可以向进私用户主动下发问候语。同时，开发者需要保存 Webhook 事件结构体中的部分字段（会话 ID、消息 ID 等），以供后续操作使用。

消息发送

本教程提供了用户主动进入私信会话页和主动私信持续触达两个消息发送场景的示例，若开发者需要处理其他消息发送场景，可以参考发送私信消息。

进私问候语回复

现在假设一个具体场景：C 端用户主动进入 B 端用户的私信会话页后，B 端用户需要向进私的 C 端用户发送问候语。

假设开发者完成了抖音开放平台 IM 接入的前置条件，并且能够正确接收 Webhook 事件，C 端用户进私时，开发者会收到用户进入私信会话页事件（im_enter_direct_msg），具体的事件请求内容为：

{
        "event": "im_enter_direct_msg",
        "client_key": "awg2sc***",
        "msg_id": "553ef98e48e2eb804af43c2fb76b31fc5d600ffb5547***",
        "from_user_id": "328139***",
        "to_user_id": "394990***",
        "content": "{\"conversation_short_id\":\"@9VwDhOCRTcMhM22uc8ptWc791WbvOP+HMpxwrAOiL1MWa/H460zdRmYqig357zEBdsme***\",\"server_message_id\":\"@9VwDhOCRTcMhM22uc8ptWc791mzsNf6CPpB5oAOnK1UQavj/60zdRmYqig357zEB5QlC***\",\"conversation_type\":1,\"create_time\":1721982974340,\"source\":\"\",\"scene_type\":5,\"user_infos\":[{\"open_id\":\"bb227f4c-0036-4056-8428-***\",\"nick_name\":\"***\",\"avatar\":\"https://p11.douyinpic.com/aweme/720x720/aweme-avatar/***.jpeg?from=3782654143\"},{\"open_id\":\"2d3201d1-4cf2-4f01-8368-***\",\"nick_name\":\"***\",\"avatar\":\"https://p11.douyinpic.com/aweme/720x720/aweme-avatar/***.jpeg?from=3782654143\"}],\"group_info\":{}}",
        "CreateTime": 1721982974340
}

开发者收到事件后，可以通过 event 属性判断出这是一个用户进私事件，通过 client_key 属性判断具体是哪个应用，通过 from_user_id 和 to_user_id 属性获取发送方和接收方的 OpenID，以及通过解析 content 属性拿到会话 ID、消息 ID 和消息类型等信息。

得到相关信息后，开发者可以通过调用发送私信消息 OpenAPI 向进私 C 端用户发送问候语。此处本文构造一个较复杂的消息类型 —— 主动私信授权卡片，发送给进私 C 端用户，主动私信授权卡片相关字段的含义以及如何构造可以参考小程序主动私信能力概述。构造好的主动私信授权卡片如下所示：

{
        "app_info": {
                "app_id": "ttddf8ab45***"
        },
        "to_user_info": {
                "open_id": "2d3201d1-4cf2-4f01-8368-***",
                "app_id": "ttddf8ab45***"
        }
}

然后，开发者可以通过调用发送私信消息接口，将构造好的消息内容发送给 C 端用户。具体示例如下，其中 content 字段是刚刚构造的消息内容，to_user_id、msg_id、conversation_id 均为 Webhook 事件中的相应字段，scene 字段对于用户主动进入私信会话页事件为 im_enter_direct_msg。具体的对应关系以及接口的限制可以参考用户主动进入私信会话页。

{
        "content": {
                "msg_type": 12,
                "auth_private_message_card": {
                        "app_info": {
                                "app_id": "ttddf8ab45***"
                        },
                        "to_user_info": {
                                "open_id": "2d3201d1-4cf2-4f01-8368-***",
                                "app_id": "ttddf8ab45***"
                        }
                }
        },
        "to_user_id": "e8047ec6-21a3-4c59-a1b9-***",
        "msg_id": "@9VwDhOCRTcMhM22uc8ptWc791mzsOPyKMpF0qQigK1QTZ/n960zdRmYqig357zEBEXNn***",
        "conversation_id": "@9VwDhOCRTcMhM22uc8ptWc7912LhO/iCOpd3oQKlKlARZvX460zdRmYqig357zEBG5bf***",
        "scene": "im_enter_direct_msg"
}

实现的效果如下：

主动私信持续触达

当 C 端用户点击主动私信授权卡片并且向 B 端用户进行授权后，B 端用户每天可以向 C 端用户主动触达一次，此处将构造一个小程序引导卡片，相关字段可以参考创建/更新小程序引导卡片模板。构造好的小程序引导卡片内容如下：

{
        "msg_type": 10,
        "applet_card": {
                "card_template_id": "@9VwDhOCRTcMhM22uc8ptWc7+3GTvPsK4Aa9LkzCcFWtE***",
                "path": "index/index",
                "query": "{\"aaa\":\"bbb\",\"ccc\":\"ddd\"}",
                "app_id": "ttddf8ab45***"
        }
}

然后，与用户进私事件回复场景相同，开发者需要调用发送私信消息接口，将构造好的消息内容发送给 C 端用户，示例如下。此处，不需要填写 msg_id 和 conversation_id 字段，其余字段需要开发者调用相关接口构造或从之前的回调事件中提取，scene 字段填写 im_authorize_message（主动私信持续触达）。

{
        "content_list": [{
                "msg_type": 10,
                "applet_card": {
                        "card_template_id": "@9VwDhOCRTcMhM22uc8ptWc7+3GTvPsK4Aa9LkzCcFWtE***",
                        "path": "index/index",
                        "query": "{\"aaa\":\"bbb\",\"ccc\":\"ddd\"}",
                        "app_id": "ttddf8ab45***"
                }
        }],
        "to_user_id": "e8047ec6-21a3-4c59-a1b9-***",
        "scene": "im_authorize_message"
}

实现的效果如下所示：

接入 IM 消息收发能力收藏我的收藏

简介