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 or username of the target chat
business_connection_id	String	No	Unique identifier of the business connection on behalf of which the message will be sent
message_thread_id	Integer	No	Unique identifier of the target message thread (topic), for forum supergroups or private chats with forum topic mode enabled
direct_messages_topic_id	Integer	No	Identifier of the direct messages topic; required when sending to a direct messages chat
emoji	String	No	Emoji on which the animation is based. Can be 🎲, 🎯, 🏀, ⚽, 🎰, or 🎳. Defaults to 🎲
disable_notification	Boolean	No	Sends the message silently. Users will receive a notification with no sound
protect_content	Boolean	No	Protects the sent message content from forwarding and saving
allow_paid_broadcast	Boolean	No	Allows paid broadcasts up to 1000 messages per second for a fee of 0.1 Telegram Stars per message
message_effect_id	String	No	Unique identifier of the message effect to add to the message, for private chats only
suggested_post_parameters	Object	No	Suggested post parameters as a JSON-serialized object, for direct messages chats only
reply_parameters	Object	No	Description of the message to reply to
reply_markup	Object	No	Custom keyboard, inline keyboard, keyboard removal, or force reply markup as a JSON-serialized object

Random Value Ranges

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

Response

Returns the sent Message object on success. The Message object contains a dice field.

{
  "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
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
429	Too many requests, rate limit triggered
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": "🏀",
    "disable_notification": true
  }'

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.
• Business account interaction: Pass business_connection_id to send random interaction messages on behalf of a business account.