Token-gate a Telegram group

Let only token or NFT holders into a Telegram group or channel, and remove members who stop qualifying.

To make a Telegram group that only token or NFT holders can join, create a guild on Guild, add a role that requires holding your token or NFT, and give that role a Telegram reward. Guild's bot, @Guildxyz_bot, becomes an admin of your group. Members connect their wallet and Telegram account to Guild, and each one who qualifies gets an invite link that works once. When someone stops meeting the requirement, for example because they sold the token, they lose the role and the bot removes them from the group. Telegram gating is part of the free plan.

Before you start

You need:

  • a Telegram group or channel where you are an admin
  • the contract address of your token or NFT collection, and the chain it is on
  • a guild. If you don't have one, create it at /create

Onchain requirements work on 50 EVM mainnets. See Supported chains for which kinds of requirement each chain supports.

Set it up

1. Create a holder role

  1. On your guild, choose Manage guild in the sidebar to open the admin panel.
  2. Open Spaces & roles, choose New role, then Empty role. The new role opens in the inspector.
  3. Give it a name, such as "Holders", and press Save.

2. Add the token or NFT requirement

  1. Under Who gets it, press Requirement.
  2. Pick Token balance for a coin or ERC-20 token, or NFT Balance for a collection.
  3. Choose the chain, paste the contract address and set the minimum amount, for example at least 1 NFT or at least 1,000 tokens.
  4. Press Add requirement.

You can add more requirements to the same role, such as a second collection or an X account older than a date, and choose under Members should meet whether members need All of them or Any one. See Token and NFT requirements for every field.

3. Connect the Telegram group

  1. Under Unlocks, press Add reward and pick Telegram. If your Guild account has no Telegram account connected yet, connect it first.
  2. Press Add Bot to Group, or Add Bot to Channel for a channel. Telegram opens. Choose your group and add the bot as an admin with the permissions it asks for: Invite Users via Link and Ban Users, plus Post Messages in a channel.
  3. The bot posts the group's Group ID in the group, a number such as -100123456789. Copy it.
  4. Paste it into Group ID and press Add reward. Guild checks the group and shows its name when the bot is set up correctly.

If Guild shows an error instead, such as "Bot is not in the group or chat ID is invalid" or "Bot needs to be an administrator in the group", check the number and the bot's admin rights. Sending /status to the bot in the group shows whether it is an admin, whether it can add and ban users, and whether the group is private.

4. Make the group private

Anyone with the link to a public group can join it without going through Guild. Make the group private and stop sharing old invite links, so the only way in is the link Guild gives a qualifying member.

What members do

  1. They open your guild, join it and connect a wallet and their Telegram account.
  2. Guild checks the role. If one of their wallets holds enough, they get the role.
  3. On the Telegram reward they press Join Group, then Open Telegram to go in.

Share the guild's link wherever you used to share the group's link, for example on your site or in your Discord.

How removal works

Guild refreshes onchain data in the background, so a sale or transfer reaches Guild without the member doing anything. When a member no longer meets the role's requirements, they lose the role and the bot removes them from the group. Their past messages stay. The same happens if they leave the guild.

If they qualify again later, they can press Join Group again. Guild lifts the earlier removal and gives them a new invite link.

If Guild can't read a member's data for a while, it keeps the roles they already have rather than taking them away, so a brief data problem doesn't remove anyone. It never grants a role on missing data. See How Guild works for the details.

FAQ

Does Guild remove people who were already in the group?

No. Guild only removes members who claimed the Telegram reward with Join Group. People who joined before you set up Guild, or through another link, aren't tracked, so ask them to join through the guild and remove the rest yourself.

Can members share their invite link?

Each link Guild creates can be used by one person. Once a member has joined with it, it can't let anyone else in.

Can I gate on several tokens or require holding for a period of time?

Yes. Add several requirements to the role and combine them with All, Any one or Some. To require that someone held without a break, or held at a past block, use Holding history, which works on Ethereum and Base.

Does this need a paid plan?

No. Telegram gating, token and NFT requirements are on the free plan. Paid plans add features such as hidden and secret roles, member analytics and forms; see Plans.

Does it work for Telegram channels as well as groups?

Yes. Add the bot with Add Bot to Channel and keep the Post Messages permission. In a channel the bot's commands don't appear in the menu, so type /status in full.

For every option of the reward, see Telegram groups.

All Guild docs