deleteForumTopic

Returns: TrueOfficial docs ↗

Use this method to delete a forum topic along with all its messages in a forum supergroup chat or a private chat with a user. In the case of a supergroup chat the bot must be an administrator in the chat for this to work and must have the can_delete_messages administrator rights. Returns True on success.

Parameters

chat_idIntegerStringRequired

Unique identifier for the target chat or username of the target supergroup (in the format @supergroupusername)

message_thread_idIntegerRequired

Unique identifier for the target message thread of the forum topic

Returns

On success, True is returned.

GramIO Usage

// Delete a forum topic and all its messages permanently
await bot.api.deleteForumTopic({
  chat_id: -1001234567890,
  message_thread_id: 123,
});

// Delete the current forum topic from within a message handler
bot.on("message", async (ctx) => {
  const threadId = ctx.update.message?.message_thread_id;
  if (threadId && ctx.text === "/deletetopic") {
    await bot.api.deleteForumTopic({
      chat_id: ctx.chatId,
      message_thread_id: threadId,
    });
  }
});

// Create a temporary topic, use it, then clean up
const topic = await bot.api.createForumTopic({
  chat_id: -1001234567890,
  name: "Temporary Discussion",
});

// ... use the topic ...

await bot.api.deleteForumTopic({
  chat_id: -1001234567890,
  message_thread_id: topic.message_thread_id,
});

Errors

Code	Error	Cause
400	Bad Request: chat not found	chat_id is invalid or the bot cannot access the chat
400	Bad Request: message thread not found	message_thread_id doesn't exist or the topic was already deleted
400	Bad Request: FORUM_DISABLED	The target chat does not have forums enabled
403	Forbidden: not enough rights	Bot is not an admin or lacks can_delete_messages right in the supergroup
429	Too Many Requests: retry after N	Rate limit hit — check retry_after, use auto-retry plugin

Tips & Gotchas

• This is permanent and irreversible. Unlike closeForumTopic, deleteForumTopic deletes the topic and every message inside it. There is no undo. If you only want to stop new messages, use closeForumTopic instead.
• Requires can_delete_messages, not can_manage_topics. Despite acting on a topic, the required right is for message deletion — not topic management. Ensure the bot has this specific right.
• Works in private chats with topics enabled. In addition to supergroups, this method can delete topics in private (DM) chats that have topics enabled.
• message_thread_id equals the topic's creation message ID. The ID comes from ForumTopic.message_thread_id as returned by createForumTopic, or from ctx.messageThreadId inside the topic.
• Deleting a topic also removes it from unread counts. Users will lose access to all messages in the topic immediately.

See Also

• createForumTopic — create a new forum topic
• editForumTopic — rename or change the topic icon
• closeForumTopic — close a topic without deleting it
• reopenForumTopic — reopen a closed topic
• unpinAllForumTopicMessages — unpin all messages in a topic
• ForumTopic — the forum topic object type