Button roles
Post a message with buttons that let members add or remove roles with one click, using the dashboard or the /buttonrole command.
On this page
- Before you start
- Set it up
- Settings explained
- 1. Message
- 2. Buttons
- 3. Message text (optional)
- Your button messages
- Commands
- Placeholders
- Examples
- Ping roles with the default embed
- Your own text as an embed
- Editing and deleting
- Premium
- Troubleshooting
- The message never appears
- Clicking a button says "I cannot assign that role"
- "This button points at a privileged role"
- Saving says the role or channel isn't valid
- My new buttons joined an old message
- Related
Button roles let members pick their own roles. Buddy posts a message with a button for each role: clicking a button gives the member that role, and clicking it again removes it. They're perfect for ping roles, interest roles, pronouns, regions or game roles, and they save your staff from handing roles out by hand.
Before you start#
Anyone who can see the message can click a button, so Buddy won't put a role with
Administrator, Manage Server or Manage Roles on a button, and never hands out
@everyone or roles managed by a bot or integration. Saving such a role shows an error, and an
older button that points at one stops working.
Create the roles first and decide which channel the message goes in. A #roles or
#get-roles channel where members can read but not type works well.
Set it up#
It's under Roles in the sidebar.
In Create button roles, under 1. Message, pick Create a new message (Discord Buddy will post it). Then choose the Channel.
Under 2. Buttons, fill in a Label, pick a Style and choose the Role. Click Add another button for each extra role.
Under 3. Message text (optional), switch on Add a custom message with the buttons, write your Message content and choose Regular message or Embed in Message type. Leave it off to use the default embed.
Check the Live preview, then click Add button roles. The message shows up in Discord within about a minute.
Settings explained#
1. Message#
| Option | What it does |
|---|---|
| Create a new message (Discord Buddy will post it) | Buddy posts a new message with your buttons. All buttons you save together share one message, in the order you listed them. With the default embed, new buttons also join Buddy's most recent default button message in that channel while it has room. |
| Add buttons to an existing Discord Buddy message (paste Message ID) | Adds buttons to a message Buddy already posted. Paste its Message ID. |
| Update a message already set up (select it from the list below) | Pick a message under Your button messages and click Use this message to load its buttons and text into the form, then change or add to them. |
| Channel | Where the message is, or where Buddy should post it. |
| Message ID | The message to add buttons to. Leave it blank for a new message. |
Buttons can only be added to messages Discord Buddy posted. If the Message ID isn't a Buddy message in the chosen channel, Buddy posts a new message instead.
How to copy a Message ID
- In Discord, open User Settings → Advanced and turn on Developer Mode.
- Right-click the message (or long-press on mobile) and choose Copy Message ID.
2. Buttons#
| Setting | What it does | Default |
|---|---|---|
| Label | The button text, up to 80 characters. Leave it empty to use the role's name. | Role name |
| Style | The button color: Primary (blurple), Secondary (grey), Success (green) or Danger (red). | Primary |
| Role | The role the button toggles. | — |
3. Message text (optional)#
| Setting | What it does | Default |
|---|---|---|
| Add a custom message with the buttons | Off: Buddy uses its default embed, "Click a button below to toggle a role." with each role listed. On: your own text. | Off |
| Message content | Your text, up to 1,500 characters. Supports Discord markdown and the tags below. | Empty |
| Message type | Regular message (plain text) or Embed (your text in an embed). | Regular message |
Your button messages#
Lists every button message, with how many buttons each has. Click one to see its buttons in the table, then use the pencil to edit a button or the trash icon to delete it.
Commands#
You can also create a button role from Discord. It needs the Manage Roles permission, and you can only use roles below your own highest role (the server owner can use any role).
/buttonrole <role> [style] [message] [embed] Manage RolesCreate a button that toggles a role.
/buttonrole posts in the channel you use it in, labels the button with the role's name, and
counts toward the same limit as the dashboard. Without a custom message, it adds the button to
Buddy's most recent default button message in that channel if there's room.
Placeholders#
Use these in Message content (or the message option of /buttonrole). The tag buttons under
the text box insert them for you.
| Placeholder | Becomes | Example |
|---|---|---|
{everyone} | @everyone | @everyone |
{role:ROLE_ID} | A mention of that role | @Gamer |
{user:USER_ID} | A mention of that user | @Sam |
{channel:CHANNEL_ID} | A link to that channel | #rules |
Examples#
Ping roles with the default embed#
Leave Add a custom message with the buttons off and add three buttons:
| Label | Style | Role |
|---|---|---|
| Announcements | Primary | @Announcements |
| Events | Success | @Events |
| Giveaways | Secondary | @Giveaways |
Announcements Events Giveaways
When someone clicks Events, only they see Buddy's reply:
You have been given the Events role!
Clicking it again replies "Removed Events role."
Your own text as an embed#
Switch on Add a custom message with the buttons, choose Embed, and write:
**Pick your platform** 🎮
Click a button to get pinged for game nights on that platform.
Click it again to remove the role. Questions? Ask in {channel:CHANNEL_ID}.Editing and deleting#
- Edit a button: click the pencil next to it. In Update button role you can change the Label, Style, Role or Message ID, and switch Use a custom message on or off. Click Save changes. Discord updates within about a minute.
- Change the text or add buttons: under Your button messages, select the message and click Use this message. The form switches to Update a message already set up with its buttons and text filled in. Make your changes and click Add button roles. To go back to the default embed, edit a button and click Remove custom message.
- Delete a button: click the trash icon and confirm. Buddy removes it from the message within about a minute, and takes its role off the default embed's list too. The message itself stays.
Premium#
Free servers can have 10 button roles (each button counts as one) and up to 25 buttons per message, which is Discord's own maximum (5 rows of 5). Premium plans raise the button role limit. The Your plan card at the top of the page shows how many you've used. See plan limits for each plan.
Troubleshooting#
The message never appears#
- Wait a minute. Buddy checks for new and changed button roles regularly.
- Give Buddy View Channel, Send Messages and Embed Links in the channel.
- Check the role still exists and Buddy can see it.
Clicking a button says "I cannot assign that role"#
- Buddy's role must be above the button's role in Server Settings → Roles.
- Buddy needs Manage Roles. Without it the reply is "I do not have permission to manage roles."
"This button points at a privileged role"#
The role has Administrator, Manage Server or Manage Roles. Remove that permission from the role, or edit the button to use a different role.
Saving says the role or channel isn't valid#
- "Roles with Administrator, Manage Server or Manage Roles permission can not be self-assigned." Pick a role without those permissions.
- "That role was not found in this server" or a role/channel missing from the list: run
/setupin Discord, choose Update Channels and Roles for Website, and reload the page. - "Button role limit reached": delete a button role or upgrade your plan.
- "You can only add up to 25 buttons per message": start a new message for the rest.
My new buttons joined an old message#
With the default embed, Buddy adds new buttons to its latest default button message in that channel until it's full. To start a separate message, switch on Add a custom message with the buttons and give it its own text.