You need to enable JavaScript to run this app.
导航
企业直播
  • 文档首页
    • /企业直播/API 参考/直播消息回调/红包结果回调
红包结果回调
最近更新时间：2025.03.21 10:45:22首次发布时间：2023.05.29 18:05:48
我的收藏
有用
有用
无用
无用

作用

当红包开奖时，企业直播会对所设置的接口地址进行回调通知。

配置方式

将接收回调通知的接口地址提供给企业直播技术支持。

详情

设置回调的接口地址后，当红包开奖时，企业直播会将直播间 ID、红包信息、中奖观众信息等数据以 POST 方式提交给您自定义的回调接口地址。单次回调最多包含 2000 条中奖观众信息，若中奖观众信息超过该上限，企业直播将分多次发送回调消息。
请求示例如下所示：

POST /xxxxx HTTP/1.1
Header1: ...
Header2: ...
...
{
    "AccountId": "200000****",
    "ActivityId": "182565784636****",
    "ActivityName": "直播间 A",
    "EventType": "ActivityRedPacketInfoCallBack",
    "IsOpenSmsNotification": "1",
    "RedPacketNumber": "1",
    "RedPacketType": "0",
    "RedPacketUnit": "分",
    "RequestUuid": "ActivityRedPacketInfoCallBack-182574727556****",
    "RewardsPointsBatch": "",
    "Sign": "bca104f96eb3d5e37bbc07365862****",
    "SubAccountName": "admin@bytedance.com",
    "Timestamp": "1741176382",
    "TotalAmount": "100",
    "UserInfos": [
        {
            "Amount": "100",
            "ExternalId": "7898982769****",
            "Extra": "",
            "IsPriorityUser": "0",
            "NickName": "观众 A",
            "Telephone": "1803****955",
            "UserAccessIP": "fdbd:dc00:5ea1:10********",
            "UserAgent": "Windows 10",
            "UserId": "182137188140****"
        }
    ]
}

超时重试

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

参数

说明

请联系技术支持获取鉴权 AccountSecret。

参数

类型

描述

AccountId

String

账号 ID。

ActivityId

String

直播间 ID。

SubAccountName

String

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

EventType

String

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

Timestamp

String

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

Sign

String

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

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

ActivityName

String

直播间标题。

RedPacketType

String

红包类型。取值如下：

  • 0：现金红包
  • 1：积分红包

RedPacketUnit

String

红包的单位。

  • 现金红包（RedPacketType 取值为 0）时，该参数值为分
  • 积分红包（RedPacketType 取值为 1）时，该参数值为设置的积分单位

TotalAmount

String

红包总金额或总积分。

RedPacketNumber

String

红包个数。

RewardsPointsBatch

String

积分批次号。

说明

仅当积分红包（RedPacketType 取值为 1）配置了批次号时，该参数有值。

UserInfos

Array of UserRedPacketInfo

中奖观众信息列表。

RequestUuid

String

请求回调的唯一标识。

IsOpenSmsNotification

String

是否开启短信提醒功能。取值如下：

  • 0：不开启
  • 1：开启

UserRedPacketInfo

参数

类型

描述

UserId

String

用户 ID。

ExternalId

String

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

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

说明

如果您集成了观播 SDK，且 SDK 的鉴权模式为自定义模式，关联用户 ID 的取值为调用 GetSDKTokenAPI 接口时传入的 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：是

Amount

String

中奖金额。

  • 现金红包（RedPacketType 取值为 0）时，单位为分
  • 积分红包（RedPacketType 取值为 1）时，单位为设置的积分单位