CreateActivityRedPacket - 直播间内新增红包--企业直播-火山引擎

文档中心

立即注册

导航

CreateActivityRedPacket - 直播间内新增红包

最近更新时间：2025.03.24 16:50:59首次发布时间：2025.03.06 11:42:49

调用 CreateActivityRedPacket 接口，在指定直播间内新增红包。

注意事项

请求频率：单用户请求频率限制为 10 次/秒。
前提条件：确保您拥有火山引擎主账号或具备直播间的直播控制 > 可编辑权限的子账号。有关如何添加子账号，详见子账号管理。

请求说明

请求方式：POST
请求地址：https://livesaas.volcengineapi.com/?Action=CreateActivityRedPacket&Version=2023-08-01

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息详见公共参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`CreateActivityRedPacket`	接口名称。当前 API 的名称为 `CreateActivityRedPacket`。
Version	String	是	`2023-08-01`	接口版本。当前 API 的版本为 `2023-08-01`。

Body

参数	类型	是否必选	示例值	描述
ActivityID	Long	是	`182492****234844`	直播间 ID。您可通过调用 ListActivityAPI 接口获取 ID。说明使用子账号调用接口时，确保该直播间对子账号可见。有关如何配置子账号的可见范围，详见子账号管理。
RedPacketType	Integer	否	`0`	红包类型。默认值为 `0`。取值如下： `0`：现金红包 `1`：积分红包说明您可以进行二次开发，按照红包中奖结果，向抢到红包的观众发放积分或让观众完成现金红包提现。详见接入流程。
TotalAmount	Integer	否	`10000`	红包总金额或总积分。现金红包（`RedPacketType` 取值为 `0`）时，取值范围为 `[1,2000000]`，单位为分积分红包（`RedPacketType` 取值为 `1`）时，取值范围为 `[1,100000]`，单位可通过 `RewardsPointsUnit` 参数配置说明当 `RedPacketType` 或 `AmountCalculationType` 取值为 `0` 时，该参数必选且生效。
RewardsPointsConfig	Object of RewardsPointsConfig	否	`-`	积分红包配置。说明当 `RedPacketType` 取值为 `1` 时，该参数必选且生效。
RedPacketNumber	Integer	否	`10`	红包个数。取值范围为 `[1,2000]`。说明当 `RedPacketType` 或 `AmountCalculationType` 取值为 `0` 时，该参数必选且生效。
OpenRedPacketType	Integer	否	`0`	开奖方式。默认值为 `0`。取值如下： `0`：自动开奖 `1`：手动开奖
DeadLine	Integer	否	`5`	开奖倒计时。取值范围为 `[1,999]`，单位为分钟。默认值为 `5`。说明当 `OpenRedPacketType` 取值为 `0` 时，该参数必选且生效。
IsOpenSmsNotification	Integer	否	`0`	是否开启短信提醒。默认值为 `0`。取值如下： `0`：关闭 `1`：开启。开启后，通过手机号登录直播间的观众，在中奖时会收到企业直播发送的红包中奖提醒短信
RedPacketCoverImage	String	否	`https://www.example.com/a.png`	观看页展示的红包图标的 URL，包含协议头。不传该参数，则使用默认红包图标。
ClaimSuccessText	String	否	`恭喜你，抢到现金红包`	观众抢到红包时的提示文案。长度为 1 到 100 个字符。不传该参数，现金红包默认为恭喜你，抢到现金红包，积分红包默认为恭喜你，抢到积分红包。
ClaimFailureText	String	否	`很遗憾，您没有抢到红包`	观众未抢到红包时的提示文案。长度为 1 到 100 个字符。不传该参数，默认为很遗憾，您没有抢到红包。
AwardCondition	Object of AwardCondition	否	`-`	参与条件配置。观众只有在同时满足开启的参与条件后，才能参与抢红包。如果开启问卷、投票、签到、答题或简答参与条件，观众必须在本场直播期间完成相关活动，才能被视为有效参与。也就是说，直播间必须处于直播中状态，且活动必须在本场直播期间完成。
BarragePwd	String	否	`新年快乐`	弹幕口令。传入该参数后，将开启弹幕参与条件，观众必须发送该弹幕口令，才能参与抢红包。
RangeStatus	Integer	否	`0`	中奖条件。默认值为 `0`。取值如下： `0`：所有观众的中奖概率相同 `1`：未中奖观众优先，即加大在当前直播间 30 天未中奖观众的中奖概率 `2`：重复中奖限制
RepeatedAwardLimit	Integer	否	`1`	同一观众在当前直播间 30 天内允许中奖（包括实时抽奖和红包）的次数。取值范围为 `[1,99]`，默认值为 `1`。说明当 `RangeStatus` 取值为 `2` 时，该参数必选且生效。
VipUserInfoId	Long	否	`162****099`	优先中奖名单 ID。您可通过调用 CreateVipOrBlackListUserInfo 接口获取 ID。当优先中奖名单中的人数大于红包数量，则在优先中奖名单中随机抽奖。当红包数量大于优先中奖名单中的人数时，则优先中奖名单中的观众全部中奖且优先获得较大金额的红包，多出的红包在普通观众中随机抽奖。优先中奖名单中，已登录的观众（仅输入昵称的观众除外）无需手动参与抢红包，如果开奖时正在观看直播，即可收到中奖弹窗通知。
BlackUserInfoId	Long	否	`162****100`	中奖黑名单 ID。您可通过调用 CreateVipOrBlackListUserInfo 接口获取 ID。中奖黑名单，即无法中奖的人员名单。如果某观众被同时添加进优先中奖名单和中奖黑名单，则该观众无法中奖。
EnableCustomRedirect	Boolean	否	`true`	是否开启自定义地址提现跳转功能。默认值为 `false`。取值如下： `true`：开启。开启后，观众点击立即提现时，即可跳转至 `CustomRedirectUrl` 配置的自定义地址页面。您需自行在页面发放中奖金额并实现红包提现逻辑 `false`：关闭说明当 `EnableCustomRedirect` 和 `EnableMiniApp` 的取值均为 `true` 时，则：在移动端微信环境下，观众会跳转至微信小程序页面在其他环境下，观众会跳转至自定义地址页面
CustomRedirectUrl	String	否	`https://www.example.com`	自定义地址。长度为 1 到 500 个字符。说明当 `EnableCustomRedirect` 取值为 `true` 时，该参数必选且生效。
EnableMiniApp	Boolean	否	`true`	是否开启微信小程序提现跳转功能。默认值为 `false`。取值如下： `true`：开启。开启后，移动端观众在微信环境下点击立即提现时，即可跳转至指定微信小程序页面。您需自行在页面发放中奖金额并实现红包提现逻辑 `false`：关闭
MiniAppId	String	否	`1234****91011`	微信小程序的 App ID，跳转后的页面属于该微信小程序。长度为 1 到 100 个字符。完成以下步骤，获取 App ID。使用微信小程序账号登录微信公众平台。在左侧导航栏，选择设置。在基本设置页签下查看 App ID。说明当 `EnableMiniApp` 取值为 `true` 时，该参数必选且生效。
MiniAppRedirectUrl	String	否	`test=1`	跳转后的页面在微信小程序中的相对路径。长度为 1 到 500 个字符。说明当 `EnableMiniApp` 取值为 `true` 时，该参数必选且生效。

RewardsPointsConfig

参数	类型	是否必选	示例值	描述
AmountCalculationType	Integer	否	`0`	金额计算方式。默认值为 `0`。取值如下： `0`：随机金额 `1`：指定金额
RewardsPointsUnit	String	否	`积分`	积分单位。默认为积分。
FixedRewardPointConfigs	Array of FixedRewardPointConfigs	否	`-`	指定金额的积分红包配置。最多支持配置 6 对积分金额和红包个数的组合。说明当 `AmountCalculationType` 取值为 `1` 时，该参数必选且生效。
RewardsPointsBatch	String	否	`123214****3214123`	批次号，用于区分不同批次的积分。观众参与抢红包后，您可根据批次号和中奖金额，向抢到红包的观众发送积分。

AwardCondition

参数	类型	是否必选	示例值	描述
Questionnaire	String	否	`all`	问卷参与条件。默认为空值。取值如下：空值：不开启问卷参与条件 `all`：提交全部问卷。全部问卷指从本场直播开始至参与本次抢红包期间发送的全部问卷 `1-999`：至少提交参数值指定个数的问卷
Vote	String	否	`all`	投票参与条件。默认为空值。取值如下：空值：不开启投票参与条件 `all`：提交全部投票。全部投票指从本场直播开始至参与本次抢红包期间发送的全部投票 `1-999`：至少提交参数值指定个数的投票
CheckIn	String	否	`all`	签到参与条件。默认为空值。取值如下：空值：不开启签到参与条件 `all`：提交全部签到。全部签到指从本场直播开始至参与本次抢红包期间发送的全部签到 `1-999`：至少提交参数值指定个数的签到
Quiz	String	否	`all`	答题或简答参与条件。默认为空值。取值如下：空值：不开启答题或简答参与条件 `all`：提交全部答题或简答。全部答题或简答指从本场直播开始至参与本次抢红包期间发送的全部答题或简答 `1-999`：至少提交参数值指定个数的答题或简答
RightQuiz	String	否	`all`	答题或简答参与条件。默认为空值。取值如下：空值：不开启答题或简答参与条件 `all`：答对全部答题或简答。全部答题或简答指从本场直播开始至参与本次抢红包期间发送的全部答题或简答 `1-999`：至少答对参数值指定个数的答题或简答

FixedRewardPointConfigs

参数	类型	是否必选	示例值	描述
RewardPointAmount	Integer	是	`100`	积分金额。取值范围为 `[1,100000]`。
RewardPointNumber	Integer	是	`10`	红包个数。取值范围为 `[1,2000]`。

返回参数

参数	类型	示例值	描述
ID	Long	`182510****340169`	成功新增的红包 ID。

请求示例

POST https://livesaas.volcengineapi.com/?Action=CreateActivityRedPacket&Version=2023-08-01
{
    "TotalAmount": 10000,
    "RedPacketNumber": 10,
    "DeadLine": 5,
    "BarragePwd": "新年快乐",
    "RedPacketCoverImage": "https://www.example.com/a.png",
    "RedPacketType": 0,
    "OpenRedPacketType": 0,
    "IsOpenSmsNotification": 0,
    "RewardsPointsConfig": {
        "AmountCalculationType": 0,
        "RewardsPointsUnit": "积分",
        "FixedRewardPointConfigs": [
            {
                "RewardPointAmount": 100,
                "RewardPointNumber": 10
            }
        ],
        "RewardsPointsBatch": "123214****3214123"
    },
    "RangeStatus": 0,
    "RepeatedAwardLimit": 1,
    "AwardCondition": {
        "Quiz": "all",
        "Questionnaire": "all",
        "CheckIn": "all",
        "Vote": "all",
        "RightQuiz": "all"
    },
    "VipUserInfoId": 162****099,
    "BlackUserInfoId": 162****100,
    "ClaimSuccessText": "恭喜你，抢到现金红包",
    "ClaimFailureText": "很遗憾，您没有抢到红包",
    "EnableCustomRedirect": true,
    "CustomRedirectUrl": "https://www.example.com",
    "EnableMiniApp": true,
    "MiniAppId": "1234****91011",
    "MiniAppRedirectUrl": "test=1",
    "ActivityID": 182492****234844
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "CreateActivityRedPacket",
        "Version": "2023-08-01",
        "Service": "livesaas",
        "Region": "cn-north-1",
        "SystemTime": 1697446406
    },
    "Result": {
        "ID": 182510****340169
    }
}

错误码

访问公共错误码和错误码获取详细信息。