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

文档中心

立即注册

导航

企业直播

卡券领取批量聚合回调

最近更新时间：2025.04.29 12:16:34首次发布时间：2025.04.29 12:16:34

作用

当观众在观看页领取卡券时，企业直播会对所设置的接口地址进行回调通知。

说明

卡券领取回调的回调消息中仅包含 1 条领取卡券的观众信息，而卡券领取批量聚合回调的回调消息中最多可以包含 1000 条领取卡券的观众信息。因此，当领取卡券的观众人数较多时，建议使用卡券领取批量聚合回调。

配置方式

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

回调频率限制

每个卡券互动工具的回调频率限制为 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 的参数值去重。

参数

说明

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

参数	类型	说明
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 位小写字符串。
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 接口时传入的 `UserIdStr`（观众 ID）。
UserNickName	String	观众昵称。
PickupTime	String	卡券的领取时间。Unix 时间戳，单位为秒。