You need to enable JavaScript to run this app.
导航
企业直播
  • 文档首页
    • /企业直播/API 参考/直播消息回调/实时抽奖结果回调
实时抽奖结果回调
最近更新时间：2025.11.20 15:34:19首次发布时间：2022.11.22 11:12:49
复制全文
我的收藏
有用
有用
无用
无用

作用

当实时抽奖开奖时，企业直播会向您设置的回调地址发送回调消息。

配置方式

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

详情

完成回调配置后，当实时抽奖开奖时，企业直播会将直播间 ID、奖品信息、中奖观众信息等数据以 POST 方式提交给您设置的回调地址。如果实时抽奖中包含多个奖品，企业直播将分别发送每个奖品的回调消息。单次回调最多包含 2000 条中奖观众信息，若某个奖品的中奖观众信息超过该上限，企业直播将分多次发送回调消息。
请求示例如下所示：

POST /xxxxx HTTP/1.1
Header1: ...
Header2: ...
...
{
    "AccountID": "200000****",
    "ActivityID": "182573526550****",
    "ActivityName": "直播间 A",
    "AwardId": "162209****",
    "AwardItemAmounts": "",
    "AwardItemId": "10****",
    "AwardItemNum": "",
    "AwardItemType": "2",
    "AwardName": "奖品 A",
    "DeliveryMethod": "",
    "EventType": "ActivityAwardInfoCallBack",
    "Name": "1",
    "RequestUuid": "ActivityAwardInfoCallBack-182572318444****",
    "Sign": "c7594afe578431086bf1c56eff54****",
    "SubAccountName": "+861803738****",
    "Timestamp": "1741158904",
    "UserInfos": [
        {
            "ExternalID": "78989827691****",
            "Extra": "",
            "IsPriorityUser": "0",
            "NickName": "观众 A",
            "Telephone": "1803738****",
            "UserAccessIP": "fdbd:dc0********",
            "UserAgent": "Windows 10",
            "UserID": "182137188********"
        }
    ]
}

超时重试

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

参数

参数

类型

说明

AccountID

String

账号 ID。

ActivityID

String

直播间 ID。

SubAccountName

String

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

EventType

String

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

Timestamp

String

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

Sign

String

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

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

说明

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

ActivityName

String

直播间标题。

AwardId

String

抽奖 ID。

Name

String

抽奖名称。

AwardItemId

String

奖品 ID。

RequestUuid

String

请求回调的唯一标识。

AwardName

String

奖品名称。

AwardItemType

String

奖品类型。取值如下：

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

DeliveryMethod

String

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

  • 1：卡券
  • 2：积分

说明

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

AwardItemNum

String

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

AwardItemAmounts

String

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

说明

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

UserInfos

Array of UserAwardInfo

中奖观众信息。

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

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

IsPriorityUser

String

是否为优先中奖用户。取值如下：

  • 0：否
  • 1：是