Skip to main content

Discord Setup Guide

Required add-on: Community Integrations

With Discord connected, each subscriber gets the roles you choose for their tier on your Discord server. Subscribers link their Discord account once, with Connect Discord on their account page, and Benecaster adds them to your server with their roles. From then on their roles follow their membership.

This guide connects one show. Each show connects its own server, so repeat it for every show that has one. Before you start, switch Community Integrations on for the show under Benecaster → Settings → Add-ons → the Community Integrations card → Active on. The Community Integrations Overview explains how members are kept in step.

What You Need

  • A Discord server you manage, with the roles you want to give already made. Benecaster gives and takes roles; it doesn’t create roles or channels.
  • A Discord application with a bot, made in the Discord Developer Portal. It’s free, and it belongs to you.
  • The bot in your server, with these permissions on its role:
    • Manage Roles, to give and take roles.
    • Create Invite, so Connect Discord can add subscribers to the server.
    • Kick, Approve, and Reject Members, only if you choose to remove former subscribers from the server.
  • An invite link that doesn’t expire, so subscribers can find the server.

Part 1: Set Up Discord

The Discord panel has an Open the Discord Developer Portal button that opens https://discord.com/developers/applications.

  1. Create an application in the Developer Portal. Its name is what subscribers see when they connect, so use your show’s name.
  2. Copy the bot token. On the application’s Bot page, copy its token. If you can’t see it, Reset Token there gives you a new one.
  3. Copy the Client ID and Client Secret from the application’s OAuth2 page.
  4. Add the bot to your server. On the OAuth2 page, open URL Generator, tick bot, then tick the permissions listed above under Bot Permissions. Open the link it makes and add the bot to your server.
  5. Put the bot’s role above the roles it gives. In your server, open Server Settings → Roles and drag the bot’s role above every role you want Benecaster to give, including a former-subscriber role. The bot can only manage roles below its own. Check the role has Manage Roles and Create Invite here too. In a new server everyone can create invites, which counts.
  6. Make an invite link with Invite People in your server, set never to expire, and copy it.

You add the Redirect URL to the OAuth2 page in Part 2, once Benecaster shows it to you.

Part 2: Connect the Show

  1. Go to Benecaster → Shows, click Settings on the show’s card, and choose Community. The Discord panel is at the top of Community platforms.
  2. Paste the token into Bot token, and the values from the OAuth2 page into Client ID and Client Secret. The token and the secret are stored encrypted and never shown again; once saved, their boxes read A token is saved. Enter a new one to replace it. and A secret is saved. Enter a new one to replace it. If you leave Client ID empty, Test connection fills it in.
  3. Paste your invite link into Invite link. Benecaster adds https:// if you leave it off. Any invite address works, including a custom one.
  4. Click Save. With a bot token saved, saving also tests the connection.
  5. Copy the Redirect URL with Copy, add it under Redirects on the application’s OAuth2 page, and save there. Without it, Connect Discord fails for your subscribers. The Redirect URL is the same for every show on your site.

The test checks the bot, the servers it’s in, its permissions, its role’s position, and the Client ID and Client Secret together. If the bot is in one server, that server is chosen for you. If it’s in several, choose this show’s server from Server and click Save. Choosing a different server clears your role choices, because roles belong to one server, and a former-subscriber choice goes back to Remove their roles only.

When everything works, the panel reads Connected to {your server’s name}. A token saved without a server reads A bot token is saved, but this show is not connected to a server yet. Anything wrong is listed as Problem: …, with what to do; see Troubleshooting.

Remove bot token and Remove Client Secret delete what’s saved. Without a bot token, nothing is sent to Discord for this show. Without a Client Secret, subscribers can’t connect.

Choosing Roles for Each Tier

Once the show is connected to a server and tested, the panel lists your server’s roles:

  • Roles for each tier: tick the roles each of the show’s tiers gets. A connected member gets every role ticked for their tier, and loses those roles when their tier no longer has them. A role the bot can’t manage shows as {role} (above the bot’s role; cannot be managed) and can’t be ticked: move the bot’s role higher, then test again.
  • Base subscriber role (optional): one role every connected member on any tier above gets, for general community access.
  • When a member leaves every tier above:
    • Remove their roles only, where every show starts;
    • Remove their roles and give them a former-subscriber role, then choose the Former-subscriber role;
    • Remove them from the server, which needs Kick, Approve, and Reject Members.

Click Save when you’re done. Saving changed tier roles or a changed base role updates every connected member in the background, adding and removing only the roles that differ. A changed leaving choice applies to people who leave from then on, not to anyone who has already left.

If the show has no tiers yet, the panel says This show has no tiers yet. Add them under Memberships → Tiers, then come back to map them.

Once the show is connected, the panel also counts the subscribers who have connected Discord, as {n} subscribers have connected Discord. A subscriber counts while they’re connected and on one of the show’s tiers.

What Subscribers See

On the account page, the show’s card has a Community section when the subscriber’s tier gets at least one role (a tier role or the base role):

  • Not connected yet: Connect your Discord account to join this show’s Discord server with your member roles. and a Connect Discord button. The button appears only once the show has a Client ID and Client Secret saved.
  • Connected: Connected to Discord as {their Discord name}. Your roles on this show’s server follow your membership. and Disconnect Discord.
  • Either way: Join the Discord server, which opens your invite link, when one is saved.

Connect Discord opens Discord’s own screen, which names your application and asks to read the subscriber’s Discord account and to join servers for them. When they agree, they come back to the account page, which says Your Discord account is connected. You are added to this show’s Discord server with your member roles within a few minutes. Benecaster then adds them to your server with their roles. Someone already in the server is left as they are and gets their roles.

Other messages on the card after the round trip:

Message When
Your Discord account is disconnected. The roles your membership gave you on this show’s server are removed within a few minutes. They clicked Disconnect Discord.
Discord was not connected: you cancelled on Discord’s screen. Nothing changed. They cancelled on Discord’s screen.
That Discord connection took too long or was started in another window. Choose Connect Discord again. More than ten minutes passed, or the connection was started elsewhere.
Your previous Discord account is still being disconnected. Try again in a few minutes. They connected a different Discord account while roles were still coming off the old one.
Connecting Discord is not available for this show right now. The show isn’t fully connected to Discord, has no Client ID or Client Secret saved, or the subscriber’s tier gets no role.
Discord could not connect your account. Try again in a few minutes. Discord refused the connection or couldn’t be reached. Check the Client ID and Client Secret with Test connection.

If the Redirect URL isn’t saved on the application’s OAuth2 page, Discord shows an error on its own screen and the subscriber never comes back to your site.

Subscribers connect separately for each show that has a Discord server, and Disconnect Discord on one card leaves other shows connected.

Add {{discord_invite_url}} to any of this show’s Benecaster emails, such as the welcome email, to include your invite link. It’s listed under Merge tags on the Community tab with Copy.

What Happens on Discord

  • Subscribing. A subscriber gets their roles once they’ve connected Discord. Until then, nothing happens on Discord for them, and they can still join with the invite link.
  • Changing tier. Only the roles that differ change.
  • Leaving. The roles Benecaster gave are taken away, then the show’s leaving choice applies. Their connection stays, so if they subscribe again their roles come back and any former-subscriber role comes off. Someone who was removed from the server and subscribes again rejoins with Join the Discord server, and their roles follow on the next retry.
  • Disconnecting. Disconnect Discord ends the connection at once and takes back the roles Benecaster gave, with no former-subscriber role and no removal from the server.
  • Only what Benecaster gave is taken away. A role you gave someone by hand stays.

If a connected subscriber isn’t in the server, Member sync shows This member connected Discord but has not joined the server yet. They get their roles on the next retry after they join. They’re retried on the usual schedule, so their roles arrive soon after they join.

The Setup Wizard Step

Benecaster’s setup wizard includes Connect your Discord server. It says Create an application and its bot in the Discord Developer Portal, then add the bot to your server with the Manage Roles and Create Invite permissions., links Open the Discord Developer Portal, and has Bot token, Client ID and Client Secret boxes. Test connection saves them for the show and tests them. If the bot is in several servers, a Server list appears; choosing one saves and tests again. Problems are listed as on the Community tab, and once saved the step shows the Redirect URL to add on the OAuth2 page.

Continue is held until the show is connected to a server, which shows Connected to {server}. Choose which roles each tier gets on this show’s Community settings. Choose I’ll set this up in Settings. to skip it.

The step doesn’t choose roles: do that on the show’s Community tab afterwards. If you install the add-on after finishing setup, each show it’s switched on for that isn’t connected to a Discord server is offered the step once. Connecting Discord on the show’s Community tab takes the step back.

Troubleshooting

Test connection lists every problem it finds:

Problem What to do
The bot does not have the Manage Roles permission on {server}, so it cannot give or take any role. In Server Settings → Roles, give the bot’s role Manage Roles, then test again.
The bot does not have the Create Invite permission on {server}, so Connect Discord cannot add subscribers to the server: they have to join with the invite link before their roles arrive. Give the bot’s role Create Invite, then test again.
Removing former subscribers from the server needs the Kick, Approve, and Reject Members permission, which the bot does not have on {server}. Give it to the bot’s role, or choose another leaving option.
The bot can only manage roles below its own, and these are not: {roles}. In Server Settings → Roles, drag the bot’s role above them, then test again.
{n} roles chosen on this tab no longer exist on the server. Choose them again, then save.
The bot is not in any server yet. Add the bot with OAuth2 → URL Generator (Part 1, step 4), then test again.
The bot is in more than one server. Choose this show’s server, then save. Choose from Server and save.
The bot is not in the server chosen for this show. Add the bot to that server, or choose another, then save.
The Client ID belongs to a different Discord application from the bot token. Use the Client ID and Client Secret of the bot’s own application.
No Client Secret is saved. Subscribers need it to connect their Discord account from their account page. Save the Client Secret.
Discord did not accept the Client ID and Client Secret together. Copy both again from the OAuth2 page.

Other messages from the panel and from Member sync:

Message What to do
Discord did not accept this bot token. Copy it again from the Bot page of your application in the Discord Developer Portal; Reset Token there gives a new one. Paste the token again and save.
Discord refused the bot access. Check the bot is still in your server and its role has the permissions it needs. Check the bot is in the server and its role’s permissions, then test again.
Discord could not find what was asked for. The server, member or role may have been deleted. Test again and check your role choices.
WordPress could not reach Discord. Check that this site can make outgoing connections, then try again. Your host may be blocking outgoing connections. Ask them.
Discord asked us to slow down. Wait a minute, then test again. Wait a minute. During a sync, the member is retried shortly by itself.
Discord answered with an error (HTTP {code}). Try again in a few minutes. A problem on Discord’s side. Members are retried by themselves.
This show has no Discord bot token saved. Save one on the show’s Community tab. Save a bot token.
The Client ID is a number of 17 to 20 digits. Copy it from the OAuth2 page of your application in the Discord Developer Portal. Paste the Client ID again.
Enter your Discord server’s invite link, for example https://discord.gg/abc123. Invite link isn’t a web address. Correct it and save.
The bot token or Client Secret could not be saved. Check that this show has been saved at least once, then try again. Save the show’s settings once, then save again.

A member who keeps failing shows as Failed under Member sync after the last retry. Fix the cause, then click Resync now.

Privacy and Removing the Add-on

When a subscriber connects, your site keeps their Discord user ID and display name, and a list of the roles it gave them, so it takes away only those. Permission to add them to your server is used once, in the minutes after they connect, and then deleted. An erasure ends their connection and takes back those roles, with no former-subscriber role and no removal from the server. See Privacy and Data Handling.

Deleting the add-on from Plugins deletes the saved bot token and Client Secret and removes nobody from your server.

See Also

Need this built rather than just documented? See our services →

Last updated