签到参与回调--企业直播-火山引擎

文档中心

立即注册

导航

企业直播

签到参与回调

最近更新时间：2025.11.20 15:34:19首次发布时间：2025.11.05 11:00:13

作用

当观众参与签到时，企业直播会向您设置的回调地址发送回调消息。

配置方式

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

详情

完成回调配置后，当观众参与签到时，企业直播系统会将直播间 ID、签到 ID 以及用户信息以 POST 方式提交给您设置的回调地址。单次回调最多包含 1000 个观众的签到记录，若签到观众数量超过该上限，企业直播将分多次发送回调消息。回调发送可能存在延迟。
请求示例如下所示：

{
    "EventType": "UserJoinCheckinCallback",
    "RequestUuid": "ActivityAwardInfoCallBack-182572318444****",
    "Sign": "c7594afe578431086bf1c56eff54****",
    "SubAccountName": "+861803738****",
    "ActivityId": "182573526550****",
    "CheckInId": "checkIn1754478641140736",
    "UserInfos": [
        {
            "UserId": 123123,
            "ExternalId": "123123",
            "CheckInTime": 1888181823,
            "NickName": "观众",
            "Telephone": "1803738****",
            "UserAccessIP": "fdbd:dc0********",
            "UserAgent": "Windows 10"
    ]
}

超时重试

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

注意

同一直播间中，每位观众仅能参与一次签到。为防止因超时重试产生重复回调从而影响统计结果的准确性，建议您在处理回调时，根据 ActivityId、CheckinId 和 UserId 参数对回调信息去重。

参数

参数	类型	说明
ActivityId	String	直播间 ID。
CheckInId	String	签到 ID。
SubAccountName	String	创建直播间的账号。参数值 `admin@bytedance.com` 表示直播间为主账号创建。
EventType	String	回调通知的事件类型，固定取值为 `UserJoinAwardCallBack`。
Sign	String	校验签名。完成以下步骤，计算校验签名。按照 `ActivityId`、`CheckInId`、`EventType`的顺序，拼接对应的参数值。将拼接后的内容进行 MD5 加密生成 32 位小写字符串。
RequestUuid	String	请求回调的唯一标识。
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）。
NickName	String	昵称。
UserAccessIP	String	IP 地址。
UserAgent	String	终端类型。
Telephone	String	观众登录直播间时使用的手机号。
CheckInTime	String	观众签到时间。Unix 时间戳，单位为秒。