editForumTopic

Returns: TrueOfficial docs ↗

Use this method to edit name and icon of a topic 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_manage_topics administrator rights, unless it is the creator of the topic. 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

nameStringOptionalminLen 0maxLen 128

New topic name, 0-128 characters. If not specified or empty, the current name of the topic will be kept

icon_custom_emoji_idStringOptional

New unique identifier of the custom emoji shown as the topic icon. Use getForumTopicIconStickers to get all allowed custom emoji identifiers. Pass an empty string to remove the icon. If not specified, the current icon will be kept

Returns

On success, True is returned.

GramIO Usage

// Rename a forum topic
await bot.api.editForumTopic({
  chat_id: -1001234567890,
  message_thread_id: 42,
  name: "Announcements",
});

// Change both the topic name and its custom emoji icon
await bot.api.editForumTopic({
  chat_id: "@mysupergroup",
  message_thread_id: 42,
  name: "Dev Discussion",
  icon_custom_emoji_id: "5312536423851630001",
});

// Remove the topic icon by passing an empty string
await bot.api.editForumTopic({
  chat_id: -1001234567890,
  message_thread_id: 42,
  icon_custom_emoji_id: "",
});

// Handle the forum_topic_created event and immediately rename it
bot.on("message", async (ctx) => {
  const threadId = ctx.update.message?.message_thread_id;
  const topicCreated = ctx.update.message?.forum_topic_created;
  if (topicCreated && threadId) {
    await bot.api.editForumTopic({
      chat_id: ctx.chatId,
      message_thread_id: threadId,
      name: `[OPEN] ${topicCreated.name}`,
    });
  }
});

Errors

Code	Error	Cause
400	Bad Request: chat not found	Invalid chat_id or the bot is not a member of the chat
400	Bad Request: message thread not found	message_thread_id doesn't exist in the target chat
400	Bad Request: not enough rights to manage topics	Bot is not the topic creator and lacks the can_manage_topics admin right
400	Bad Request: TOPIC_NAME_INVALID	name exceeds 128 characters
400	Bad Request: method is available only in supergroups	chat_id points to a regular group or channel, not a supergroup with forums enabled
403	Forbidden: not enough rights	Bot is not an administrator in the supergroup
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.

Tips & Gotchas

• Both name and icon_custom_emoji_id are optional. Omit a field to keep its current value — passing only name leaves the icon unchanged.
• Pass an empty string for icon_custom_emoji_id to remove the icon. Omitting it keeps the current icon; an empty string clears it.
• Use getForumTopicIconStickers to get valid emoji IDs. Only specific emoji from the sticker set are allowed as topic icons — you can't use arbitrary custom emoji.
• Bot must be creator of the topic or have can_manage_topics admin right. If neither condition is met, the call returns a 400 error.
• Works in private chats with topics (as of Bot API 9.0). The message_thread_id works the same way in both supergroups and private chats with topics enabled.
• General topic cannot be edited with this method. Use editGeneralForumTopic for the special General topic.

See Also

• createForumTopic — Create a new forum topic
• closeForumTopic — Close a forum topic to new messages
• reopenForumTopic — Reopen a closed forum topic
• deleteForumTopic — Delete a forum topic and all its messages
• editGeneralForumTopic — Edit the special General topic name
• getForumTopicIconStickers — Get the list of allowed topic icon emoji
• ForumTopic — Forum topic object type