Discord roles
Give a Discord role to the people whose wallets meet a token gate, and take it back when they stop.
A token gate can give a Discord role as well as gate sign-in: Synq's bot gives the role to people whose wallets meet the gate's rule, checks them again on a schedule, and takes the role back from anyone who stops qualifying. One rule can gate an app's sign-in and a role at once. Discord roles come with token gates, so they need a plan that includes them (Pro and up; otherwise plan_feature_unavailable).
Connecting a server
Add Synq's bot to the server from the dashboard (Communities, Discord, Add to Discord), or start adding it with the brand its members verify on and the dashboard path to come back to. The answer is a link to Discord's own install screen, good for 15 minutes and once. Discord asks which server, and shows what the bot may do there:
| Permission | Why the bot needs it |
|---|---|
| Manage Roles | To give and take the roles your gates name, and only those |
| View Channels | To see the channel it keeps its Verify message in |
| Send Messages | To post that message, and to answer the Verify button |
| Embed Links | To show the Verify message as Discord's card, with its button |
| Pin Messages | To pin an announced window's announcement in that channel |
Adding a bot takes Manage Server in that server. Discord then sends the person to Synq, which connects the server to your org and sends them back to the dashboard: with discord set to connected, or to cancelled, taken (another organization has it), full (your org has 25 servers), expired (the link sat past its 15 minutes), used (it was used already) or failed. An expired or used link still comes back to the page it began on, saying so, and Add to Discord makes a new one. It is recorded as discord_server.connected.
The brand is fixed once the server connects: its members verify on that brand's hosted pages and become its users. They sign in the way they already do, link Discord 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 Discord sign-in. To move a server to another brand, disconnect it and add it again.
List your servers to see each one's status, how many roles your gates give there and how many people Synq manages. A server whose status is bot_removed lost the bot: add it again under Communities, Discord. Disconnecting a server takes the bot out and stops every role your gates give there: whoever holds one keeps it, and nobody is checked there again (discord_server.disconnected).
Putting Synq's role above the role it gives
Discord lets a bot give only the roles below its own highest role. Read the server's roles to see, for each, whether Synq's bot can give it (assignable), why not when it can't (problem), the fix in the dashboard's words (problem_detail), and the gate that gives it already (gate):
- The bot's role is below the role: "Synq's role is below @Holder in Server Settings → Roles. Drag Synq above it."
- @everyone is every member, so nobody gives or takes it, and a role a bot or an integration owns (
managed) can't be given by anyone else: make a role of your own for holders. - The bot's Manage Roles permission was turned off: turn it on for its role in Server Settings → Roles.
Giving a role through a gate
Add the role to a gate under Applies to, or name it in a gate's discord_roles when you make or change one (a gate of the server's brand: a gate names only its own brand's servers):
| Field | What it is |
|---|---|
server | A connected server (dsv_…) |
role | The role's Discord id |
grace_seconds | How long someone keeps the role 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 who holds it through Synq is checked again: 3600 (every hour) to 86400 (every day). 21600 (every 6 hours) when left out |
existing_members | Those who already hold the role: verify gives them an announced window to verify (the default), leave leaves them alone (below) |
Synq reads the role from Discord as you add it, and refuses one the bot can't give, with the fix, at its path (discord_roles.0.role). A role follows one gate: a second gate that names it is refused, naming the gate that has it, since a rule's "all of" and "any of" say whatever two gates would. A gate gives at most 25 roles. discord_roles replaces the list: a role you keep keeps its people and takes the new settings, and a role you take off stops being managed, with whoever holds it keeping it. Where Synq's API has no Discord bot, adding a role is 409 discord_unavailable.
The Verify message
Pick the channel the bot keeps its Verify with Synq message in: in the gate's form, or change the server with verify_channel, from its text channels. The bot posts it there, edits it in place when it is there already, and deletes the one it left in another channel (discord_server.updated). It needs View Channel, Send Messages and Embed Links in that channel (400 at verify_channel with the fix). The message names no role, so it never goes stale as your gates change. It's a card in the look of the brand the server is connected to: the brand's name and icon at the top (its logo when it has no icon, Logos, icons and backgrounds), its primary color down the side (Synq's mint when the brand sets none), and "Powered by Synq" at the foot as the brand's pages say it. The bot itself keeps Synq's name and picture; for your own, bring your own bot (Scale and up). When the brand's name, logo, icon, color or "Powered by Synq" changes, the bot redraws it in place on its own, within half a minute, and an old card someone presses is redrawn too. Move it or redraw it any time under Communities → Discord: pick its channel (the one it's in redraws it, another moves it and deletes the old one). The card's words, and its button's on Scale and up ("Verify with RODAI"), can be your own: saving them redraws every card at once (see Bot messages).
Where verified members go
Pick the channel members land in once they get a role, usually one the role unlocks: under Communities → Discord, or change the server with verified_channel (null for the server itself, the default). The member profile's Back to Discord opens it once a role is given, and the bot's "You're verified" message links to it, so members land where the role shows rather than back in the Verify channel. The bot needn't post there.
What members see
- A member presses Verify with Synq. The bot answers with a link only they see. It opens once, in one browser, within 10 minutes: "Here's your link to verify in Acme. It works for 10 minutes, and it's just for you."
- The link opens the brand's own sign-in, with every way in the brand offers and the reason above them: "To get Holder in the Acme Discord, sign in to your Acme account." The way they signed in last comes first, marked Last used, so they sign in the way they did before. A browser already signed in to the brand goes straight on.
- They land on their member profile: their wallets, their linked accounts, every gate of the brand's listed communities, live, and one finish button. The button says exactly what's missing ("Add a wallet with 3 more", or Add a wallet where any one of a gate's conditions would do), then Connect Discord to finish, then Get Holder.
- Connecting Discord there takes Discord's own sign-in once, and must be the account that pressed Verify. Any other account stops with what happened and the fix ("That was @other. This link is for @ari, the account that pressed Verify…"), and nothing is linked. A forwarded link verifies nobody else: only the account it was made for gets the role, with that person's wallets.
- Each role in the server is judged alone. The bot gives each role whose gate they meet and tells them in a direct message, which waits for them however they come back to Discord: "You're verified: Holder is yours in Acme.", with Go to Acme and Open my profile. Where their direct messages are closed to the bot, the same goes as a message only they see at the bottom of the channel they pressed Verify in, within 15 minutes of the press. The button's reply becomes "You're verified 🎉 You now have @Holder.", and the profile says it's theirs, with Back to Discord.
The brand needn't offer Discord sign-in: members link Discord on their member profile, whatever way they sign in. A verification is a sign-in to the brand, and counts toward its monthly active users as any sign-in does.
Link once, get in everywhere this brand gates
A member whose Discord account is already linked to their account at the brand, because they signed in with Discord there or added it from your app, needs no link. When they press Verify with Synq, Synq checks every Solana wallet on that account against each role's gate. The bot gives each role they meet at once and answers: "You're verified: your Discord account is already linked to your Acme account. You now have @Holder.", with Open my profile beside it. Pressed again once every role they meet is theirs, it answers "You're verified already, and you have @Holder. Nothing else to do." A role they don't meet yet comes with their link, so they can add the wallet that holds what it asks for. Meeting none, they get the link like anyone else. Each role given this way is recorded as discord_role.recognized (Activity shows it under Verified), then discord_role.granted. Only the brand's own users count: an account linked at another brand, yours or anyone's, changes nothing here.
Synq hears nothing when someone joins a server, because its bot talks to Discord over HTTP and never over the gateway. So someone who joins later presses Verify once, and gets in at once if their account is linked.
Checked again
Everyone who holds a role through Synq is checked again every recheck_seconds (or when what they qualified on lapses, if that comes first: activity in a window):
- Still qualifying: nothing changes.
- No longer qualifying: the grace period starts (
discord_role.removal_scheduled, withends_at), and the bot tells them in a direct message. Qualify again before it ends and nothing changes. - Still not qualifying when it ends: the bot takes the role back (
discord_role.removed) and tells them. Losing qualification removes the role, never the person: they stay in the server. - Qualifying again after losing the role: Synq keeps checking everyone who verified on the same schedule, so the bot gives the role back on its own (
discord_role.granted, withqualified_again: true) and tells them: "You qualify again, so @Holder in Acme is yours again. Welcome back!" Pressing Verify with Synq checks at once. - Their account at the brand 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 the role and are checked again within 30 minutes, so an outage takes nobody's role away.
A role met on activity in a window lapses when the activity it counted gets too old. A lapse is a drop like any other: the grace period starts then. Three days before it, the bot sends a heads-up, once for each lapse date: "Your @Swapper role in Acme counts recent activity: it ends November 21, 2026 unless you're active again (Used Acme Swap at least 3 times in the last 30 days)." Synq checks again early enough that the heads-up is never late.
A gate that's off checks nobody, and everyone keeps what they have. When the bot can't give or take a role (its role was moved below it, it lost Manage Roles, it was removed), it records discord_role.grant_failed or discord_role.removal_failed once per problem, with the fix in metadata.fix, and tries again.
What the bot tells members
Every direct message about someone's role (the role given on their member profile, the grace period starting, the role taken, the role given back, a heads-up before a lapse) is in the brand's look: its name and logo, its color, and "Powered by Synq" as its pages say it. Each one 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 the member sees where they stand and what each role asks for. Nothing about losing a role is ever posted in a channel: only the member hears it. Each of these messages, and the replies to a Verify press, can be in your own words (Bot messages).
Members who turned off direct messages (for everyone, or for your server) aren't told when the bot DMs them. They learn on their member profile, or at their next Verify with Synq press, whose answer starts with what changed ("You lost @Holder 2 days ago (November 7, 2026 6:00 PM) because your wallets no longer qualify."). Activity shows that Synq couldn't tell them: the change's row has told: false with untold_reason: dms_off.
People who already hold the role
When you add a role that people already hold, the dashboard shows how many, and you choose:
- Give them an announced window to verify (
existing_members: verify, recommended): below. They keep the role until its deadline. - Leave them alone (
leave): Synq manages only the people who verify, and never takes the role from anyone else.
The announced window
The same window a Telegram group gets. Set it up with PUT …/discord-servers/{server}/roles/{role}/window, or under Communities → Discord on the role's window page, and announce it when you're ready. GET …/discord-servers/{server}/windows lists every gated role's window in a server.
| 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 and the zone its days and quiet hours are counted in. Discord shows each member the deadline in their own time zone |
quiet_hours | 22:00 to 09:00 unless you say, or none. No reminders, names or removals then: a reminder that falls in them goes when they end |
name_unverified | In the last 7 days, name those still to verify, 20 to a message, at most 3 times each, never @everyone (on) |
headline | The announcement's title, in your words. What you call your members is your brand's: see Bot messages |
Announcing posts the announcement in the server's Verify channel, pinging the role, and pins it. The bot needs Send Messages, Embed Links and Pin Messages there (Synq asks for Pin Messages when it's added; a server added before needs it turned on for Synq's role). Its countdown line is edited once a day, which notifies nobody. Then the reminders follow the Telegram window's schedule, never in quiet hours, each with the Verify button; those from 7 days out ping the role, and in the last week the bot names who still holds the role without verifying. Discord's window sends no direct messages: the Verify channel reaches everyone.
Synq takes in the role's holders once the window is announced, through Discord's list of a server's members, which takes the Server Members intent on Synq's app: that is Synq's to turn on, and the roles route says so when it can't count. The deadline waits until that list is done. At the deadline, whoever hasn't verified loses the role, never their place in the server, and gets it back the moment they verify. One closing message follows, and the announcement says closed. Then nothing of the window keeps a button, so a newcomer reads no deadline that passed. Each reminder, names message and extension is edited in place to one line, which notifies nobody: "This one's closed. The deadline to verify for @Holder was November 18, 2026. You can still verify any time: press Verify with Synq on the pinned message." The announcement and the closing message lose their buttons, the announcement is unpinned, and the server's Verify message is pinned instead, so the channel has one current Verify. A cancelled window ends the same way. A window announced before Synq kept its posts' ids has them read back from the Verify channel, where the bot may read its history (Read Message History, which @everyone has by default). You can extend the deadline (it never moves earlier) and pause or resume the reminders. The announcement, the reminders, the names and the closing message can be in your own words.
Activity, audit log and webhooks
Integrations activity lists what Synq did in your servers, newest first: people verified and refused, roles given and taken, failures with their fix, and servers connected and disconnected. A change the bot DMs the member about (discord_role.removal_scheduled, discord_role.removed, and discord_role.granted with qualified_again) says whether the message reached them: told: true, or told: false with untold_reason, dms_off (their direct messages are closed to the bot) or unavailable (Discord didn't take it). Each row is an audit row, and goes to every webhook subscribed to its event: discord_server.* and discord_role.* (see webhook events). Wallet addresses never go in either.