createForumTopic

Returns: ForumTopicOfficial docs ↗

Use this method to create 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 right. Returns information about the created topic as a ForumTopic object.

Parameters

chat_idIntegerStringRequired

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

nameStringRequiredminLen 1maxLen 128

Topic name, 1-128 characters

icon_colorIntegerOptional

Values:7322096167665901333833193671921674949016478047

Color of the topic icon in RGB format. Currently, must be one of 7322096 (0x6FB9F0), 16766590 (0xFFD67E), 13338331 (0xCB86DB), 9367192 (0x8EEE98), 16749490 (0xFF93B2), or 16478047 (0xFB6F5F)

icon_custom_emoji_idStringOptional

Unique identifier of the custom emoji shown as the topic icon. Use getForumTopicIconStickers to get all allowed custom emoji identifiers.

Returns

On success, the ForumTopic object is returned.

GramIO Usage

// Create a basic forum topic with a default icon
const topic = await bot.api.createForumTopic({
  chat_id: -1001234567890,
  name: "General Discussion",
});
// Save message_thread_id to send messages to this topic later
console.log(`Topic thread ID: ${topic.message_thread_id}`);

// Create a topic with a specific icon color (yellow)
const topic = await bot.api.createForumTopic({
  chat_id: -1001234567890,
  name: "Announcements",
  icon_color: 16766590, // 0xFFD67E — yellow
});

// Create a topic with a custom emoji icon
// Use getForumTopicIconStickers to find valid emoji IDs
const topic = await bot.api.createForumTopic({
  chat_id: -1001234567890,
  name: "Bug Reports",
  icon_color: 16478047, // 0xFB6F5F — red
  icon_custom_emoji_id: "5312536423581202898",
});

// Create a topic and then send a message into it
const topic = await bot.api.createForumTopic({
  chat_id: -1001234567890,
  name: "Support",
  icon_color: 9367192, // 0x8EEE98 — green
});

await bot.api.sendMessage({
  chat_id: -1001234567890,
  message_thread_id: topic.message_thread_id,
  text: "Welcome to the Support topic!",
});

Errors

Code	Error	Cause
400	Bad Request: chat not found	Invalid or inaccessible chat_id — verify the bot is a member
400	Bad Request: TOPIC_NAME_EMPTY	name is empty — must be 1–128 characters
400	Bad Request: TOPIC_NAME_TOO_LONG	name exceeds 128 characters
400	Bad Request: ICON_COLOR_INVALID	icon_color is not one of the 6 allowed integer values
400	Bad Request: FORUMS_DISABLED	The supergroup does not have the forum/topics feature enabled
400	Bad Request: method not available for this chat type	Target chat is not a forum supergroup (or an allowed private chat)
403	Forbidden: not enough rights	Bot lacks the can_manage_topics administrator right in the supergroup
429	Too Many Requests: retry after N	Rate limit hit — check retry_after, use auto-retry plugin

Tips & Gotchas

• Forum mode must be enabled on the supergroup. The chat must have topics turned on in group settings — the method fails silently otherwise.
• icon_color accepts only 6 specific integer values. Valid options: 7322096 (blue 0x6FB9F0), 16766590 (yellow 0xFFD67E), 13338331 (purple 0xCB86DB), 9367192 (green 0x8EEE98), 16749490 (pink 0xFF93B2), 16478047 (red 0xFB6F5F).
• Get valid icon_custom_emoji_id values from getForumTopicIconStickers. Not all custom emoji work as topic icons — only those returned by that method are permitted.
• Save message_thread_id from the returned ForumTopic. You need it to send messages into the topic, close it, or delete it later.
• In private chats, bots can always create topics without admin rights. This is useful for organizing per-user conversations.
• The can_manage_topics right is required in supergroups — even if the bot has other admin rights, this specific permission must be granted.

See Also

• editForumTopic — Edit an existing topic's name or icon
• closeForumTopic — Close a topic to prevent new messages
• deleteForumTopic — Delete a topic and all its messages
• getForumTopicIconStickers — Get the list of allowed topic icon custom emoji IDs
• ForumTopic — Return type containing message_thread_id and icon details