Skip to main content

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.


Disnake BotBot01/13/2023
Embed Description
Regular Title
Regular Value
Inline Title
Inline Value
Inline Title
Inline Value
Inline Title
Inline Value

The code for this embed is given below.

embed.py
# 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",
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-thin-banner.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)
note

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.py
embed = disnake.Embed(
title="Embed Title",
description="Embed Description",
colour=0xF0C43F,
)

Disnake BotBot01/13/2023
Embed Title
Embed Description

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.py
embed.set_author(
name="Embed Author",
url="https://disnake.dev/",
icon_url="https://disnake.dev/assets/disnake-logo.png",
)

Disnake BotBot01/13/2023
Embed Title
Embed Description

Since we have set a URL in this case, clicking on "Embed Author" will redirect the user to the disnake.dev website.

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.py
embed.set_footer(
text="Embed Footer",
icon_url="https://disnake.dev/assets/disnake-logo.png",
)

Disnake BotBot01/13/2023
Embed Title
Embed Description

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.py
embed.set_thumbnail(url="https://disnake.dev/assets/disnake-thin-banner.png")

Disnake BotBot01/13/2023
Embed Thumbnail
It is shown in the top-right corner of the embed. You can set this as a URL, but disnake also allows you to use a locally stored file instead, using the file parameter.

embed.set_thumbnail(file=disnake.File("asset/path.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.

embed.py
# 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(),
)

Disnake BotBot01/13/2023
Timestamps
Note that datetime.datetime.utcnow() can also be used here. You can also specify the timezone via the tzinfo parameter.

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.

embed.py
# 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)

Disnake BotBot01/13/2023
Embed Title
Embed Description
Regular Title
Regular Value
Inline Title
Inline Value
Inline Title
Inline Value
Inline Title
Inline Value

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.

embed.py
# Using a URL
embed.set_image(url="https://disnake.dev/assets/disnake-thin-banner.png")

# Using a local file
embed.set_image(file=disnake.File("path/to/file.png"))

Disnake BotBot01/13/2023
Images
To use a local asset for images or thumbnail with the set_image attribute, use the file kwarg which accepts a disnake.File() object.

Sending 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.py
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-thin-banner.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.
Source: Discord.js Guide

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.
Source: Discord API Documentation

Resulting code

The code showcased in this section can be found on our GitHub repository here.