sendDice

Send an animated emoji message with a random result, such as dice, darts, basketball, football, slot machine, or bowling.

Request

POST /:token/sendDice

Parameters

Parameter	Type	Required	Description
chat_id	Integer/String	Yes	Unique identifier of the target chat, as a numeric ID or numeric string. The @username form is not supported yet
emoji	String	No	Emoji on which the animation is based. Can be 🎲, 🎯, 🏀, ⚽, 🎰, or 🎳. Defaults to 🎲
message_thread_id	Integer	No	Unique identifier of the target message thread (topic), for topic groups only
reply_parameters	Object	No	Description of the message to reply to. Only the message_id field takes effect currently
reply_markup	Object	No	Custom keyboard or inline keyboard markup, accepted either as a JSON-serialized object or as a string

The following parameters are accepted but have no effect in the current implementation and are ignored by the server: business_connection_id, disable_notification, protect_content, allow_paid_broadcast, message_effect_id.

Random Value Ranges

The value is generated randomly on the server and cannot be specified by the caller.

Emoji	Type	value Range
🎲	Dice	1-6
🎯	Darts	1-6
🎳	Bowling	1-6
🏀	Basketball	1-5
⚽	Football	1-5
🎰	Slot machine	1-64

Football also accepts ⚽️ with the variation selector, which behaves the same as ⚽. Any emoji outside this table returns EMOTICON_STICKERPACK_MISSING.

Response

Returns the sent Message object on success. The result is carried in the dice field: emoji echoes the emoji actually used, and value is the point generated by the server.

{
  "ok": true,
  "result": {
    "message_id": 102,
    "from": {
      "id": 123456789,
      "is_bot": true,
      "first_name": "MyBot",
      "username": "my_bot"
    },
    "chat": {
      "id": 987654321,
      "first_name": "User",
      "username": "user123",
      "type": "private"
    },
    "date": 1700000000,
    "dice": {
      "emoji": "🎲",
      "value": 4
    }
  }
}

Error Codes

Code	Description
400	Bad request parameters, e.g. missing chat_id, unsupported emoji, or invalid reply_markup format. Hitting the send rate limit also returns 400, with the description MESSAGE_TOO_MUCH
401	Invalid or expired token
403	Bot was blocked by the user or does not have permission to send messages to this chat
404	Chat not found
500	Internal server error

Examples

Send Default Dice

curl -X POST "https://api.safew.bot/<token>/sendDice" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 987654321
  }'

Send Basketball Animation

curl -X POST "https://api.safew.bot/<token>/sendDice" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 987654321,
    "emoji": "🏀"
  }'

Mini Game with Inline Keyboard

curl -X POST "https://api.safew.bot/<token>/sendDice" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 987654321,
    "emoji": "🎯",
    "reply_markup": {
      "inline_keyboard": [
        [
          {"text": "Play again", "callback_data": "dice_retry"},
          {"text": "Rules", "callback_data": "dice_rules"}
        ]
      ]
    }
  }'

Related Applications

• Random mini games: Start lightweight interactions in private chats or groups with dice, darts, basketball, football, slot machine, or bowling animations.
• Giveaways and decisions: Use dice.value as the random result for giveaways, ranking, or random selection.
• Prediction challenges: Let users submit predictions first, then call sendDice to generate a public random result.
• Group engagement: Combine reply_markup with buttons such as “Play again” or “Rules” for continuous interaction.