You need to enable JavaScript to run this app.
导航
企业直播
  • 文档首页
    • /企业直播/API 参考/营销与互动/ListActivityRedPacket - 获取直播间内红包列表
ListActivityRedPacket - 获取直播间内红包列表
最近更新时间：2025.03.24 16:51:00首次发布时间：2025.03.06 11:42:49
我的收藏
有用
有用
无用
无用

调用 ListActivityRedPacket，获取指定直播间内的红包列表，包括红包 ID、状态、类型、个数、参与条件等信息。

注意事项

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

请求说明

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

请求参数

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

Query

参数类型是否必选示例值描述
ActionString是ListActivityRedPacket接口名称。当前 API 的名称为 ListActivityRedPacket。
VersionString是2023-08-01接口版本。当前 API 的版本为 2023-08-01。

ActivityID

Long

是

182492****234844

直播间 ID。您可通过调用 ListActivityAPI 接口获取 ID。

说明

使用子账号调用接口时，确保该直播间对子账号可见。有关如何配置子账号的可见范围，详见子账号管理。

PageItemCountInteger否10分页查询数量。默认值为 10。取值范围为 [1,500]。
PageNoInteger否1分页查询页码。默认值为 1。取值大于等于 1。

返回参数

参数类型示例值描述
PageItemCountInteger10分页查询数量。
PageNoInteger1分页查询页码。
TotalCountLong1查询结果总数。
RedPacketListArray of RedPacketList-红包列表。

RedPacketList

参数类型示例值描述
ActivityIDLong182492****234844直播间 ID。
RedPacketIDLong182509****702096红包 ID。

RedPacketStatus

Integer

0

红包状态。取值如下：

  • 0：初始化
  • 1：已发送
  • 2：开奖中
  • 3：开奖成功
  • 4：开奖失败

RedPacketType

Integer

0

红包类型。取值如下：

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

说明

您可以进行二次开发，按照红包中奖结果，向抢到红包的观众发放积分或让观众完成现金红包提现。详见接入流程。

TotalAmount

Integer

10000

红包总金额或总积分。

  • 现金红包（RedPacketType 取值为 0）时，单位为分
  • 积分红包（RedPacketType 取值为 1）时，单位可通过 RewardsPointsUnit 参数获取

RewardsPointsConfig

Object of RewardsPointsConfig

-

积分红包配置。

说明

该参数仅在 RedPacketType 取值为 1 时生效。

RedPacketNumber

Integer

10

红包个数。

说明

该参数仅在 RedPacketType 或 AmountCalculationType 取值为 0 时生效。

OpenRedPacketType

Integer

0

开奖方式。取值如下：

  • 0：自动开奖
  • 1：手动开奖

DeadLine

Integer

5

开奖倒计时。单位为分钟。

说明

该参数仅在 OpenRedPacketType 取值为 0 时生效。

IsOpenSmsNotification

Integer

1

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

  • 0：关闭
  • 1：开启。开启后，通过手机号登录直播间的观众，在中奖时会收到企业直播发送的红包中奖提醒短信

RedPacketCoverImage

String

https://www.example.com/a.png

观看页展示的红包图标的 URL。
如果图标是通过控制台配置的，则 URL 无协议头，如果图标是通过 API 调用配置的，则 URL 有协议头。

ClaimSuccessTextString恭喜你，抢到积分红包，请联系主办方领取观众抢到红包时的提示文案。
ClaimFailureTextString很遗憾，您没有抢到红包观众未抢到红包时的提示文案。

AwardCondition

Object of AwardCondition

-

参与条件配置。
观众只有在同时满足开启的参与条件后，才能参与抢红包。
如果开启问卷、投票、签到、答题或简答参与条件，观众必须在本场直播期间完成相关活动，才能被视为有效参与。也就是说，直播间必须处于直播中状态，且活动必须在本场直播期间完成。

BarragePwd

String

新年快乐

弹幕口令。
该参数有值，则表示开启弹幕参与条件，观众必须发送该弹幕口令，才能参与抢红包。

RangeStatus

Integer

0

中奖条件。取值如下：

  • 0：所有观众的中奖概率相同
  • 1：未中奖观众优先，即加大在当前直播间 30 天未中奖观众的中奖概率
  • 2：重复中奖限制

RepeatedAwardLimit

Integer

1

同一观众在当前直播间 30 天内允许中奖（包括实时抽奖和红包）的次数。

说明

该参数仅在 RangeStatus 取值为 2 时生效。

VipUserInfoId

Long

162****099

优先中奖名单 ID。您可调用 GetVipOrBlackListUserInfo 接口，通过传入直播间 ID 和优先中奖名单 ID，获取名单中的用户信息。
当优先中奖名单中的人数大于红包数量，则在优先中奖名单中随机抽奖。当红包数量大于优先中奖名单中的人数时，则优先中奖名单中的观众全部中奖且优先获得较大金额的红包，多出的红包在普通观众中随机抽奖。优先中奖名单中，已登录的观众（仅输入昵称的观众除外）无需手动参与抢红包，如果开奖时正在观看直播，即可收到中奖弹窗通知。

BlackUserInfoId

Long

162****100

中奖黑名单 ID。您可调用 GetVipOrBlackListUserInfo 接口，通过传入直播间 ID 和中奖黑名单 ID，获取名单中的用户信息。
中奖黑名单，即无法中奖的人员名单。如果某观众被同时添加进优先中奖名单和中奖黑名单，则该观众无法中奖。

EnableCustomRedirect

Boolean

false

是否开启自定义地址提现跳转功能。取值如下：

  • true：开启。开启后，观众点击立即提现时，即可跳转至 CustomRedirectUrl 配置的自定义地址页面。您需自行在页面发放中奖金额并实现红包提现逻辑
  • false：关闭

说明

当 EnableCustomRedirect 和 EnableMiniApp 的取值均为 true 时，则：

  • 在移动端微信环境下，观众会跳转至微信小程序页面
  • 在其他环境下，观众会跳转至自定义地址页面

CustomRedirectUrl

String

https://www.example.com

自定义地址。

说明

该参数仅在 EnableCustomRedirect 取值为 true 时生效。

EnableMiniApp

Boolean

false

是否开启微信小程序提现跳转功能。取值如下：

  • true：开启。开启后，移动端观众在微信环境下点击立即提现时，即可跳转至指定微信小程序页面。您需自行在页面发放中奖金额并实现红包提现逻辑
  • false：关闭

MiniAppId

String

1234****91011

微信小程序的 App ID，跳转后的页面属于该微信小程序。

说明

该参数仅在 EnableMiniApp 取值为 true 时生效。

MiniAppRedirectUrl

String

test=1

跳转后的页面在微信小程序中的相对路径。

说明

该参数仅在 EnableMiniApp 取值为 true 时生效。

RewardsPointsConfig

参数类型示例值描述

AmountCalculationType

Integer

1

金额计算方式。取值如下：

  • 0：随机金额
  • 1：指定金额
RewardsPointsUnitString积分积分单位。

FixedRewardPointConfigs

Array of FixedRewardPointConfigs

-

指定金额的积分红包配置。

说明

该参数仅在 AmountCalculationType 取值为 1 时生效。

RewardsPointsBatchString123214****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

参数类型示例值描述
RewardPointAmountInteger100积分金额。
RewardPointNumberInteger10红包个数。

请求示例

GET https://livesaas.volcengineapi.com/?Action=ListActivityRedPacket&Version=2023-08-01&ActivityID=182492****234844&PageItemCount=10&PageNo=1

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "ListActivityRedPacket",
        "Version": "2023-08-01",
        "Service": "livesaas",
        "Region": "cn-north-1",
        "SystemTime": 1697446406
    },
    "Result": {
        "RedPacketList": [
            {
                "TotalAmount": 10000,
                "RedPacketNumber": 10,
                "BarragePwd": "新年快乐",
                "DeadLine": 5,
                "ActivityID": 182492****234844,
                "RedPacketID": 182509****702096,
                "RedPacketStatus": 0,
                "RedPacketCoverImage": "https://www.example.com/a.png",
                "RedPacketType": 0,
                "OpenRedPacketType": 0,
                "IsOpenSmsNotification": 1,
                "RewardsPointsConfig": {
                    "AmountCalculationType": 1,
                    "RewardsPointsUnit": "积分",
                    "FixedRewardPointConfigs": [
                        {
                            "RewardPointAmount": 100,
                            "RewardPointNumber": 10
                        }
                    ],
                    "RewardsPointsBatch": "123214****3214123"
                },
                "RangeStatus": 0,
                "AwardCondition": {
                    "Quiz": "all",
                    "Questionnaire": "all",
                    "CheckIn": "all",
                    "Vote": "all",
                    "RightQuiz": "all"
                },
                "VipUserInfoId": 162****099,
                "BlackUserInfoId": 162****100,
                "RepeatedAwardLimit": 1,
                "ClaimSuccessText": "恭喜你，抢到积分红包，请联系主办方领取",
                "ClaimFailureText": "很遗憾，您没有抢到红包",
                "EnableCustomRedirect": false,
                "CustomRedirectUrl": "https://www.example.com",
                "EnableMiniApp": false,
                "MiniAppId": "1234****91011",
                "MiniAppRedirectUrl": "test=1"
            }
        ],
        "PageItemCount": 10,
        "PageNo": 1,
        "TotalCount": 1
    }
}

错误码

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