createChatInviteLink

Returns: ChatInviteLinkOfficial docs ↗

Use this method to create an additional invite link for a chat. The bot must be an administrator in the chat for this to work and must have the appropriate administrator rights. The link can be revoked using the method revokeChatInviteLink. Returns the new invite link as ChatInviteLink object.

Parameters

chat_idIntegerStringRequired

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

nameStringOptionalminLen 0maxLen 32

Invite link name; 0-32 characters

expire_dateIntegerOptional

Point in time (Unix timestamp) when the link will expire

member_limitIntegerOptional

The maximum number of users that can be members of the chat simultaneously after joining the chat via this invite link; 1-99999

creates_join_requestBooleanOptional

True, if users joining the chat via the link need to be approved by chat administrators. If True, member\_limit can't be specified

Returns

On success, the ChatInviteLink object is returned.

GramIO Usage

// Create a basic invite link with no restrictions
const link = await bot.api.createChatInviteLink({
  chat_id: "@mychannel",
  name: "General access",
});
console.log(link.invite_link);

// Create a time-limited link expiring in 24 hours with a member cap
const expiresAt = Math.floor(Date.now() / 1000) + 86400;

const link = await bot.api.createChatInviteLink({
  chat_id: -1001234567890,
  name: "Event 2025",
  expire_date: expiresAt,
  member_limit: 50,
});
console.log(`Link: ${link.invite_link}, expires: ${link.expire_date}`);

// Create an approval-gated link — users must be accepted by admins
const link = await bot.api.createChatInviteLink({
  chat_id: -1001234567890,
  name: "Membership application",
  creates_join_request: true,
});
console.log(link.invite_link);

Errors

Code	Error	Cause
400	`Bad Request: chat not found`	Invalid or inaccessible `chat_id` — verify the bot is a member of the target chat
400	`Bad Request: can't combine member limit with join request approval`	`member_limit` and `creates_join_request` are mutually exclusive — choose one
400	`Bad Request: INVITE_LINK_NAME_INVALID`	`name` exceeds 32 characters
400	`Bad Request: EXPIRE_DATE_INVALID`	`expire_date` is in the past or otherwise invalid
403	`Forbidden: not enough rights`	Bot lacks the `can_invite_users` administrator right
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

member_limit and creates_join_request are mutually exclusive. Setting both in a single call will fail — choose between capping membership or requiring admin approval for each joiner.
Bot must have the can_invite_users admin right. Other admin permissions do not imply this right; it must be explicitly granted.
expire_date is a Unix timestamp in seconds, not milliseconds. Use Math.floor(Date.now() / 1000) + seconds to compute future timestamps correctly.
Only bot-created links can be revoked with revokeChatInviteLink. The primary invite link (managed by the group owner) cannot be revoked this way.
name is shown to users before joining. Use descriptive names like "Event 2025" or "VIP tier" to track invite sources and manage links efficiently.
@username strings work for public channels and groups. Private chats always require the numeric chat ID.

createChatInviteLink ​

Parameters ​

Returns ​

GramIO Usage ​

Errors ​

Tips & Gotchas ​

See Also ​