You need to enable JavaScript to run this app.
导航
企业直播
  • 文档首页
    • /企业直播/API 参考/直播消息回调/累计观看抽奖结果批量聚合回调
累计观看抽奖结果批量聚合回调
最近更新时间：2025.11.20 15:34:19首次发布时间：2025.08.13 11:35:16
复制全文
我的收藏
有用
有用
无用
无用

作用

当观众参与累计观看抽奖并点击开奖时，企业直播会向您设置的回调地址发送回调消息。

配置方式

完成回调配置。详见回调配置。

回调频率限制

每个抽奖规则的回调频率限制为 5 次/秒。

详情

完成回调配置后，当观众参与累计观看抽奖并点击开奖时，企业直播会将直播间 ID、奖品信息、中奖观众信息等数据以 POST 方式提交给您设置的回调接口地址。单次回调最多包含 1000 条中奖观众信息。若某份奖品的领取观众信息超过该上限，企业直播将分多次发送回调消息。
请求示例如下所示：

POST /xxxxx HTTP/1.1
Header1: ...
Header2: ...
...
{
  "AccountId": "200000****",
  "ActivityId": "182573526550****",
  "ActivityName": "直播间 A",
  "AwardItemAmounts": "",
  "TaskAwardItemId": "123*33",
  "AwardItemId": "10****",
  "AwardItemNum": "",
  "AwardItemType": "1",
  "AwardName": "奖品 A",
  "DeliveryMethod": "",
  "EventType": "ActivityTaskAwardInfoBatchCallBack",
  "RequestUuid": "ActivityTaskAwardInfoBatchCallBack-182574625960****",
  "Sign": "c5e7b0079fd02849ad1a707b9d5e****",
  "SubAccountName": "+861803738****",
  "Timestamp": "1741175437",
  "UserInfos": [
    {
      "ExternalID": "78989827691****",
      "Extra": "",
      "NickName": "观众 A",
      "Telephone": "1803738****",
      "UserAccessIP": "fdbd:dc00:************",
      "UserAgent": "Windows 10",
      "UserID": "182137188140****"
    }
  ]
}

超时重试

回调服务器在发送消息通知后，5 秒内没有收到您的服务器的响应，即认为通知失败。后续会以 5 秒为间隔继续重试 2 次。

注意

由于同一直播间的同一累计观看抽奖配置内，每位观众只能对同一抽奖规则中奖一次，为避免因超时重试而接收重复的回调消息，导致奖品被重复发放，建议您在商城系统向观众发放奖品前，对 ActivityId、 TaskAwardItemId 和 UserId 的参数值去重。

参数

参数

类型

说明

AccountId

String

账号 ID。

ActivityId

String

直播间 ID。

SubAccountName

String

创建直播间的账号。参数值 admin@bytedance.com 表示直播间为主账号创建。

EventType

String

回调通知的事件类型，固定取值为 ActivityTaskAwardInfoBatchCallBack。

Timestamp

String

发送回调请求的时间。Unix 时间戳，单位为秒。

Sign

String

校验签名。
完成以下步骤，计算校验签名。

  1. 按照 AccountSecret、AccountId、ActivityId、EventType、Timestamp 的顺序，拼接对应的参数值。
  2. 将拼接后的内容进行 MD5 加密生成 32 位小写字符串。

说明

AccountSecret 的取值可通过控制台获取。详见步骤二：获取鉴权密钥。

ActivityName

String

直播间标题。

AwardName

String

奖品名称。

UserInfos

Array of UserAwardInfo

中奖观众信息。

AwardItemNum

String

积分的奖品批次号。您可根据该批次号识别企业积分，向观众发放积分。

AwardItemAmounts

String

每位中奖观众可获得的积分数额。您可根据该中奖金额，判断向中奖观众发放多少积分。取值范围：[1, 99999]。

说明

仅当 DeliveryMethod 取值为 2 时，该参数有值。

AwardItemId

String

奖品 ID。

TaskAwardItemId

String

累计观看抽奖配置中的抽奖规则 ID，可用于去重。

RequestUuid

String

请求回调的唯一标识。

AwardItemType

String

奖品类型。取值如下：

  • 1：实物奖品
  • 2：虚拟奖品
  • 3：自定义奖品
  • 4：奖券奖品

DeliveryMethod

String

自定义奖品的分类。您可根据该分类，判断本次开奖需要发放的是积分还是卡券。取值如下：

  • 1：卡券
  • 2：积分

说明

仅当 AwardItemType 取值为 3 时，该参数有值。

UserAwardInfo

参数值

类型

描述

UserID

String

用户 ID。

ExternalID

String

关联用户 ID，即观众在第三方平台的唯一标识。
您可以根据该关联用户 ID 识别企业自身的用户身份，以便于按需实现用户洞察和进行数据分析。
观众通过不同方式登录直播间，关联用户 ID 的取值如下所示。

  • 微信：观众在企业直播微信服务号的 OpenID。
  • 企业微信：绑定企业直播的企业内部成员 OpenID。
  • 自定义：自定义登录时通过 UserId 传入的值。详见自定义登录。
  • OAuth 2.0：您自有账号系统中用户 ID 对应的字段。
  • 飞书：绑定企业直播的飞书企业成员 Open ID。
  • 手机号：观众通过手机号注册企业直播后生成的 passport_id。
  • 白名单：观众输入的白名单校验信息。

说明

如果您集成了观播 SDK，且 SDK 的鉴权模式为自定义模式，关联用户 ID 的取值为调用 GetSDKTokenAPI 接口时、或调用 GetActivityLoginSecret 后生成 JWT 时，传入的 UserIdStr（观众 ID）。

Extra

String

业务方扩展参数，对应观看页地址中的 extra 字段，例如：https://live.xxx.com/9854/1315744?extra=xxx。

NickName

String

昵称。

UserAccessIP

String

IP 地址。

UserAgent

String

终端类型。

Telephone

String

观众登录直播间时使用的手机号。