提交工单
咨询集成、功能及报价等问题
调用此接口触发弹幕游戏内的送礼事件,会在弹幕游戏客户端产生相应的效果。
以下请求参数列表仅列出了接口请求参数,公共参数列表请参考 调用方式 - 公共请求参数。
参数 | 类型 | 是否必选 | 描述 |
---|---|---|---|
RoomId |
String |
是 |
房间 ID,由您定义,长度上限为 64 字符。 |
MiniGameId |
String |
是 |
游戏 ID,请联系 ZEGO 技术支持获取。 |
GiftList |
Array of Object |
是 |
整合后的送礼列表。 |
UserInfo |
Object |
是 |
用户信息对象。 |
UserId |
String |
是 |
参与游戏的用户 ID,由您定义,长度上限为 48 字符,只允许数字和英文。
|
Nickname |
String |
是 |
用户昵称,由您定义,长度上限为 32 字符。 |
Avatar |
String |
是 |
用户头像的地址,必须是有效的 HTTP/HTTPS 地址,且长度在 1024 字节以内。 |
Sex |
Number |
否 |
用户性别。
|
GiftInfo |
Object |
是 |
送礼信息对象。 |
GiftId |
String |
是 |
礼物 ID。具体礼物 ID,请联系 ZEGO 技术支持。 |
Value |
Number |
否 |
单个效果所需的礼物数量。 非必填,仅当礼物 ID 需要因一次性送出的礼物数量(Value)不同而触发不同效果时,才为必填。 具体数量与效果的关系,请联系 ZEGO 技术支持进行约定,若未约定则为 1。 用户不能随意送出任意份数的礼物,需要按照游戏规则提前约定的枚举值,送出指定数目的礼物。 例如,当游戏规定 5 份礼物 A,才能召唤一个士兵,则用户送礼时,Value 应该为 5 |
Num |
Number |
是 |
所需游戏效果份数。
Giftid + Value 对应的触发游戏效果,为提前约定的游戏规则,与具体游戏相关。GiftId、Value 和 Num 的传入说明请见 下文。 |
ReceiverId |
String |
否 |
接收礼物用户 ID。当多主播同房间 PK 时,需要此数据,便于记录。 |
Timestamp |
Number |
是 |
送礼事件发生时的 Unix 时间戳,单位为 ms。 |
MsgId |
String |
是 |
送礼消息 ID,由您生成,表示单次送礼的消息记录 ID,用于保证礼物消费幂等以及查询送礼结果,需保至少 24 小时内唯一。24 小时内使用重复的 MsgId 会返回第一次的送礼结果,不会重复赠送。长度上限为 64 字符,支持数字、英文和 '_','-'。 |
Num(游戏效果份数)与 GiftID(礼物)和 Value(每份效果所需礼物份数)有关,且受具体游戏规则影响,详情请联系 ZEGO 技术支持。
例如:游戏 A 规定:
游戏过程中可能有以下几种情况:
当观众希望送出 20 个“火箭”在游戏中出两个小兵,则此时传入的 GiftInfo
数值为:
"GiftInfo": {
"GiftId": "g1",
"Value": 10,
"Num": 2
}
当观众希望送出 66 个火箭在游戏中出一个大将,则此时传入的数值为:
"GiftInfo": {
"GiftId": "g1",
"Value": 66,
"Num": 1
}
若开发者的数值与 ZEGO 技术支持约定的不符,则此时会返回错误信息,因为与约定的游戏规则不符。
"GiftInfo": {
"GiftId": "g1",
"Value":30, // 30 不等于 10 或 66
"Num": 1
}
请求 URL
https://mini-game-api.zego.im/?Action=SendDanmakuGifts
&<公共请求参数>
请求消息体
{
"RoomId": "room123",
"MiniGameId": "TinyLoveWar",
"GiftList": [
{
"UserInfo": {
"UserId": "user1",
"Nickname": "test1",
"Avatar": "http://",
"Sex": 1
},
"GiftInfo": {
"GiftId": "g1",
"Value": 5,
"Num": 2
},
"Timestamp": 12312312,
"ReceiverId":"anchor111",
"MsgId":"445623452643416236"
}
]
}
参数 | 类型 | 描述 |
---|---|---|
Code |
Int64 |
错误码。 |
Message |
String |
请求结果的说明信息。 |
RequestId |
String |
请求 ID。 |
Data |
Object |
返回的具体信息。 |
Results |
Array of Object |
礼物弹幕处理结果列表。 |
Result |
Number |
处理结果。0 表示成功,其余为失败。 |
Msg |
String |
失败原因。 |
MsgId |
String |
处理结果对应的礼物唯一 MsgId。 |
送礼失败分为两种情况:
{
"Code": 0,
"Message": "succeed",
"RequestId": "abcd123",
"Data": {
"Results": [
{
"Result": 0,
"Msg": "success",
"MsgId":"445623452643416236"
}
]
}
}
以下仅列出了接口业务逻辑相关的返回码,完整返回码请参考 全局返回码。
返回码 | 描述说明 | 处理建议 |
---|---|---|
7202001 |
游戏未找到,可能造成的原因包含:
|
|
7202002 |
MiniGameId 格式错误。 |
请确认格式是否为 String。 |
7206001 |
游戏未开始。 |
请确认游戏开始后再送礼。 |
返回码 | 描述说明 | 处理建议 |
---|---|---|
10003 |
送礼失败,可能造成的原因包含:
|
请联系 ZEGO 技术人员排查问题。 |
10004 |
未配置对应礼物。 |
请确认礼物是否已配置。 |
10005 |
送礼异常。 |
请联系 ZEGO 技术支持排查问题。 |
10006 |
MsgId 对应的送礼请求正在处理中。 |
请稍后重试。 |
联系我们
文档反馈