Send gifts

Description

Calling this interface to trigger the gift-giving event in the live comment-based game will produce corresponding effects on thelive comment-based game client.

Request method and endpoint

• Request method: POST
• Request URL: https://mini-game-api.zego.im/?Action=SendDanmakuGifts
• Transmission protocol: HTTPS
• Call frequency limit: 20 times/second (at the room level)

Request parameters

The following request parameter list only lists interface request parameters. For the public parameter list, please refer to Make API requests.

Input instructions for GiftId, Value, and Num

Num (number of game effect units) is related to GiftID (gift) and Value (number of gifts required per unit of effect). It is also influenced by specific game rules. For more details, please contact the ZEGOCLOUD technical support team.

For example, in game A:

• The GiftId of the "rocket"(a gift) is g1.
• Sending 10 "rockets" at once will summon a "soldier"(the effect) in the game.
• Sending 66 "rockets" at once will summon a "general"(the effect) in the game.

During the game, there may be the following situations:

• When the audience wants to send 20 "rockets" to summon two soldiers in the game, the GiftInfo value passed in at this time is:：

  Untitled

  "GiftInfo": {
      "GiftId": "g1",
      "Value": 10,
      "Num": 2
  }
  

  1

  Copied!

• When the audience wants to send 66 "rockets" to summon a "general" in the game, the value passed in at this time is:

  Untitled

  "GiftInfo": {
      "GiftId": "g1",
      "Value": 66,
      "Num": 1
  }
  

  1

  Copied!

• If the developer's value does not match what was agreed with the ZEGOCLOUD technical support, an error message will be returned because it does not comply with the agreed game rules.

  Untitled

  "GiftInfo": {
      "GiftId": "g1",
      "Value":30, // 30 is not equal to 10 or 66
      "Num": 1
  }
  

  1

  Copied!

Request example

• Request URL

  Untitled

  https://mini-game-api.zego.im/?Action=SendDanmakuGifts
  &<Common request parameters>
  

  1

  Copied!

• Request message body

  Untitled

  {
    "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"
    ]
  }
  

  1

  Copied!

Response parameters

There are two scenarios for gift delivery failure:

• If the error code “code != 0”, it means that all gifts have failed to be delivered. In this case, the MsgId will not be recorded, and you can retry the delivery directly without generating a new MsgId.
• If the error code “code == 0”, it means that the gift requests have been successfully consumed. However, there may be cases where some gifts are successfully delivered while others fail. The specific information about whether the gifts are successful or the reasons for failure can be found in the Result parameter of the response body. If you need to re-gift a failed gift, you need to regenerate the MsgId.

Response example

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

Return code

The following only lists the return codes related to the interface business logic. For complete return codes, please refer to Global return codes.

Result processing result code