Telegram groups
Let people into a Telegram group only while their wallets meet a token gate, and mute or remove them when they stop.
A token gate can guard a Telegram group as well as gate sign-in: Synq's bot approves the join requests of people whose wallets meet the gate's rule, checks everyone it let in again on a schedule, and mutes or removes anyone who stops qualifying. Telegram groups come with token gates, so they need a plan that includes them (Pro and up; otherwise plan_feature_unavailable).
Connecting a group
From the dashboard (Communities, Telegram, Connect a group), or start connecting one with the brand its people verify on. The answer has:
| Field | What it is |
|---|---|
code | A one-time code: it works once, within 15 minutes, from an admin of the group |
link | Telegram's link that adds Synq's bot to a group as an admin, with the rights it needs and the code: open it signed in as an admin of the group |
command | /connect <code>, to send in the group when the bot is in it already, or when the link added it and it didn't answer |
bot | Synq's bot's @username |
expires_at | When the code stops working |
The link asks Telegram to make the bot an admin with three rights, each named here as Telegram's apps show them, though the exact labels vary by app and version:
| Right | Why the bot needs it |
|---|---|
| Invite users via link | To approve join requests (Telegram's can_invite_users) |
| Ban users | To mute and remove people (can_restrict_members) |
| Pin messages | To pin its Verify message (can_pin_messages) |
When the bot doesn't answer
The bot answers "Connected" in the group once it has the code. If the link added it and nothing came, send /connect <code> in the group from an admin's account (command in the answer, which the dashboard's Copy copies), before the code expires. Telegram for Android has added the bot without sending the code; the command connects the group the same way.
Connecting by hand
Telegram's apps follow the link. Telegram Web can open it and then do nothing, so connect the group by hand there, or wherever the link doesn't work. Signed in to Telegram as an admin of the group:
- Open the group's settings (its name, then Edit or Manage group) and its Administrators, and add the bot as an admin: search for the @username the dashboard shows (
botin the answer). If Telegram doesn't offer the bot there, add it to the group as a member first, then make it an admin. - Turn on only the three rights above, Invite users via link, Ban users and Pin messages, turn every other right off, and save.
- Send
/connect <code>in the group from an admin's account (commandin the answer, which the dashboard's Copy copies), before the code expires.
The bot answers in the group, as it does after the link. When the bot is an admin of the group already, with those rights, the last step is all it takes.
Only a group admin's code counts, an anonymous admin's included. The bot reads the group and its own rights, makes a join-request invite link for it, and answers in the group, listing any right it still lacks with the fix. It is recorded as telegram_group.connected. An org connects at most 25 groups, and a group belongs to one org.
The brand is fixed once the group connects: its people verify on that brand's hosted pages. They sign in the way they already do, link Telegram on their member profile, and show what they hold with Solana wallets, so the brand must offer wallets (400 at brand with the fix). It needn't offer Telegram sign-in.
List your groups to see each one's kind, the bot's rights, its invite_link, and how many people Synq manages there. After an admin changes the bot's rights, or the group becomes a supergroup, read it again (telegram_group.updated). A bot taken out of the group is bot_removed (telegram_group.bot_removed): connect the group again. Disconnecting a group takes the bot out and stops your gate there: whoever is in it stays, a muted person stays muted until an admin lifts it, and join requests wait for the group's other admins (telegram_group.disconnected).
Sharing the group
Share the group's join-request link (invite_link, or any invite link with join requests on): Telegram holds each request for the group's admins, Synq's bot among them, and the bot approves the people who qualify.
Synq's bot has no Mini App. Telegram's blockchain guidelines let Mini Apps connect only TON wallets, so every button the bot sends opens a web page, and the verify page opens on the web, where people sign with their Solana wallet. A supergroup can also pick a guard bot, the bot Telegram asks first about each request to join: there's no need to make Synq's bot one. If a group does, the bot hands each request straight back to the admins, itself among them, and everything works as below.
Letting people in through a gate
Add the group to a gate under Applies to, or name it in a gate's telegram_groups when you make or change one (a gate of the group's brand: a gate names only its own brand's groups):
| Field | What it is |
|---|---|
group | A connected group (tgg_…) |
on_lost | What happens once someone stops qualifying and the grace period ends: mute (the default) or remove (below) |
grace_seconds | How long they keep their place after a check finds they no longer qualify: 0 (at once) to 604800 (a week). 86400 (24 hours) when left out |
recheck_seconds | How often everyone it let in is checked again: 3600 (every hour) to 86400 (every day). 21600 (every 6 hours) when left out |
existing_members | Those already in the group: verify gives them a window to verify, which you announce (the default), leave leaves them alone (below) |
A group needs the bot's Invite users via link and Ban users rights to be added, and mute needs a supergroup: each is refused with its fix at its path (telegram_groups.0.on_lost). A group follows one gate, and a gate guards at most 25 groups. telegram_groups replaces the list, keeping the people of a group you keep. Where Synq's API has no Telegram bot, adding a group is 409 telegram_unavailable.
What people see
- Someone asks to join the group.
- Synq's bot messages them a Verify with Synq button, in the 5 minutes after a request Telegram lets a bot write to someone who asked to join. From Synq's bot it's a Telegram login button: Telegram confirms it's them inside the app, asks whether the bot may message them later, and the verify page opens on the web already signed in with that Telegram account, with no Telegram web page in between. From your own bot it's a plain link to the verify page. If the bot can't write to them, it posts and pins a Verify message in the group once, with the group's own Verify with Synq button (below).
- The button opens the brand's own sign-in, with every way in the brand offers and the reason above them ("To join Acme Holders on Telegram, sign in to your Acme account."), the way they signed in last first. The link works while their request is open (48 hours).
- They land on their member profile: their wallets, linked accounts and every gate, live, with one finish button that says what's missing, then Connect Telegram to finish, then Join Acme Holders. Connecting Telegram must be the account that asked to join; any other stops with the fix, and nothing is linked.
- Qualifying, they're let in (
telegram_member.approved), and the bot says so: "You're in. Welcome to Acme Holders!", with Open my profile.
Every message the bot sends about the group starts with the brand's name, in bold, and ends "Powered by Synq" as the brand's pages say it. Every message about someone's place in the group (let in, declined, the grace period starting, muted, unmuted, removed, qualifying again, a heads-up before a lapse) has Open my profile, a button to the brand's member profile (/me on its issuer host, or on its custom domain while that serves), where they see where they stand. From Synq's bot, Open my profile is a login button too, so it opens their profile signed in. Every button opens a web page: Synq's bot never shows a Mini App. The bot itself keeps Synq's name and picture; for your own, bring your own bot (Scale and up).
The group's own Verify with Synq button (on its pinned Verify message, and on its window's announcement and posts) is one button for everyone in the group. From Synq's bot it's a Telegram login button: whoever taps it confirms it's them inside Telegram, and the brand's page opens on the web signed in with their Telegram account, with no stop in the bot's chat. Telegram's signed word says who tapped it, so it opens their own verify link, made then, or their member profile once they're verified. Verify messages pinned before Synq's bot had this button get it in place, by an edit that notifies nobody, with nothing for you to do. From your own bot, someone who refuses the login, and someone the page can't sign in (not in the group and not asking to join, banned by an admin, or a brand on its own Telegram app), the button opens the bot's chat instead, which Telegram shows only as "/start". The bot answers where the person stands: verified and in the group, "You're verified in Acme Holders. There's nothing else to do.", with Open my profile (and, while a window runs, that they're set for its deadline); in the group and not verified yet, or with a request open, their own verify link (and a running window's deadline, for someone in the group); neither, the group's invite link. Whether they're in the group is Telegram's word, or what Synq last made true there, since Telegram's answer can fail or lag a join it just approved.
Link once, get in everywhere this brand gates
Someone whose Telegram account Synq already knows at the brand, and whose wallets meet the gate, needs no link. The moment they ask to join, the bot approves the request: no link and no message. It's recorded as telegram_member.recognized (Activity shows it under Verified), then telegram_member.approved. Synq goes by the Telegram user id on the request and matches it to the id their Telegram account at the brand keeps. Telegram's sub isn't that id, so the account keeps it only after a sign-in that asked Telegram for it. That happens when they verify through a link (the verify page always asks), or when they sign in with Telegram where the brand's own Telegram app asks for telegram:bot_access. A later Telegram sign-in at the brand that doesn't ask clears it. Every Solana wallet on their account counts. Only the brand's own users count: an account linked at another brand changes nothing here.
A request that waits 48 hours without a verified wallet is declined (telegram_member.declined), and they may ask again whenever they're ready. People added to the group some other way are left alone. A verification is a sign-in to the brand, and counts toward its monthly active users as any sign-in does. Each check is recorded as user.token_gate_checked with at: telegram.
Checked again
Everyone the group let in through Synq is checked again every recheck_seconds, and so is everyone muted or removed who verified once. Someone who qualifies on activity is checked again when it lapses, if that comes first, and gets a heads-up 3 days before, once for each lapse date: "Your place in Acme Holders counts recent activity: it ends Nov 21 unless you're active again (…)." A lapse is a drop like any other. Someone who stops qualifying keeps their place for the grace period (telegram_member.removal_scheduled, and the bot tells them where Telegram lets it write to them); qualify again before it ends and nothing changes. When someone's account at the brand is deleted, it has no wallets to check, so the same grace period runs, and the bot's messages say the account was deleted and that verifying again starts fresh. A check that can't read the chain changes nothing: they keep their place and are checked again within 30 minutes. A gate that's off checks nobody. The group's admins and its owner are never muted or removed.
When someone stops qualifying
Once the grace period ends, on_lost decides:
- Mute (the default). Every permission goes off, reacting included, so they can still read everything but not post or react (
telegram_member.muted). Muted people keep being checked, and the mute lifts on its own, back to the group's own permissions, once they qualify again (telegram_member.unmuted): "You qualify again, so you can post in Acme Holders again. Welcome back!" Telegram mutes people only in supergroups. A muted person can still read everything, so a group that only verified members may read should use Remove. - Remove. They're taken out with a ban that lifts itself two minutes later (
telegram_member.removed). The bot's message telling them comes once that ban has lifted. Removed people keep being checked too: once they qualify again, the bot messages them "You qualify for Acme Holders again", with an Ask to join button (the group's join-request link). When they ask, Synq recognizes them and approves the request at once (telegram_member.recognized, thentelegram_member.approved).
In the dashboard, the group's choice shows both, with Mute picked first and that note under them. An agent connected to Synq's MCP server never picks for you: before it gates a group, it asks you "Mute or remove people who don't hold it?", and the gate tools refuse a group it adds without on_lost until it does.
Synq never posts anything about someone losing their place in the group: only they hear it, where Telegram lets the bot write to them. When it can't (they blocked the bot, or never started a chat with it), the change's row in Activity says so: told: false, with untold_reason: dms_off.
When the bot can't act (it lost a right, it was removed), it records telegram_member.action_failed once per problem, with the fix, and tries again.
Your admins' bans always stand
Synq never lifts or shortens a ban. Right before it lets anyone in, mutes, unmutes or removes them, it asks Telegram where they stand, so a ban it didn't hear about still counts. Someone an admin or another bot banned is left exactly as they are: Synq records it once (telegram_member.banned_by_admin, with when the ban ends and who set it when Telegram says), sends them nothing about the group, and makes no change for them there. If they verify or ask Synq's bot for a link, it tells them only an admin can lift the ban. Once Telegram shows the ban gone (they ask to join again, post in the group, or an admin lets them back), Synq manages them again as anyone else.
Your admins' mutes stand too
Synq lifts only its own mutes. A mute anyone else sets (one of your admins, or another bot) is left as it is. That includes a mute Synq finds on someone it takes in, and one Telegram reports right before a change that Synq didn't make. Synq records it once (telegram_member.muted_by_admin, with when the mute ends and who set it when Telegram says). It never unmutes them, whatever their wallets hold. If they verify, the bot tells them only an admin can lift the mute. Once Telegram shows they can post again (an admin lifts it, or they post or leave), Synq manages them again as anyone else.
Large changes go at Telegram's pace
When many people stop qualifying at once, Synq works through them at a pace well under Telegram's limits, for each bot by itself (Synq's, or your own): at most 10 changes a minute in one group and 10 calls a second in all, with the messages to the people concerned sent after the changes, at most 5 a second. So 5,000 removals across many groups take about half an hour, and in a single group about 10 people a minute. If Telegram asks the bot to slow down, it stops at once and goes on from where it was once Telegram's wait has passed. The bot's own replies to people asking to join don't wait.
People already in the group
When you add a group with people in it, you choose:
- Give them time to verify (
existing_members: verify, recommended): an announced window, below. Nobody is muted or removed until its deadline. - Leave them alone (
leave): Synq manages only the people who verify.
The announced window
You set the window up and announce it when you're ready: PUT …/telegram-groups/{group}/window saves its settings and answers its schedule, and POST …/window/announce posts it. The settings:
| Setting | |
|---|---|
notice_days | 7 to 365 days. A shorter window keeps the same shape and drops the early reminders |
deadline_time, time_zone | The deadline's time of day in the group's time zone (18:00 UTC unless you say), outside quiet hours. Every time the bot gives members, in the group and in direct messages, is on this clock, 12-hour (Nov 9, 6:00 PM ET) |
quiet_hours | 22:00 to 09:00 unless you say, or none. No reminders, names, messages or removals then: a reminder that falls in them goes when they end |
topic | In a forum, the topic Synq posts and pins in, from those it has seen (topics). Telegram can't hide a topic from some members, so the gate covers the whole group |
topic_link | In place of topic, any topic, by a link to a message in it: see Picking a topic |
name_unverified | In the last 7 days, name those still to verify, 20 to a message, at most 3 times each, never @everyone (on) |
message_reachable | Message everyone the bot can reach, with their own link, at 30 days, 7 days and the last day (on). Where the 7-day reminder is dropped, as in a 7-day window, that message goes with the 3-day reminder instead |
headline | The announcement's first line, in your words. What you call your members ("612 players verified") is your brand's: see Bot messages |
Announcing posts the announcement in the topic and pins it without a notification. Its countdown line ("312 days left · 612 of 1,068 verified") is edited once a day, and an edit notifies nobody. Then the reminders come closer together: monthly, every two weeks in the last two months, weekly in the last month, then 7 days, 3 days and the last day before, and 3 hours before: 19 group messages over a year with the announcement, each worded differently, each with how many have verified, the Verify with Synq button and a link to the member profile. Every one of them, and every message to people about their place in the group, can be in your own words: see Bot messages. A bot can message only people who let it: those who started a chat with it, and those who signed in with Telegram on the member profile or pressed one of Synq's bot's login buttons, which ask Telegram whether the bot may message them (it may, unless they turn that off). For everyone else the group is the only way to reach them. If the bot can't message a member, their member profile shows Get updates in Telegram, which opens the bot's chat: pressing Start there lets it.
You can extend the deadline at any time, with one message in the group, and pause or resume the reminders: the countdown and the deadline stay. Once announced, the deadline never moves earlier.
Picking a topic
The Bot API can't list a forum's topics, so Synq's bot learns each one from the messages posted in it, and the window's topics lists those it has seen: a quiet topic shows up once someone posts in it. Telegram tells a bot a topic's name only when the topic is made or renamed, and in messages that answer its first message. A topic whose first message was deleted, as service messages often are, is never named that way, so Synq lists it by its number ("Topic 5", name: null) until someone renames it in Telegram.
To pick any topic, listed or not, paste a link to a message in it. In Telegram, press and hold (or right-click) any message in the topic, then Copy Link: it looks like https://t.me/c/1234567890/5/1234, or https://t.me/<username>/5/1234 in a public group, where 5 is the topic. On the window's page, pick Another topic, by a link to a message in it… under "Post and pin in" and paste it. Through the API or MCP, send it as topic_link in place of topic, to PUT …/window, POST …/window/announce or POST …/window/move. Synq keeps the topic, and the window's topic answers its number. A link to a message in another group, or one without a topic in it (a link to a topic itself looks the same as one to a message in General), is refused with what to copy instead.
Moving the countdown to another topic
In a forum, the countdown can move to another topic, or to General, at any time before the window closes: on the window's page, pick the topic under Topic ("Post and pin in"), and confirm. topic is the new one at once, so every later reminder, the names and the closing message go there. Within a few minutes, Synq's bot posts the announcement again in the new topic, with the countdown as it stands and the Verify buttons, and pins it without a notification. Then it unpins its countdown in the topic it left and edits it to one line, "📌 The countdown moved to COMRODS.", linked to the new one. Nothing posts in quiet hours: a move made in them goes when they end, and the window's move.waits_until says when. Until it's done, the window's move names the topic the countdown is still pinned in, and picking that topic again calls the move off. If an admin deleted the old countdown, the move goes on without it. If the bot can't post in the new topic (it was closed or deleted), the window says cannot_post until it can, or until you pick another. Each move is recorded as telegram_group.window_moved.
At the deadline, Synq first makes sure it knows everyone in the group. Synq's bot reads the group's whole member list through Telegram's admin member listing when the window is announced, every day after, and once more at the deadline (members_listed_at), and learns anyone else as they post, react or join; counts.unknown says how many it hasn't seen. While any are unknown, it removes nobody and waits (problem: members_unknown), so no silent member stays without verifying. Someone whose request an admin approves by hand while the window runs gets its deadline too. Then, outside quiet hours, everyone still to verify is muted or removed, as on_lost says, at the group's pace of 10 a minute: removing 1,000 takes about 100 minutes. Anyone who verifies during the run is skipped, admins and bots are never touched, and a removal is a ban that lifts itself two minutes later. One closing message follows, and the Verify button keeps working for anyone who wants back in.
Activity, audit log and webhooks
Integrations activity lists what Synq did in your groups, newest first: people verified and refused, requests approved and declined, people muted, unmuted and removed, failures with their fix, and groups connected and disconnected. A change the bot messages someone about says whether the message reached them once the bot tried (its messages go after the changes, paced): told: true, or told: false with untold_reason, dms_off or unavailable. A webhook delivered before then doesn't carry it. Each row is an audit row, and goes to every webhook subscribed to its event: telegram_group.* and telegram_member.* (see webhook events). Wallet addresses never go in either.