Examples¶

The following examples should work out-of-the-box and assume you have your bot set up.

For setup, see the Bot setup guide.

Looking for examples about older features? Check out Legacy Examples

About these examples

Each example is self-contained and can be copied directly into your bot between setup and bot.run().

Beware of similar command names!

Table of Contents¶

Minimal Slash Command
Building with Discord's V2 Components
Building and Responding to Components
Building and Responding to Select Components
Building and responding to a Modal
Responding to an Event
Adding Attachments

Minimal Slash Command¶

Demonstrates responding to a slash command. Sends the message Hello, {user}! when /example is sent.

@client.command(
    command=discord.SlashCommand(name='example', description='Demonstrate the minimal slash command!'),
    guild_id=GUILD_ID # must be a guild ID your bot is in!
)
async def on_example(bot: discord.Client, event: discord.InteractionEvent):
    await event.interaction.respond(f'Hello, {event.interaction.member.user.username}!')

Guild vs Global

Use global commands for production bots (may take up to 1 hour to appear).
Use guild commands for instant registration within a guild.

Building with Discord's V2 Components¶

Demonstrates building the V2 component: a container.

@client.command(
    command=discord.SlashCommand(name='example', description="Demonstrate using Discord's new component system!"),
    guild_id=GUILD_ID # must be a guild ID your bot is in!
)
async def on_example(bot: discord.Client, event: discord.InteractionEvent):
    await event.interaction.respond(
        discord.MessageBuilder()
            .add_container(discord.Container()
                .set_color('#d4af37')
                .add_text_display("It's dangerous to go alone!")
                .add_separator()
                .add_text_display('Take this.')
            )
            .set_flags(is_components_v2=True) # THIS IS A NECESSITY!
    )

Building and Responding to Components¶

Demonstrates building a button and responding to a user pressing it.

import random

@client.component('best_custom_id')
async def route(bot: discord.Client, event: discord.InteractionEvent):
    adj = random.choice(['wonderous', 'beautiful', 'charming', 'vibrant', 'sinister'])
    await event.interaction.update(
        message=discord.MessageBuilder(content=f'Hello *{adj}* world!')
            .add_row(discord.ActionRow()
                .add_button(style='Primary', label='Press me again!', custom_id='best_custom_id', emoji='❤️‍🔥')
            )
    )

@client.command(
    command=discord.SlashCommand(name='example', description='Demonstrate using components!'), 
    guild_id=GUILD_ID # must be a guild ID your bot is in!
)
async def on_example(bot: discord.Client, event: discord.InteractionEvent):
    await event.interaction.respond(
        message=discord.MessageBuilder(content='Hello world!')
            .add_row(discord.ActionRow()
                .add_button(style='Primary', label='Press me!', custom_id='best_custom_id', emoji='❤️')
            )
    )

Building and Responding to Select Components¶

Demonstrates building a string select component and responding.

@client.component(custom_id='on_string_select')
async def on_string_select(bot: discord.Client, event: discord.InteractionEvent):
    await event.interaction.respond(f'You selected option: **{event.data.values[0]}**!')

@client.command(
    command=discord.SlashCommand(name='example', description='Demonstrate the select components!'), 
    guild_id=GUILD_ID # must be a guild ID your bot is in!
)
async def on_example(bot: discord.Client, event: discord.InteractionEvent):
    await event.interaction.respond(
        discord.MessageBuilder("Select an option:")
            .add_row(discord.ActionRow()
                .string_select(
                    discord.StringSelect(custom_id='on_string_select', placeholder='Choose an option...')
                        .add_option(label='Caterpillar', emoji='🐛', value='Caterpillar', description='(best option)')
                        .add_option(label='Butterfly', emoji='🦋', value='Butterfly')
                        .add_option(label='Ant', emoji='🐜', value='Ant')
                )
            )
    )

Demonstrates using the modal feature and extracting the user's responses.

@client.component(custom_id='modal_one')
async def modal_one(bot: discord.Client, event: discord.InteractionEvent):
    label = event.data.get_modal_data('bug_select')[0]
    details = event.data.get_modal_data('bug_explanation')

    await event.interaction.respond(
        f"Form Data: \nSelect: {label} \nDetails: {details}",
        ephemeral=True
    )

@client.command(
    command=discord.SlashCommand(name='example', description='Demonstrate the modal request/response!'),
    guild_id=GUILD_ID # must be a guild ID your bot is in!
)
async def on_example(bot: discord.Client, event: discord.InteractionEvent):
    select_label = (discord.Label(label="What's your favorite bug?")
        .string_select(
            discord.StringSelect(custom_id='bug_select', placeholder='Choose...', required=True)
                .add_option(label='Ant', value='Ant', description='(best option)', emoji='🐜')
                .add_option(label='Butterfly', value='Butterfly', emoji='🦋')
                .add_option(label='Caterpillar', value='Caterpillar', emoji='🐛')
        )
    )

    inp_label = (discord.Label(label='Why is it your favorite?', description='Provide as much detail as possible!')
        .text_input(
            style='Paragraph',
            placeholder='Write your explanation here...',
            custom_id='bug_explanation',
            min_length=25,
            max_length=250
        )
    )

    await event.interaction.respond_modal(
        discord.ModalBuilder(
            title='Bug Report',
            custom_id='modal_one'
        )
        .add_label(select_label)
        .add_label(inp_label)
    )

Responding to an Event¶

Demonstrates responding to a reaction added to one of the bot's messages.

@client.event("MESSAGE_REACTION_ADD")
async def on_reaction_add(bot: discord.Client, event: discord.ReactionAddEvent):
    if event.message_author_id == bot.application_id:
        await bot.message_from_id(event.channel_id, event.message_id).send('Love ya too!')

Adding Attachments¶

Demonstrates adding multiple attachments to a legacy embed. This example can be extended to Containers and other fields that need an https or attachment scheme.

@client.command(
    command=discord.SlashCommand(name='example', description='Demonstrate adding an attachment!'), 
    guild_id=GUILD_ID
)
async def on_example(bot: discord.Client, event: discord.InteractionEvent):
    await event.interaction.respond(
        discord.MessageBuilder()
            .add_attachment('relative/path/to/file.png')
            .add_attachment('relative/path/to/animation.gif')
            .add_embed(discord.EmbedBuilder('Example Embed')
                .set_user_author(event.interaction.member.user)
                .set_color('#d4af37')
                .set_thumbnail(f'attachment://file.png') # attachment://<filename>
                .set_image(f'attachment://animation.gif')
                .set_timestamp()
            )
    )