基础能力

触达与营销

订阅消息

分发

搜索能力

私信和群聊

私信管理

群聊管理

经营工具

私域经营常见问题

挂载

支付

运营

生活服务

垂直行业

其它

查询授权主动私信用户

我的收藏

使用限制

•

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

•

小程序通过试运营期

接口说明

•

该接口用于查询授权服务账号主动私信的所有 C 端用户列表，会返回调用应用对应的 OpenID

•

有关小程序主动私信能力，详见小程序主动私信能力概述

•

关于分页方式的说明

◦

分页方式一

使用 page_num x page_size 参数进行分页，返回结果将根据授权更新时间，由近至远排序返回

page_num x page_size 最多能获取 5w 条数据

◦

分页方式二

使用 cursor x limit 方式进行分页，返回结果将根据首次授权时间，由远至近排序返回

cursor x limit 无获取数据限制

基本信息

名称	描述
HTTP URL	https://open.douyin.com/im/authorize/user_list/
HTTP Method	POST
Scope	im.direct_message
权限要求	•需要申请权限在开发者后台-设置-关联设置-抖音号管理为小程序经营者申请小程序发送私信能力

请求头

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

请求参数

Query

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

Body

名称	字段类型	是否必填	示例	描述
cursor	String	否		分页方式二必传游标，初次查询传 0 即可，后续查询使用 resp 中的 next_cursor 参数
limit	Int64	否		分页方式二必传每次查询数量，不能大于 100
page_num	Int64	否	1	分页方式一必传页码，page_size * page_num 需小于 50000
page_size	Int64	否	10	分页方式一必传每页数量，不能大于 50

请求示例

curl -X  POST 'https://open.douyin.com/im/authorize/user_list/?open_id=aa-aa-aa' \
-H 'Content-Type:application/json' \
  --data '{
    "page_size":10,
    "page_num":2
}' \
\

响应参数

Body

名称			字段类型	是否必填	示例	描述
err_msg			String	是
err_no			Int32	是
log_id			String	是
data			Struct	否
auth_user_list			List<Struct>	否
	enter_from	enter_from	String	是		授权来源 •micro_app 小程序button组件 •im_card 服务私信授权卡片 •action_bar 会话页快捷入口 •live_shelf_panel 直播间货架入口 •micro_app_pendant 小程序内免研悬浮组件 •mp_follow_account 小程序内关注后拉起主动私信授权
	attribution		Struct	否		授权归因，不同的授权来源对应不同的归因字段
		anchor_id	String	否	ba253642-0590-40bc-9bdf-9a1334b94059	主播id
		author_id	String	否	ba253642-0590-40bc-9bdf-9a1334b94059	作者id
		conversation_id	String	否	@8hxdhauTCMppanGnM4ltGM780mDqPP+KPpR0qQOmLVAXb/T060zdRmYqig357zEBq6CZRp4NVe6qLIJW/V/x1w==	群聊id
		from_att_uid	String	否	ba253642-0590-40bc-9bdf-9a1334b94059	消息发送者id
		group_id	String	否	@8hxdhauTCMppanGnM4ltGM780mDqPP+KPpR0qQOmLVAXb/T060zdRmYqig357zEBq6CZRp4NVe6qLIJW/V/x1w==	群id
		message_id	String	否	@8hxdhauTCMppanGnM4ltGM780mDqPP+KPpR0qQOmLVAXb/T060zdRmYqig357zEBq6CZRp4NVe6qLIJW/V/x1w==	消息id
		room_id	String	否	123456	直播房间id
		auth_user_source_app_id	String	否	tt2e995824b1a72e1201	C 端用户授权来源小程序
		data_im_extra	String	否	uehjgdwbedjnbve	开发者在主动私信授权组件中自定义参数
		path	String	否	page/componentTpl/hebxkjehh?cptName=button	用户在获取用户私信授权组件授权服务账号所在小程序当前页面的path参数
		query	String	否	uehjgdwbedjnbve	用户在获取用户私信授权组件中授权服务账号所在小程序当前页面的query参数
		target_open_id	String	否	ba253642-0590-40bc-9bdf-9a1334b94059	使用调用应用加密的 open_id
has_more			Bool	否		分页方式一、二均会返回此字段，是否还有后续数据
next_cursor			String	否		分页方式二会返回此字段，下次查询使用的游标

响应示例

正常示例

{
  "data": {
    "auth_user_list": [
      {
        "auth_user_source_app_id": "ttfa3965001",
        "target_open_id": "_000FnVpk1_9MMOGOTvzFqPoQCxmyooIfgaC".
        "enter_from": "im_card",
        "attribution": {
            "room_id": "1234567"
        },
        "data_im_extra":"micro_app",
        "query":"cptName=button",
        "path":"page/componentTpl/componentTpl\"
      },
      {
        "target_open_id": "_000LMpVKP67ggHu4Y0OO5JwQKAqkC6j0_li",
        "auth_user_source_app_id": "ttfa3965001",
        "enter_from": "micro_app",
        "data_im_extra":"micro_app",
        "query":"cptName=button",
        "path":"page/componentTpl/componentTpl\"
      },
      {
        "auth_user_source_app_id": "ttfa3965001",
        "target_open_id": "_0002cdMxHCrp1JcWzRtI3GDb5J-Ins4JnCS",
        "enter_from": "micro_app",
        "attribution": {
            "from_att_uid": "_000LMpVKP67ggHu4Y0OO5JwQKAqkC6j0_li"
        },
        "data_im_extra":"micro_app",
        "query":"cptName=button",
        "path":"page/componentTpl/componentTpl\"
      }
    ],
    "has_more": true
  },
  "err_msg": "",
  "err_no": 0,
  "log_id": "02169835083298800000000000000000000ffff0a9c251a9d7709"
}

异常示例

{
  "err_no": 28001008,
  "err_msg": "access_token过期,请刷新或重新授权",
  "log_id": "02169835067775200000000000000000000ffff0a9b3f2c9eaa18"
}

错误码

HTTP 状态码	错误码	错误码描述	排查建议
200	28001005	系统内部错误，请重试	请求重试，若依然无解请向平台提交反馈
200	28001003	access_token无效	重新请求生成access_token
200	28001008	access_token过期,请刷新或重新授权	重新请求生成access_token
200	28001016	当前应用已被封禁或下线	clientKey被封禁或者下线
200	28001006	网络调用错误，请重试	重试即可
200	28001014	应用未授权任何能力	确认应用是否授权能力
200	28001018	应用未获得该能力	开通相关能力
200	28003017	quota已用完	联系平台处理
200	28001019	应用该能力已被封禁	该能力被封禁，联系平台处理
200	28001007	参数不合法	根据错误信息检查请求参数是否填写正常

查询授权主动私信用户在线调试

使用限制

接口说明

基本信息

请求头

请求参数

Query

Body

请求示例

响应参数

Body

响应示例

正常示例

异常示例

错误码

查询授权主动私信用户