deleteMessages

Returns: TrueOfficial docs ↗

Use this method to delete multiple messages simultaneously. If some of the specified messages can't be found, they are skipped. Returns True on success.

Parameters

chat_idIntegerStringRequired

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

message_idsInteger[]Required

A JSON-serialized list of 1-100 identifiers of messages to delete. See deleteMessage for limitations on which messages can be deleted

Returns

On success, True is returned.

GramIO Usage

// Delete multiple messages at once
await bot.api.deleteMessages({
  chat_id: -1001234567890,
  message_ids: [101, 102, 103],
});

// Delete a range of messages by constructing an ID array
const latestId = 500;
const messageIds = Array.from({ length: 10 }, (_, i) => latestId - i);

await bot.api.deleteMessages({
  chat_id: -1001234567890,
  message_ids: messageIds,
});

// Batch delete more than 100 messages by chunking
async function deleteAllMessages(chatId: number, ids: number[]) {
  for (let i = 0; i < ids.length; i += 100) {
    await bot.api.deleteMessages({
      chat_id: chatId,
      message_ids: ids.slice(i, i + 100),
    });
  }
}

// Collect and bulk-delete messages from a handler
const collected: number[] = [];

bot.on("message", async (ctx) => {
  collected.push(ctx.id);

  if (collected.length >= 10) {
    await bot.api.deleteMessages({
      chat_id: ctx.chatId,
      message_ids: [...collected],
    });
    collected.length = 0;
  }
});

Errors

Code	Error	Cause
400	Bad Request: chat not found	chat_id is invalid or inaccessible
400	Bad Request: too many ids	message_ids has more than 100 entries — chunk into batches of 100
403	Forbidden: not enough rights	Bot lacks the required admin rights to delete messages in this chat
403	Forbidden: bot is not a member of the channel chat	Bot is not in the specified channel
429	Too Many Requests: retry after N	Rate limit hit — check retry_after, use auto-retry plugin

TIP

Use GramIO's auto-retry plugin to handle 429 errors automatically when making many rapid deletion calls.

Tips & Gotchas

• Missing or already-deleted messages are silently skipped. Unlike deleteMessage, invalid IDs don't cause an error — the method returns True and simply skips those IDs. This makes bulk cleanup safe.
• Maximum 100 messages per call. Chunk larger arrays into batches of 100 and call sequentially. See the deleteAllMessages example above.
• All deleteMessage limitations apply — silently. Messages older than 48 hours, non-deletable service messages, etc. are skipped without error, not rejected. The call still returns True.
• Always prefer deleteMessages over looping deleteMessage. A single deleteMessages call for multiple IDs is far more efficient than a loop — fewer API calls and significantly lower risk of hitting rate limits.
• IDs must all be from the same chat. You cannot mix message IDs from different chats in one call. Group by chat_id before calling.

See Also

• deleteMessage — delete a single message with full error detail
• deleteBusinessMessages — bulk delete for business accounts
• Message — the message object type