文档中心
小游戏平台
服务端 API
弹幕游戏相关
发送礼物

发送礼物

更新时间：2025-04-15 19:16

描述

调用此接口触发弹幕游戏内的送礼事件，会在弹幕游戏客户端产生相应的效果。

送礼事件需要在用户加入游戏之后才能进行，如用户送礼行为发生时未加入游戏，则送礼失败（极少部分游戏有特殊情况，可联系技术支持确定）。
请以房间的维度，合并用户的礼物消息，再请求至此接口，建议每 50-200 ms 整合一次用户的送礼消息。

接口原型

请求方法：POST
请求地址：https://mini-game-api.zego.im/?Action=SendDanmakuGifts
传输协议：HTTPS
调用频率限制：20 次/秒（以房间为维度）

请求参数

以下请求参数列表仅列出了接口请求参数，公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
RoomId	String	是	房间 ID，由您定义，长度上限为 64 字符。
MiniGameId	String	是	游戏 ID，请联系 ZEGO 技术支持获取。
GiftList	Array of Object	是	整合后的送礼列表。
UserInfo	Object	是	用户信息对象。
UserId	String	是	参与游戏的用户 ID，由您定义，长度上限为 48 字符，只允许数字和英文。请保证 UserId 在相同的 appID 下全局唯一。如果您业务的账号系统中的用户 ID 采用了其他规则，请自行实现映射。
Nickname	String	是	用户昵称，由您定义，长度上限为 32 字符。
Avatar	String	是	用户头像的地址，必须是有效的 HTTP/HTTPS 地址，且长度在 1024 字节以内。
Sex	Number	否	用户性别。 1：男。 2：女。
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 字符，支持数字、英文和 '_'，'-'。

GiftId、Value 和 Num 的传入说明

Num（游戏效果份数）与 GiftID（礼物）和 Value（每份效果所需礼物份数）有关，且受具体游戏规则影响，详情请联系 ZEGO 技术支持。

例如：游戏 A 规定：

“火箭”（礼物）的 GiftId 为 g1。
一次性发送 10 个 “火箭”，即可在游戏中召唤一个“小兵”（效果）。
一次性发送 66 个“火箭”，即可在游戏中召唤一个“大将”（效果）。

游戏过程中可能有以下几种情况：

当观众希望送出 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，则全部礼物赠送失败，MsgId 不会被记录，可直接重试，无需重新生成 MsgId。
错误码 code == 0，则礼物请求全部消费成功；但可能存在部分礼物赠送成功、部分礼物赠送失败，具体礼物是否成功以及失败原因见响应体中 Result 参数。若需对赠送失败的礼物重新赠送，则需重新生成 MsgId。

响应示例

{
    "Code": 0,
    "Message": "succeed",
    "RequestId": "abcd123",
    "Data": {
        "Results": [
          {
            "Result": 0,
            "Msg": "success",
            "MsgId":"445623452643416236"
          }
        ]
    }
}

返回码

以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	描述说明	处理建议
7202001	游戏未找到，可能造成的原因包含： `MiniGameId` 输入错误。未开通此游戏的权限。	请检查 `MiniGameId` 是否正确。请联系 ZEGO 商务人员开通此游戏的权限。
7202002	`MiniGameId` 格式错误。	请确认格式是否为 String。
7206001	游戏未开始。	请确认游戏开始后再送礼。

Result 处理结果码

返回码	描述说明	处理建议
10003	送礼失败，可能造成的原因包含：用户未加入游戏。房间不存在或已结束。未知错误。	请联系 ZEGO 技术人员排查问题。
10004	未配置对应礼物。	请确认礼物是否已配置。
10005	送礼异常。	请联系 ZEGO 技术支持排查问题。
10006	`MsgId` 对应的送礼请求正在处理中。	请稍后重试。