exportChatInviteLink

Returns: StringOfficial docs ↗

Use this method to generate a new primary invite link for a chat; any previously generated primary link is revoked. The bot must be an administrator in the chat for this to work and must have the appropriate administrator rights. Returns the new invite link as String on success.

Parameters

chat_idIntegerStringRequired

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

Returns

On success, String is returned.

GramIO Usage

// Reset and retrieve the primary invite link for a chat
const newLink = await bot.api.exportChatInviteLink({
  chat_id: -1001234567890,
});
console.log(newLink); // "https://t.me/joinchat/..."

// Admin command: refresh the invite link and share it
bot.command("refreshlink", async (ctx) => {
  const link = await bot.api.exportChatInviteLink({
    chat_id: -1001234567890,
  });
  await ctx.send(`New invite link: ${link}`);
});

// Rotate the primary link by username (public channels/groups)
const link = await bot.api.exportChatInviteLink({
  chat_id: "@mypublicchannel",
});
console.log(`Primary link rotated: ${link}`);

Errors

Code	Error	Cause
400	Bad Request: chat not found	Invalid or inaccessible chat_id — ensure the bot is a member of the target chat
403	Forbidden: not enough rights	Bot lacks the can_invite_users administrator right — grant it in the group's admin settings
403	Forbidden: bot is not a member of the channel chat	Bot is not in the chat — add it as an admin first
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

• Calling this revokes the existing primary link. Any users who had the old primary link can no longer use it to join. Use this only when intentional rotation is needed (e.g., after a leak).
• Returns a plain String, not a ChatInviteLink object. If you need a link with metadata (name, expiry, member limit, join request approval), use createChatInviteLink instead.
• Bot must have the can_invite_users admin right. This is separate from other admin permissions and must be explicitly assigned.
• @username strings work for public channels and groups. Private chats always require the numeric chat ID.
• The primary link is the single "default" link for a chat. Each chat has exactly one primary link at a time — this method replaces it. Extra tracked links (with limits, names, expiry) are managed separately via createChatInviteLink and revokeChatInviteLink.
• Avoid calling this unnecessarily. Rotating the primary link impacts all members who may have shared it; prefer creating secondary links for trackable campaigns instead.

See Also

• createChatInviteLink — create additional named/limited/expiring links without revoking the primary
• editChatInviteLink — modify an existing bot-created invite link
• revokeChatInviteLink — revoke a specific bot-created link
• approveChatJoinRequest — approve a pending join request
• declineChatJoinRequest — decline a pending join request
• ChatInviteLink — the richer invite link object returned by createChatInviteLink
• auto-retry plugin — automatic 429 retry handling