卡券领取批量聚合回调--企业直播-火山引擎

文档中心

立即注册

企业直播

请输入

直播消息回调

卡券领取批量聚合回调

作用

当观众在观看页领取卡券时，企业直播会向您设置的回调地址发送回调消息。

配置方式

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

回调频率限制

每个卡券互动工具的回调频率限制为 5 次/秒。

详情

完成回调配置后，当观众在观看页领取卡券时，企业直播会将直播间 ID、卡券相关信息以及领取卡券的观众信息以 POST 方式提交给您设置的回调地址。如果直播间包含多个卡券互动工具，企业直播将分别发送每个卡券互动工具的回调消息。单次回调最多包含 1000 条领取卡券的观众信息，若某个卡券互动工具的领取观众信息超过该上限，企业直播将分多次发送回调消息。
请求示例如下所示：

POST /xxxxx HTTP/1.1
Header1: ...
Header2: ...
...
{
        "AccountId": "20000*****",
        "ActivityId": "182845*****86724",
        "CouponId": "18218*****41860",
        "CouponName": "卡券 A",
        "EventType": "ActivityPickupCouponBatchCallBack",
        "Id": "18287*****81612",
        "RequestUuid": "ActivityPickupCouponBatchCallBack-1828723*****4044",
        "SendTime": "1744019357",
        "Sign": "f51eb4cc55f93d****10947f909689bb",
        "SubAccountName": "admin@bytedance.com",
        "ThirdPartyId": "45535343****444444",
        "UserCouponPickInfos": [{
                "ExternalUserId": "42709****587552",
                "PickupTime": "1744019364",
                "UserId": "175155****397136",
                "UserNickName": "观众 A"
        }, {
                "ExternalUserId": "jy**hh",
                "PickupTime": "1744019365",
                "UserId": "182867****93812",
                "UserNickName": "观众 B"
        }]
}

超时重试

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

注意

由于同一直播间内，每位观众只能领取同一张卡券一次，为避免因超时重试而接收重复的回调消息，导致卡券被重复发放，建议您在商城系统向观众发放卡券前，对 ActivityId、Id 和 UserId 的参数值去重。

参数

参数	类型	说明
ActivityId	String	直播间 ID。
AccountId	String	账号 ID。
Id	String	卡券互动工具 ID。
CouponId	String	卡券 ID。
CouponName	String	卡券名称。
ThirdPartyId	String	关联卡券 ID，即您自有商城系统中的卡券 ID。通过该 ID，可将当前卡券绑定您商城系统中的卡券，方便后续卡券的发放以及在商城内的核销。
SendTime	String	卡券互动工具的发送时间。Unix 时间戳，单位为秒。
EventType	String	回调通知的事件类型，固定取值为 `ActivityPickupCouponBatchCallBack`。
UserCouponPickInfos	Array of UserCouponPickInfo	领取卡券的观众信息。
RequestUuid	String	请求回调的唯一标识。
Sign	String	校验签名。完成以下步骤，计算校验签名。按照 `AccountSecret`、`AccountId`、`ActivityId`、`CouponId`、`EventType`、`Id`、`ThirdPartyId` 的顺序，拼接对应的参数值。将拼接后的内容进行 MD5 加密生成 32 位小写字符串。说明 `AccountSecret` 的取值可通过控制台获取。详见步骤二：获取鉴权密钥。
SubAccountName	String	创建直播间的账号。参数值 `admin@bytedance.com` 表示直播间为主账号创建。

UserCouponPickInfo

参数	类型	说明
UserId	String	用户 ID，观众在企业直播的唯一标识。
ExternalUserId	String	关联用户 ID，即观众在第三方平台的唯一标识。您可以根据该 ID 识别企业自身的用户身份，以便于后续卡券的发放。观众通过不同方式登录直播间，关联用户 ID 的取值如下所示。微信：观众在企业直播微信服务号的 OpenID。企业微信：绑定企业直播的企业内部成员 OpenID。自定义：自定义登录时通过 `UserId` 传入的值。详见自定义登录。 OAuth 2.0：您自有账号系统中用户 ID 对应的字段。飞书：绑定企业直播的飞书企业成员 Open ID。手机号：观众通过手机号注册企业直播后生成的 passport_id。白名单：观众输入的白名单校验信息。说明如果您集成了观播 SDK，且 SDK 的鉴权模式为自定义模式，关联用户 ID 的取值为调用 GetSDKTokenAPI 接口时、或调用 GetActivityLoginSecret 后生成 JWT 时，传入的 `UserIdStr`（观众 ID）。
UserNickName	String	观众昵称。
PickupTime	String	卡券的领取时间。Unix 时间戳，单位为秒。

最近更新时间：2025.11.20 15:34:19

这个页面对您有帮助吗？

有用

无用