CreateVipOrBlackListUserInfo - 新增优先中奖名单或中奖黑名单用户信息--企业直播-火山引擎

文档中心

导航

企业直播

CreateVipOrBlackListUserInfo - 新增优先中奖名单或中奖黑名单用户信息

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

调用 CreateVipOrBlackListUserInfo，在指定直播间内新增优先中奖名单或中奖黑名单用户信息。新增成功后，您可以调用 CreateActivityRedPacket 或 UpdateActivityRedPacket 接口，将名单添加到指定红包中。

注意事项

请求频率：单用户请求频率限制为 10 次/秒。
使用限制：名单中的用户信息上限为 50,000 条。单次接口调用最多支持新增 2100 条用户信息。

请求说明

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

请求参数

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

Query

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

Body

参数	类型	是否必选	示例值	描述
ActivityId	Long	是	`182519****981916`	直播间 ID。您可通过调用 ListActivityAPI 接口获取 ID。
Id	Long	否	`162****124`	优先中奖名单 ID 或中奖黑名单 ID。您可调用本接口，通过返回参数的 `VipUserInfoId` 或 `BlackUserInfoId` 获取 ID。传入该参数，可以在指定名单中新增用户信息。
Role	Integer	否	`2`	创建的名单类型。取值如下： `1`：优先中奖名单 `2`：中奖黑名单说明如果未传入 `Id`，该参数必选。
AwardUserInfoList	Array of AwardUserInfoList	否	`-`	用户信息列表。说明企业直播按照以下优先级顺序匹配名单中的观众：`UserId`（用户 ID）、`UserTel`（手机号）、`UserName`（用户昵称）。例如配置了 `UserId`，则无论是否能匹配到观众，均不再按 `UserTel` 或 `UserName` 进行匹配。因此，选择其中之一配置即可。

AwardUserInfoList

参数	类型	是否必选	示例值	描述
UserId	String	否	`172739****031831`	用户 ID。长度为 1 到 20 个字符。
UserTel	String	否	`156****1234`	手机号。长度为 1 到 20 个字符。说明如果是海外地区或中国香港、中国澳门、中国台湾地区的手机号，请按照以下格式：“+” + 国际电话区号 + 手机号，例如 +1XXXXXXXXXX 为北美手机号。
UserName	String	否	`观众 A`	昵称。长度为 1 到 60 个字符。说明如果在优先中奖名单中仅配置了昵称，且该昵称在当前直播间的观众中并非唯一，则会从昵称相同的观众中随机抽奖。如果在中奖黑名单中仅配置了昵称，且该昵称在当前直播间的观众中并非唯一，则昵称相同的所有观众均无法中奖。

返回参数

参数	类型	示例值	描述
VipUserInfoId	Long	`0`	优先中奖名单 ID。
BlackUserInfoId	Long	`162****124`	中奖黑名单 ID。
ErrorUserList	Object of ErrorUserList	`-`	新增失败的用户信息列表。说明该参数无值，则表示所有用户信息新增成功。

ErrorUserList

参数	类型	示例值	描述
UserId	String	`172739****031831`	用户 ID。
UserName	String	`观众 A`	昵称。
UserTel	String	`156****1234`	手机号。
ErrorReason	String	`用户ID重复`	用户信息新增失败的原因。取值如下： `名单字段均为空`：`UserId`、`UserName` 和 `UserTel` 均未传入，请至少传入其中之一 `用户昵称长度超过60个字符`：传入的 `UserName` 字符长度超过上限，请修改参数取值 `用户id长度超过20个字符`：传入的 `UserId` 字符长度超过上限，请修改参数取值 `用户手机号长度超过20个字符`：传入的 `UserTel` 字符长度超过上限，请修改参数取值 `用户id非法`：传入的 `UserId` 取值非正整数，请修改参数取值 `用户ID重复`：传入的 `UserId` 取值在名单中已存在，请修改参数取值 `用户手机号重复`：传入的 `UserTel` 取值在名单中已存在，请修改参数取值 `用户昵称重复`：传入的 `UserName` 取值在名单中已存在，请修改参数取值

请求示例

POST https://livesaas.volcengineapi.com/?Action=CreateVipOrBlackListUserInfo&Version=2023-08-01
{
    "AwardUserInfoList": [
        {
            "UserName": "观众 A",
            "UserTel": "156****1234",
            "UserId": "172739****031831"
        }
    ],
    "ActivityId": 182519****981916,
    "Role": 2,
    "Id": 162****124
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "CreateVipOrBlackListUserInfo",
        "Version": "2023-08-01",
        "Service": "livesaas",
        "Region": "cn-north-1",
        "SystemTime": 1697446406
    },
    "Result": {
        "ErrorUserList": {
            "UserId": "",
            "UserName": "",
            "UserTel": "",
            "ErrorReason": ""
        },
        "VipUserInfoId": 0,
        "BlackUserInfoId": 162****124
    }
}

错误码

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