sendDice

Returns: Message⌨️ KeyboardsOfficial docs ↗

Use this method to send an animated emoji that will display a random value. On success, the sent Message is returned.

Parameters

business_connection_idStringOptional

Unique identifier of the business connection on behalf of which the message will be sent

chat_idIntegerStringRequired

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

message_thread_idIntegerOptional

Unique identifier for the target message thread (topic) of a forum; for forum supergroups and private chats of bots with forum topic mode enabled only

direct_messages_topic_idIntegerOptional

Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat

emojiStringOptional Default: 🎲

Values:🎲🎯🏀⚽🎳🎰

Emoji on which the dice throw animation is based. Currently, must be one of "!🎲", "!🎯", "!🏀", "!⚽", "!🎳", or "!🎰". Dice can have values 1-6 for "!🎲", "!🎯" and "!🎳", values 1-5 for "!🏀" and "!⚽", and values 1-64 for "!🎰". Defaults to "!🎲"

disable_notificationBooleanOptional

Sends the message silently. Users will receive a notification with no sound.

protect_contentBooleanOptional

Protects the contents of the sent message from forwarding

allow_paid_broadcastBooleanOptional

Pass True to allow up to 1000 messages per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot's balance

message_effect_idStringOptional

Unique identifier of the message effect to be added to the message; for private chats only

suggested_post_parametersSuggestedPostParametersOptional

A JSON-serialized object containing the parameters of the suggested post to send; for direct messages chats only. If the message is sent as a reply to another suggested post, then that suggested post is automatically declined.

reply_parametersReplyParametersOptional

Description of the message to reply to

reply_markupInlineKeyboardMarkupReplyKeyboardMarkupReplyKeyboardRemoveForceReplyOptional⌨️ Keyboards

Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user

Returns

On success, the Message object is returned.

GramIO Usage

Send a default dice (🎲) and read its rolled value:

bot.on("message", async (ctx) => {
  const msg = await ctx.sendDice("🎲");
  const rolled = msg.dice?.value ?? 0;
  await ctx.send(`You rolled a ${rolled}!`);
});

Reply to the user's message with a dice throw:

bot.on("message", async (ctx) => {
  const msg = await ctx.replyWithDice("🎲");
  const rolled = msg.dice?.value ?? 0;
  await ctx.send(`You rolled: ${rolled}`);
});

Send a slot machine (🎰) and check for a jackpot (value 64):

bot.on("message", async (ctx) => {
  const msg = await ctx.sendDice("🎰");
  const result = msg.dice?.value ?? 0;

  if (result === 64) {
    await ctx.send("Jackpot! You hit the maximum!");
  } else {
    await ctx.send(`Slot result: ${result} — better luck next time!`);
  }
});

Build a simple basketball mini-game (🏀, values 1–5):

bot.command("shoot", async (ctx) => {
  const msg = await ctx.sendDice("🏀");
  const score = msg.dice?.value ?? 0;

  const verdict =
    score >= 4 ? "Slam dunk!" : score >= 2 ? "Nice shot!" : "Missed!";
  await ctx.send(verdict);
});

Direct API call with bot.api.sendDice (useful outside message handlers):

const msg = await bot.api.sendDice({
  chat_id: 123456789,
  emoji: "🎯",
});
const value = msg.dice?.value ?? 0;

Errors

Code	Error	Cause
400	Bad Request: chat not found	The chat_id is invalid, the bot has never interacted with the user, or the chat does not exist.
400	Bad Request: wrong dice emoji	The emoji value is not one of the six supported emojis (🎲 🎯 🏀 ⚽ 🎳 🎰).
403	Forbidden: bot was blocked by the user	The user blocked the bot. Remove them from your active user list.
429	Too Many Requests: retry after N	Flood control triggered. Back off for the specified number of seconds.

TIP

Use GramIO's auto-retry plugin to handle 429 errors automatically.

Tips & Gotchas

• The value is truly random. Telegram generates the random value server-side — you cannot control or predict the outcome. Read message.dice.value from the returned Message object.
• Value ranges differ by emoji. 🎲 🎯 🎳 → 1–6 · 🏀 ⚽ → 1–5 · 🎰 → 1–64. Design game logic around the correct range for your chosen emoji.
• Omitting emoji defaults to 🎲. If you want a specific animated emoji, always pass the emoji parameter explicitly.
• The animation plays client-side. The rolled value is embedded in the message immediately, but the visual animation takes a few seconds to complete. Do not read the value before the Message is returned — the value is already final when sendDice resolves.
• Not suitable for real gambling. The dice is entertainment-only. Telegram reserves the right to change value ranges or behavior in future API versions.
• protect_content prevents forwarding. Use this in fair-play scenarios where users should not forward a lucky roll to another chat.

See Also

• Dice type — structure of the dice object in the returned message
• Message type — full structure of the returned message
• Keyboards overview — attaching inline keyboards for follow-up actions
• sendMessage — send a text response after reading the dice value
• auto-retry plugin — handle rate limits automatically