Messages · Docs

These functions work in commands (pre-hook and post-hook), events and component handlers.

You do not need to write await in front of them. The bot adds it for you. Writing it is fine too.

The reply is free

The command's own reply (the Response box, or set_content) does not count toward any limit. Use send_message only for extra messages, like a log in another channel.

Limits#

Each run of a command or event can send a fixed number of messages. Pre-hook and post-hook share one count.

Function	Free	Premium
`send_message` + `forward_message` (together)	3	5
`send_dm`	2	2

Going over stops the script with "Maximum messages sent. Can't send more."

send_message#

Sends a message to a channel in this server. Returns the sent message.

python

send_message(
    channel,
    content=None,
    embed=None,
    message=None,
    components=None,
    attachments=None,
    everyone_mentions=True,
    role_mentions=True,
    user_mentions=True,
    reply=None,
)

Argument	Type	What it does
`channel`	channel, ID or name	Where to send.
`content`	text	The message text.
`embed`	embed	One embed, for example from `load_embed("id")`.
`message`	`Message`	Text and embed together, built with `Message(...)`.
`components`	`ComponentBuilder` or `View`	Buttons and menus.
`attachments`	list	Files, from `load_file(...)` or `render_template(...)`.
`everyone_mentions`	yes / no	Set `False` so `@everyone` does not ping.
`role_mentions`	yes / no	Set `False` so role mentions do not ping.
`user_mentions`	yes / no	Set `False` so user mentions do not ping.
`reply`	message ID	Send as a reply to that message.

Example: log who used a command

python

log = get_channel("mod-log")
send_message(log, f"{user.mention} used /{command_name} in {channel.mention}")

Example: a message with an embed

python

send_message(channel, message=Message(
    title="Server rules",
    description="1. Be kind\n2. No spam",
    color="#5865F2",
))

Watch out

Do not use channel.send(...). It is blocked. Always use send_message.

send_dm#

Sends a direct message to a member. Fails when the member has DMs turned off.

python

send_dm(member, content=None, embed=None, message=None)

python

send_dm(user, "Thanks for joining the giveaway!")

member can be a member or a member ID.

edit_message#

Changes a message the bot sent before.

python

edit_message(
    channel,
    message_id,
    content=None,
    embed=None,
    message=None,
    components=None,
    attachments=None,
)

python

msg = send_message(channel, "Counting…")
edit_message(channel, msg.id, "Done! 3 of 3 checked.")

Note

Discord only lets a bot edit its own messages.

delete_message#

Deletes a message.

python

delete_message(channel_id, message_id)

python

# In a message event: remove messages that contain a blocked word
if "badword" in message.content.lower():
    delete_message(channel_id, message_id)

The bot needs Manage Messages to delete other people's messages.

forward_message#

Forwards a message into another channel, like Discord's own Forward button.

python

forward_message(channel, message, from_channel=None)

Argument	What it does
`channel`	Where the forwarded copy goes.
`message`	A message, or a message ID.
`from_channel`	Where the message is. Needed only when `message` is an ID.

python

forward_message("starboard", message)
forward_message("starboard", 1290000000000000000, from_channel="general")

Both channels must be in this server. It counts toward the send_message limit.

get_message#

Fetches a message by its ID. Returns None when the channel is not found.

python

get_message(channel_id, message_id)

python

msg = get_message(channel.id, 1290000000000000000)
set_content(f"That message says: {msg.content}")

purge_messages#

Deletes many messages at once.

python

purge_messages(channel_id, count, _filter=None, skip=0)

Argument	What it does
`count`	How many messages to delete.
`_filter`	A function. Only messages where it returns `True` are deleted.
`skip`	Skip this many recent messages first.

python

# Delete the last 20 messages from bots
purge_messages(channel.id, 20, lambda m: m.author.is_bot)

Watch out

Discord only bulk-deletes messages newer than 14 days. Older ones are skipped. The bot needs Manage Messages and Read Message History.

add_reactions#

Adds one or more reactions to a message.

python

add_reactions(message, *emojis)

python

msg = send_message(channel, "Do you like pizza?")
add_reactions(msg, "👍", "👎")

For a custom emoji from your server, pass its name: add_reactions(msg, "pepe_happy").

remove_reactions#

Removes reactions one user added.

python

remove_reactions(message, user, *emojis)

remove_all_reactions#

Removes every reaction from a message, or every reaction of one emoji.

python

remove_all_reactions(message, emoji=None)

get_reaction_users#

Lists the users who reacted with an emoji.

python

get_reaction_users(message, emoji)

python

msg = get_message(channel.id, giveaway_id)
users = get_reaction_users(msg, "🎉")
users = [u for u in users if not u.is_bot]   # skip the bot's own reaction
winner = random(users)
set_content(f"The winner is {winner.mention}!")

get_reaction_count#

Counts the reactions of one emoji on a message. Returns 0 when there are none.

python

get_reaction_count(message, emoji)

mention_message#

Makes a link that jumps to a message.

python

mention_message(channel_id, message_id)

python

link = mention_message(channel.id, msg.id)
send_message("mod-log", f"New report: {link}")

These functions work in commands (pre-hook and post-hook), events and component handlers.

You do not need to write await in front of them. The bot adds it for you. Writing it is fine too.

The reply is free

The command's own reply (the Response box, or set_content) does not count toward any limit. Use send_message only for extra messages, like a log in another channel.

Limits#

Each run of a command or event can send a fixed number of messages. Pre-hook and post-hook share one count.

Function	Free	Premium
`send_message` + `forward_message` (together)	3	5
`send_dm`	2	2

Going over stops the script with "Maximum messages sent. Can't send more."

send_message#

Sends a message to a channel in this server. Returns the sent message.

python

send_message(
    channel,
    content=None,
    embed=None,
    message=None,
    components=None,
    attachments=None,
    everyone_mentions=True,
    role_mentions=True,
    user_mentions=True,
    reply=None,
)

Argument	Type	What it does
`channel`	channel, ID or name	Where to send.
`content`	text	The message text.
`embed`	embed	One embed, for example from `load_embed("id")`.
`message`	`Message`	Text and embed together, built with `Message(...)`.
`components`	`ComponentBuilder` or `View`	Buttons and menus.
`attachments`	list	Files, from `load_file(...)` or `render_template(...)`.
`everyone_mentions`	yes / no	Set `False` so `@everyone` does not ping.
`role_mentions`	yes / no	Set `False` so role mentions do not ping.
`user_mentions`	yes / no	Set `False` so user mentions do not ping.
`reply`	message ID	Send as a reply to that message.

Example: log who used a command

python

log = get_channel("mod-log")
send_message(log, f"{user.mention} used /{command_name} in {channel.mention}")

Example: a message with an embed

python

send_message(channel, message=Message(
    title="Server rules",
    description="1. Be kind\n2. No spam",
    color="#5865F2",
))

Watch out

Do not use channel.send(...). It is blocked. Always use send_message.

send_dm#

Sends a direct message to a member. Fails when the member has DMs turned off.

python

send_dm(member, content=None, embed=None, message=None)

python

send_dm(user, "Thanks for joining the giveaway!")

member can be a member or a member ID.

edit_message#

Changes a message the bot sent before.

python

edit_message(
    channel,
    message_id,
    content=None,
    embed=None,
    message=None,
    components=None,
    attachments=None,
)

python

msg = send_message(channel, "Counting…")
edit_message(channel, msg.id, "Done! 3 of 3 checked.")

Note

Discord only lets a bot edit its own messages.

delete_message#

Deletes a message.

python

delete_message(channel_id, message_id)

python

# In a message event: remove messages that contain a blocked word
if "badword" in message.content.lower():
    delete_message(channel_id, message_id)

The bot needs Manage Messages to delete other people's messages.

forward_message#

Forwards a message into another channel, like Discord's own Forward button.

python

forward_message(channel, message, from_channel=None)

Argument	What it does
`channel`	Where the forwarded copy goes.
`message`	A message, or a message ID.
`from_channel`	Where the message is. Needed only when `message` is an ID.

python

forward_message("starboard", message)
forward_message("starboard", 1290000000000000000, from_channel="general")

Both channels must be in this server. It counts toward the send_message limit.

get_message#

Fetches a message by its ID. Returns None when the channel is not found.

python

get_message(channel_id, message_id)

python

msg = get_message(channel.id, 1290000000000000000)
set_content(f"That message says: {msg.content}")

purge_messages#

Deletes many messages at once.

python

purge_messages(channel_id, count, _filter=None, skip=0)

Argument	What it does
`count`	How many messages to delete.
`_filter`	A function. Only messages where it returns `True` are deleted.
`skip`	Skip this many recent messages first.

python

# Delete the last 20 messages from bots
purge_messages(channel.id, 20, lambda m: m.author.is_bot)

Watch out

Discord only bulk-deletes messages newer than 14 days. Older ones are skipped. The bot needs Manage Messages and Read Message History.

add_reactions#

Adds one or more reactions to a message.

python

add_reactions(message, *emojis)

python

msg = send_message(channel, "Do you like pizza?")
add_reactions(msg, "👍", "👎")

For a custom emoji from your server, pass its name: add_reactions(msg, "pepe_happy").

remove_reactions#

Removes reactions one user added.

python

remove_reactions(message, user, *emojis)

remove_all_reactions#

Removes every reaction from a message, or every reaction of one emoji.

python

remove_all_reactions(message, emoji=None)

get_reaction_users#

Lists the users who reacted with an emoji.

python

get_reaction_users(message, emoji)

python

msg = get_message(channel.id, giveaway_id)
users = get_reaction_users(msg, "🎉")
users = [u for u in users if not u.is_bot]   # skip the bot's own reaction
winner = random(users)
set_content(f"The winner is {winner.mention}!")

get_reaction_count#

Counts the reactions of one emoji on a message. Returns 0 when there are none.

python

get_reaction_count(message, emoji)

mention_message#

Makes a link that jumps to a message.

python

mention_message(channel_id, message_id)

python

link = mention_message(channel.id, msg.id)
send_message("mod-log", f"New report: {link}")