Как сделать кнопки discord py

5

Buttons

On May 26, 2021, Discord added a new interaction called buttons. Instead of reactions, bots could now send buttons and users could use them to interact with bots. This opened up a whole new world of possibilities for bots. Soon after, developers made calculators, polls, and games like blackjack, UNO, and even Minecraft! Buttons provided a clear and easy to use interface for interacting with bots.

So, let's learn how you can add buttons to your bot!

Concept​

Buttons weren't the only update to the interactions system in Discord. Discord also added Select Menus and Modal Dialogs, both of which work very similarly to buttons.

These UI elements reside in a "view". To learn more about views, please refer to the interactions page.

Usage Syntax​

Let's see how to create a simple responsive button.

Using this command should return the following message:

BobDotCom used / button

As you can see, we create a class called MyView that subclasses discord.ui.View .

Then, we add a function called button_callback to the MyView class with the decorator discord.ui.button . This decorator adds a button to a component. This function takes two arguments: the button that was clicked and the interaction. These arguments are passed to the function when the button is clicked by the module. We use the interaction.response.send_message function to send a message to the channel where the interaction was sent.

Finally, we create a global slash command called button that sends the message, along with the view that contains a button.

This is the basic syntax of creating a button. What you create with it is up to you. You can worry about making your button do amazing things, while Pycord handles the rest!

Button Styles​

Check out the discord.ButtonStyle class for more information.

You can set a button's style by adding the style argument in the discord.ui.button decorator.

Action Rows​

We have discussed that Views can have 5 rows. Each row has 5 slots, and each button takes up 1 slot. So, how do we move the buttons to another row?

This can be done by specifying the row argument in the discord.ui.button decorator.

The row argument

The row argument specifies the relative row this button belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults to None, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).

Disabling Buttons​

Pre-Disabled Buttons​

Disabling Buttons on Press​

• Disabling a single component
• Disabling all the components of a view

Timeouts​

Sometimes, you want to have a button that is disabled after a certain amount of time. This is where timeouts come in.

• Specifying time when creating a view object
• Specifying the time when subclassing

Here, we loop through all the children of the view (buttons and select menus in the view) and disable them. Then, we edit the message to show that the timeout was reached.

If the on_timeout coroutine is not present, the components will simply stop working after the specified time.

Persistent Views​

Sometimes, instead of a button that is disabled after a certain amount of time, you want to have a button that is always working.

Normally, when the bot goes offline, all of its buttons stop working. You will be able to see the buttons, but nothing will happen when you press them. This is a problem if you are trying to create a self-role system with buttons, for example. This is where persistent views come in.

Persistent views work forever. When the bot goes offline, the buttons will stop working. When the bot comes back online, however, the buttons will start working again.

In a Persistent View, the timeout must be set to None and all the children in the view much have a custom_id attribute set.

How many buttons can I have in a message?​

Each message can have a maximum of 25 buttons. Views can have up to 5 rows, and each row has 5 slots. A button takes up one slot, while a select menu takes up all five slots.

Can I add more than one view to a message?​

No. As a Discord limitation, you can only have one view per message.

Why are UI Components so confusing?​

They cannot be simple like commands. This system makes them flexible and doesn't limit your imagination. There are loads of different ways you can use UI Components. For example, you could subclass Buttons or Select Menus and add them to a view using the view's add_item function.

UI Components aren't hard to use if you know Python. We recommend learning Object-Oriented Programming with Python.

What is OOP? What is subclassing? ​

OOP (object-oriented programming) is a programming paradigm that allows you to create objects that have their own properties and methods. Almost everything in python is an object or a class. discord.Embed and discord.ui.View are both classes. When you use view = discord.ui.View() to create a view, you are actually creating an object of type discord.ui.View .

Subclassing is a Python OOP concept. It means that you can create a class that inherits from another class. In other words, the class that subclasses another class can inherit all the methods and attributes of that class.

We highly recommend you learn about basic Python concepts like classes and inheritance before you start learning Pycord.

Resources:

Do buttons need any special permissions?​

No new permissions are needed for either the bot or the server to allow bots to use buttons.

Should I replace reactions with buttons for my bot?​

That is up to you. Buttons do provide a cleaner interface for your bot and are easier to use.

Name already in use

discord-py-guide / ui_elements.md

• Go to file T
• Go to line L
• Copy path
• Copy permalink

1 contributor

Users who have contributed to this file

• Open with Desktop
• View raw
• Copy raw contents Copy raw contents

Copy raw contents

Copy raw contents

Работа с UI-Элементами

Если вы все еще пользуетесь библиотекой discord-py , то для работы с материалами этого руководства вам придется обновиться на более актуальный форк этой библиотеки. Конкретно здесь пойдет речь про PyCord . Подробнее про смысл перехода на эту библиотеку здесь.

Если кто не знал, в дискорд вместе со slash-командами уже давно завезли графические элементы, такие как:

Все эти элементы хранятся в модуле discord.ui и работать с ними очень просто. Для просмотра документации нажмите на интересующий элемент списка выше

Для начала немного теории. Кнопки и выпадающие списки являются такими же элементами сообщения ( discord.Message ), как и вложения (видео/изображения/файлы) ( discord.Message.attachments ), Embed-формы ( discord.Message.embeds ) и прочие доп. элементы кроме основного текста.

Поэтому, когда вы отправляете сообщение с кнопкой, эту кнопку нужно куда-то размещать. Для этого в PyCord имеется специальный класс discord.ui.View , который как раз таки будет содержать в себе все созданные в коде компоненты.

То есть, логика такая:

1. Создаем экземпляр View()
2. Затем создаем объекты кнопок/выпадающих списков
3. Устанавливаем их внутрь формы View и уже эту форму передаем как параметр при отправке сообщения:

Дальше на конкретных примерах будет понятнее.

Работа с кнопками

Кнопки имеют различные стили, которые хранятся в классе discord.ButtonStyle :

Импортируем из модуля discord.ui класс кнопки и класс формы для кнопки:

Пусть кнопка создается при вызове команды /create_button :

Для начала создадим форму discord.ui.View , в которую будем размещать кнопку. Из документации видим, что по умолчанию параметр timeout имеет значение 180.0 , что означает, что дискорд будет передавать боту информацию о нажатии на кнопку только в течение 180 секунд, а потом просто забудет про нее. Если вам нужно, чтобы бот работал с кнопкой все время, пока он запущен, то значение параметра следует установить как None

Теперь давайте создадим кнопку. Из документации по классу discord.ui.Button видим, что можем передать в конструктор класса парамтры:

• label : str — текст кнопки
• emoji : discord.Emoji / str — эмоджи рядом с текстом
• style : discord.ButtonStyle — стиль кнопки
• custom_id : str — пользовательский идентификатор кнопки (для удобства обработки нажатий)
• disabled : bool — состояние кнопки (включена или выключена)

И другие параметры, про которые можно почитать в документации.

Создаем объект кнопки:

Обработчик нажатия на кнопку

Кнопка есть, теперь надо сделать, чтобы при нажатии на нее вызывалась какая-то функция. Сделаем, чтобы при нажатии на кнопку, текст сообщения отображал последнего пользователя, который ее нажал.

Реализуем это в функции button_callback :

Из документации видим, что при нажатии на кнопку, в обработчик будет передаваться аргумент interaction ( discord.Interaction ), из которого можно получить пользовательский идентификатор кнопки, пользователя, который нажал на кнопку и многое другое.

Не забываем указать, что функция принимает этот аргумент interaction .

Далее присваиваем кнопке обработчик нажатия:

Добавляем ее в форму view :

И отправляем ответ на команду:

Должно получиться как-то так (код с пояснениями здесь):

Результат:

Работа с выпадающими списками

Импортируем из модуля discord.ui класс выпадающего списка и класс формы для его размещения:

Пусть выпадающий список создается при вызове команды /create_select_menu :

Для начала создадим форму discord.ui.View , в которую будем размещать выпадающий список. Из документации видим, что по умолчанию параметр timeout имеет значение 180.0 , что означает, что дискорд будет передавать боту информацию о выборе пункта списка только в течение 180 секунд, а потом просто забудет про него. Если вам нужно, чтобы бот работал со списком все время, пока он запущен, то значение параметра следует установить как None

Теперь давайте создадим выпадающи список. Из документации по классу discord.ui.Select видим, что можем передать в конструктор класса парамтры:

• custom_id : str — пользовательский идентификатор списка (для удобства обработки выбора значения)
• disabled : bool — состояние списка (включен или выключен)
• min_values : int — минимальное количество элементов, которые должен выбрать пользователь
• max_values : int — максимальное количество элементов, которые может выбрать пользователь

И другие параметры, про которые можно почитать в документации.

Создаем объект выпадающего списка:

Теперь, когда мы имеем пустой выпадающий список, его нужно наполнить элементами, которые сможет выбирать пользователь. Элементы должны быть экземплярами класса discord.SelectOption .

Импортируем этот класс:

И рассмотрим список параметров его конструктора:

• default : bool — будет ли этот параметр выбран в качестве параметра по умолчанию
• description : str — описание параметра
• label : str — название параметра
• emoji : discord.Emoji / str — эмоджи, который будет отображаться рядом с названием
• value : str — значение параметра, которое не видят пользователи (если не указано, то принимает значение параметра label )

Теперь создадим список параметров. Первый будет выбран по умолчанию ( default=True )

Добавляем их в список:

Обработчик выбора параметра

Реализуем обработчик выбора параметра. Сделаем так, чтобы при выборе элемента бот изменял текст сообщения на «<Пользователь> выбрал <выбор>»

How to make a button in discord.py?

I am trying to make a discord bot to update a status message, but I can’t get buttons/dropdown menus to work.

I got the error:

1 Answer 1

You haven’t made a View. Make it like this:

You can also make it another way, but that is the way I make it. Now you made a button, but you have to assign the view to your message where you send the embed.

Right now the button doesn’t do anything. Here is an example of how you can make it send a message once you click it:

Components

listening_component ( custom_id , messages = None , users = None , component_type : Optional [ Literal [ ‘button’ , ‘select’ ] ] = None , check : Callable [ [ Union [ discord_ui.receive.ButtonInteraction , discord_ui.receive.SelectInteraction ] ] , bool ] = empty_check ) 

Decorator for add_listening_component

The custom_id of the components to listen to

messages: List[ discord.Message | int str ], Optional

A list of messages or message ids to filter the listening component

users: List[ discord.User | discord.Member | int | str ], Optional

A list of users or user ids to filter

component_type: Literal[ ‘button’ | ‘select’ ]

What type the used component has to be of (select: SelectMenu, button: Button)

check: function , Optional A function that has to return True in order to invoke the listening component

The check function takes to parameters, the component and the message

callback: method(ctx)

The asynchron function that will be called if a component with the custom_id was invoked

There will be one parameters passed

Note

ctx is just an example name, you can use whatever you want for it

A list of components that are listening for interaction

async put_listener_to ( target_message , listener ) 

Adds a listener to a message and edits it if the components are missing

The message to which the listener should be attached

The listener which should be put to the message

Removes a listening component

The listening component which should be removed

Removes all listening components for a custom_id

The custom_id for the listening component

async send ( channel , content = . , * , tts = False , embed = . , embeds = . , file = . , files = . , delete_after = . , nonce = . , allowed_mentions = . , reference = . , mention_author = . , components = . ) → discord_ui.receive.Message 

Sends a message to a textchannel

channel: discord.TextChannel | int | str

The target textchannel or the id of it

content: str , optional

The message text content; default None

tts: bool , optional

True if this is a text-to-speech message; default False

embed: discord.Message , optional

Embedded rich content (up to 6000 characters)

embeds: List[ discord.Embed ], optional

Up to 10 embeds; default None

file: discord.File , optional

A file sent as an attachment to the message; default None

files: List[ discord.File ], optional

A list of file attachments; default None

delete_after: float , optional

After how many seconds the message should be deleted; default None

nonce: int , optional

The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value; default None

allowed_mentions: discord.AllowedMentions , optional

A list of mentions proceeded in the message; default None

reference: discord.MessageReference | discord.Message , optional

A message to refer to (reply); default None

mention_author: bool , optional

True if the author should be mentioned; default None

A list of message components included in this message; default None

Channel is not an instance of discord.abc.GuildChannel , discord.abc.PrivateChannel:, :class:`int , str

Returns the sent message

send_webhook ( webhook , content = . , * , wait = False , username = . , avatar_url = . , tts = False , files = . , embed = . , embeds = . , allowed_mentions = . , components = . ) → Optional [ discord.webhook.WebhookMessage ] 

Sends a webhook message

The webhook which will send the message

content: str , optional

the message contents (up to 2000 characters); default None

wait: bool , optional

if True , waits for server confirmation of message send before response, and returns the created message body; default False

username: str , optional

override the default username of the webhook; default None

avatar_url: str , optional

override the default avatar of the webhook; default None

tts: bool , optional

true if this is a TTS message; default False

A list of files which will be sent as attachment

Embed rich content, optional

embeds: List[ discord.Embed ], optional

embedded rich content; default None

allowed_mentions: discord.AllowedMentions , optional

allowed mentions for the message; default None

the message components to include with the message; default None

The message which was sent, if wait was True, else nothing will be returned

Events

We got 3 events to listen for your client

component 

This event will be dispatched whenever a component was invoked

A sole parameter will be passed

ComponentContext : The used component

button 

This event will be dispatched whenever a button was pressed

A sole parameter will be passed:

select 

This event will be dispatched whenever a value was selected in a SelectInteraction

A sole paremeter will be passed

SelectInteraction : The menu where a value was selected

Components

Button

custom_id: str , optional A identifier for the button, max 100 characters

If no custom_id was passed, a random 100 character string will be generated

label: str , optional

Text that appears on the button, max 80 characters; default ​ (“empty” char)

color: str | int , optional

The color of the button; default “blurple”

emoji: discord.Emoji | str , optional

The emoji displayed before the text; default MISSING

new_line: bool , optional

Whether a new line should be added before the button; default False

disabled: bool , optional

Whether the button is disabled; default False

A value you want to set is not an instance of a valid type

The lenght of a value is not valid

A value is out of its valid range

The color you provided is not a valid color alias

LinkButton

A ui-button that will open a link when it’s pressed

A url which will be opened when pressing the button

label: str , optional

Text that appears on the button, max 80 characters; default ​ (“empty” char)

emoji: discord.Emoji | str , optional

Emoji that appears before the label; default MISSING

new_line: bool , optional

Whether a new line should be added before the button; default False

disabled: bool , optional

Whether the button is disabled; default False

A value you want to set is not an instance of a valid type

The lenght of a value is not valid

A value is out of its valid range

The color for the button

property component_type : discord_ui.enums.ComponentType 

The component type

The complete content in the button (“ ”)

The mention of the emoji before the text

Note

For setting the emoji, you can use a str or discord.Emoji

The label displayed on the button

The link which will be opened when the button was pressed

ButtonStyle

SelectMenu

A ui-dropdown selectmenu

A list of options to select from

custom_id: str , optional

The custom_id for identifying the menu, max 100 characters

min_values: int , optional

The minimum number of items that must be chosen; default 1 , min 0, max 25

max_values: int , optional

The maximum number of items that can be chosen; default 1 , max 25

placeholder: str , optional

A custom placeholder text if nothing is selected, max 100 characters; default MISSING

default: int | range , optional

The position of the option that should be selected by default; default MISSING

disabled: bool , optional

Whether the select menu should be disabled or not; default False

property component_type : discord_ui.enums.ComponentType 

The component type

A custom identifier for this component

The option selected by default

Whether the selectmenu is disabled or not

The maximum number of items that can be chosen; default 1, max 25

The minimum number of items that must be chosen; default 1, min 0, max 25

Custom placeholder text if nothing is selected

Selects the default selected option

position: int | range

The position of the option that should be default. If position is of type range , it will iterate through it and disable all components with the index of the indexes.

SelectOption

An option for a select menu

The dev-define value of the option, max 100 characters

The user-facing name of the option, max 25 characters; default ​ (“empty” char)

description: str , optional

An additional description of the option, max 50 characters

emoji: discord.Emoji | str , optional

Emoji appearing before the label; default MISSING

Whether this option should be selected by default in the select menu; default False

A value you want to set is not an instance of a valid type

The lenght of a value is not valid

A value is out of its valid range

The complete option content, consisting of the emoji and label

Whether this option is selected by default in the menu or not

property description : str 

A short description for the option

The mention of the emoji before the text

Note

For setting the emoji, you can use a str or a discord.Emoji

The main text appearing on the option

A unique value for the option, which will be usedd to identify the selected value

Interactions

Message

A discord.Message optimized for components

Attaches a listener to this message after it was sent

The listener that should be attached

The button components in the message

The components in the message

async disable_components ( index=<discord_ui.tools._All object> , disable=True , **fields ) 

Disables component(s) in the message

index: int | str | range | List[ int | str ], optional

Index(es) or custom_id(s) for the components that should be disabled or enabled; default all components

disable: bool , optional

Whether to disable ( True ) or enable ( False ) components; default True

Other parameters for editing the message (like content= , embed= )

async edit ( content = . , * , embed = . , embeds = . , attachments = . , suppress = . , delete_after = . , allowed_mentions = . , components = . ) 

Edits the message and updates its properties

If a paremeter is None , the attribute will be removed from the message

The new message content

The new embed of the message

embeds: List[ discord.Embed ]

The new list of discord embeds

attachments: List[ discord.Attachment ]

A list of new attachments

Whether the embeds should be shown

After how many seconds the message should be deleted

The mentions proceeded in the message

A list of components to be included the message

async put_listener ( listener ) 

Adds a listener to this message and edits the message if the components of the listener are missing in this message

The listener which should be put to the message

Removes the listener from this message

The select menus components in the message

async wait_for ( event_name : Literal [ ‘select’ , ‘button’ , ‘component’ ] , client , custom_id = None , by = None , check = empty_check , timeout = None ) → Union [ discord_ui.receive.ButtonInteraction , discord_ui.receive.SelectInteraction , discord_ui.receive.ComponentContext ] 

Waits for a message component to be invoked in this message

The name of the event which will be awaited [ "select" | "button" | "component" ]

event_name must be select for a select menu selection, button for a button press and component for any component

The discord client

custom_id: str , Optional

Filters the waiting for a custom_id

by: discord.User | discord.Member | int | str , Optional

The user or the user id by that has to create the component interaction

check: function , Optional A check that has to return True in order to break from the event and return the received component

The function takes the received component as the parameter

timeout: float , Optional

After how many seconds the waiting should be canceled. Throws an asyncio.TimeoutError Exception

The event name passed was invalid

The component that was waited for

ButtonInteraction

An interaction that was created by a Button

The ID of the bot application

The user who pressed the button

property channel : Union [ discord.abc.GuildChannel , discord.abc.PrivateChannel ] 

The channel where the interaction was created

The channel-id where the interaction was created

The component that created the interaction

The interaction’s creation time in UTC

The passed data of the interaction

async defer ( hidden = False ) 

This will acknowledge the interaction. This will show the (Bot is thinking…) Dialog

This function should be used if the bot needs more than 15 seconds to respond

Whether the loading thing should be only visible to the user; default False.

property guild : discord.guild.Guild 

The guild where the interaction was created

The guild-id where the interaction was created

The id of the interaction

The message in which the interaction was created

async respond ( content = None , * , tts = False , embed = None , embeds = None , file = None , files = None , nonce = None , allowed_mentions = None , mention_author = None , components = None , delete_after = None , listener = None , hidden = False , ninja_mode = False ) → Union [ Message , EphemeralMessage ] 

Responds to the interaction

content: str , optional

The raw message content

Whether the message should be send with text-to-speech

Embed rich content

embeds: List[ discord.Embed ]

A list of embeds for the message

The file which will be attached to the message

files: List[ discord.File ]

A list of files which will be attached to the message

The nonce to use for sending this message

Controls the mentions being processed in this message

Whether the author should be mentioned

A list of message components to be included

After how many seconds the message should be deleted, only works for non-hiddend messages; default MISSING

A component-listener for this message

Whether the response should be visible only to the user

If true, the client will respond to the button interaction with almost nothing and returns nothing

Returns the sent message

async send ( content = None , * , tts = None , embed = None , embeds = None , file = None , files = None , nonce = None , allowed_mentions = None , mention_author = None , components = None , delete_after = None , listener = None , hidden = False , force = False ) → Union [ discord_ui.receive.Message , discord_ui.receive.EphemeralMessage ] 

Sends a message to the interaction using a webhook

content: str , optional

The raw message content

tts: bool , optional

Whether the message should be send with text-to-speech

embed: discord.Embed , optional

Embed rich content

embeds: List[ discord.Embed ], optional

A list of embeds for the message

file: discord.File , optional

The file which will be attached to the message

files: List[ discord.File ], optional

A list of files which will be attached to the message

nonce: int , optional

The nonce to use for sending this message

allowed_mentions: discord.AllowedMentions , optional

Controls the mentions being processed in this message

mention_author: bool , optional

Whether the author should be mentioned

A list of message components to be included

delete_after: float , optional

After how many seconds the message should be deleted, only works for non-hiddend messages; default MISSING

listener: Listener , optional

A component-listener for this message

hidden: bool , optional

Whether the response should be visible only to the user

ninja_mode: bool , optional

If true, the client will respond to the button interaction with almost nothing and returns nothing

force: bool , optional

Whether sending the follow-up message should be forced. If False , then a follow-up message will only be send if .responded is True; default False

Returns the sent message

The token for responding to the interaction

The type of the interaction. See InteractionType for more information

SelectInteraction

An interaction that was created by a SelectMenu

The ID of the bot application

The user who selected the value

property channel : Union [ discord.abc.GuildChannel , discord.abc.PrivateChannel ] 

The channel where the interaction was created

The channel-id where the interaction was created

The interaction’s creation time in UTC

The passed data of the interaction

async defer ( hidden = False ) 

This will acknowledge the interaction. This will show the (Bot is thinking…) Dialog

This function should be used if the bot needs more than 15 seconds to respond

Whether the loading thing should be only visible to the user; default False.

property guild : discord.guild.Guild 

The guild where the interaction was created

The guild-id where the interaction was created

The id of the interaction

The message in which the interaction was created

async respond ( content = None , * , tts = False , embed = None , embeds = None , file = None , files = None , nonce = None , allowed_mentions = None , mention_author = None , components = None , delete_after = None , listener = None , hidden = False , ninja_mode = False ) → Union [ Message , EphemeralMessage ] 

Responds to the interaction

content: str , optional

The raw message content

Whether the message should be send with text-to-speech

Embed rich content

embeds: List[ discord.Embed ]

A list of embeds for the message

The file which will be attached to the message

files: List[ discord.File ]

A list of files which will be attached to the message

The nonce to use for sending this message

Controls the mentions being processed in this message

Whether the author should be mentioned

A list of message components to be included

After how many seconds the message should be deleted, only works for non-hiddend messages; default MISSING

A component-listener for this message

Whether the response should be visible only to the user

If true, the client will respond to the button interaction with almost nothing and returns nothing

Returns the sent message

The list of the selected options

selected_values : List [ str ] 

The list of raw values which were selected

async send ( content = None , * , tts = None , embed = None , embeds = None , file = None , files = None , nonce = None , allowed_mentions = None , mention_author = None , components = None , delete_after = None , listener = None , hidden = False , force = False ) → Union [ discord_ui.receive.Message , discord_ui.receive.EphemeralMessage ] 

Sends a message to the interaction using a webhook

content: str , optional

The raw message content

tts: bool , optional

Whether the message should be send with text-to-speech

embed: discord.Embed , optional

Embed rich content

embeds: List[ discord.Embed ], optional

A list of embeds for the message

file: discord.File , optional

The file which will be attached to the message

files: List[ discord.File ], optional

A list of files which will be attached to the message

nonce: int , optional

The nonce to use for sending this message

allowed_mentions: discord.AllowedMentions , optional

Controls the mentions being processed in this message

mention_author: bool , optional

Whether the author should be mentioned

A list of message components to be included

delete_after: float , optional

After how many seconds the message should be deleted, only works for non-hiddend messages; default MISSING

listener: Listener , optional

A component-listener for this message

hidden: bool , optional

Whether the response should be visible only to the user

ninja_mode: bool , optional

If true, the client will respond to the button interaction with almost nothing and returns nothing

force: bool , optional

Whether sending the follow-up message should be forced. If False , then a follow-up message will only be send if .responded is True; default False

Returns the sent message

The token for responding to the interaction

The type of the interaction. See InteractionType for more information

Tools

Converts a list of components to a dict that can be used for other extensions