Embeds
You might have seen some special messages on Discord (often sent by bots/webhooks), that have a colored border, embedded
images, text fields and other properties. These elements are referred to as Embeds, and this section will cover how
you can create and send one with your bot. This is done with Embed object.
This section will extensively cover the attributes and methods used with embeds. Thus, we recommend skipping to your desired topic via the table of contents.
Embed preview
Here is an example of how an embed may look. We will go over embed construction in the next part of this article.
Embed Footer01/01/2077The code for this embed is given below.
# At the top of the file.
import disnake
from disnake.ext import commands
# Inside a command, event listener, etc.
embed = disnake.Embed(
title="Embed Title",
description="Embed Description",
url="https://disnake.dev/",
color=disnake.Colour.yellow(),
timestamp=datetime.datetime.now(),
)
embed.set_author(
name="Embed Author",
url="https://disnake.dev/",
icon_url="https://disnake.dev/assets/disnake-logo.png",
)
embed.set_footer(
text="Embed Footer",
icon_url="https://disnake.dev/assets/disnake-logo.png",
)
embed.set_thumbnail(url="https://disnake.dev/assets/disnake-logo.png")
embed.set_image(url="https://disnake.dev/assets/disnake-banner-thin.png")
embed.add_field(name="Regular Title", value="Regular Value", inline=False)
embed.add_field(name="Inline Title", value="Inline Value", inline=True)
embed.add_field(name="Inline Title", value="Inline Value", inline=True)
embed.add_field(name="Inline Title", value="Inline Value", inline=True)
await ctx.send(embed=embed)
It is not strictly necessary to use all elements showcased above. You're free to leave some out as per your requirements.
The colour of the embed (via the colour parameter) accepts a Colour instance, a HEX
string or an integer.
To add a blank field to the embed, you can use embed.add_field(name='\u200b', value='\u200b').
Creating an embed
You can use the Embed object for the creation and manipulation of embeds.
embed = disnake.Embed(
title="Embed Title",
description="Embed Description",
colour=0xF0C43F,
)
Setting the author
You can set the author of the embed with the set_author
attribute. Note that this code will come after you have defined embed via embed = disnake.Embed(...).
embed.set_author(
name="Embed Author",
url="https://disnake.dev/",
icon_url="https://disnake.dev/assets/disnake-logo.png",
)
Since we have set a URL in this case, clicking on "Embed Author" will redirect the user to the
disnake.dev website.
Setting the footer
You can set the footer of the embed with the set_footer
attribute. Note that this code will come after you have defined embed via embed = disnake.Embed(...).
embed.set_footer(
text="Embed Footer",
icon_url="https://disnake.dev/assets/disnake-logo.png",
)
Setting the thumbnail
The thumbnail of the embed is shown in it's top right corner. It can be set using
the set_thumbnail attribute.
embed.set_thumbnail(url="https://disnake.dev/assets/disnake-banner-thin.png")
Using timestamps
Timestamps are shown in the footer of the embed, indicating the time at which the embed was sent/initiated. This can be
done using the timestamp parameter of disnake.Embed(). Note
that you will need to import the datetime package into your script.
# At the top of your script
import datetime
# Inside a command, event listener, etc.
embed = disnake.Embed(
title="An Embed!",
description="A description!",
colour=0xF0C43F,
timestamp=datetime.datetime.now(),
)
Inserting fields
Embed fields have two parameters - a name(or title) and a value, inside the add_field attribute.
It is also possible to use markdown in both parameters.
# Regular Fields
embed.add_field(name="Regular Title", value="Regular Value", inline=False)
# Inline Fields
embed.add_field(name="Inline Title", value="Inline Value", inline=True)
embed.add_field(name="Inline Title", value="Inline Value", inline=True)
embed.add_field(name="Inline Title", value="Inline Value", inline=True)
These attributes also fully support the use of markdown, as well as highlight links. You can also insert fields at a
particular position, with a specified index using embed.insert_field_at(index, ...).
Inserting images
This can be done using the set_image attribute, which accepts
either a URL or a File object.
# Using a URL
embed.set_image(url="https://disnake.dev/assets/disnake-banner-thin.png")
# Using a local file
embed.set_image(file=disnake.File("path/to/file.png"))
Embed Footer01/01/2077Sending an embed
Once the embed is created, you need to send it to a channel too. This means you need to call send(embed=embed) on a
messageable object, for example a TextChannel object (i.e. message.channel.send) or a Context object (ctx.send).
Otherwise, the embed will not be sent.
Dictionaries to embeds
A dict datatype (and essentially a json file) can be converted into an embed, using the Embed.from_dict() method.
We can recreate the embed made at the start of this page, using the same.
embed_dict = {
"title": "Embed Title",
"description": "Embed Description",
"color": 0xFEE75C,
"timestamp": datetime.datetime.now().isoformat(),
"author": {
"name": "Embed Author",
"url": "https://disnake.dev/",
"icon_url": "https://disnake.dev/assets/disnake-logo.png",
},
"thumbnail": {"url": "https://disnake.dev/assets/disnake-logo.png"},
"fields": [
{"name": "Regular Title", "value": "Regular Value", "inline": "false"},
{"name": "Inline Title", "value": "Inline Value", "inline": "true"},
{"name": "Inline Title", "value": "Inline Value", "inline": "true"},
{"name": "Inline Title", "value": "Inline Value", "inline": "true"},
],
"image": {"url": "https://disnake.dev/assets/disnake-banner-thin.png"},
"footer": {"text": "Embed Footer", "icon_url": "https://disnake.dev/assets/disnake-logo.png"},
}
await channel.send(embed=disnake.Embed.from_dict(embed_dict))
This will give the exact same result as the embed shown here. Note that the timestamp passed through a
dictionary should be in ISO8601 format (which has been achieved here by using datetime.datetime.now().isoformat()).
You can learn more about the dict format of embeds in the
official Discord documentation.
Embed notes
- To display fields side-by-side, you need at least two consecutive fields set to inline.
- The timestamp will automatically adjust the timezone depending on the user's device.
- Mentions of any kind in embeds will only render correctly within embed descriptions and field values.
- Mentions in embeds will not trigger a notification.
- Embeds allow masked links (e.g.
[Guide](https://guide.disnake.dev/ 'optional hovertext')), but only in description and field values.
Embed limits
There are a few limits to be aware of while planning your embeds due to the API's limitations. Here is a quick reference you can come back to:
- Embed titles are limited to 256 characters.
- Embed descriptions are limited to 4096 characters.
- There can be up to 25 fields.
- A field's name is limited to 256 characters and its value to 1024 characters.
- The footer text is limited to 2048 characters.
- The author name is limited to 256 characters.
- The sum of all characters from all embed structures in a message must not exceed 6000 characters.
- 10 embeds can be sent per message.
Resulting code
The code showcased in this section can be found on our GitHub repository here.