@ -1,3 +1,4 @@
:orphan:
.. currentmodule :: discord.. currentmodule :: discord
.. _guide_topic_embeds: .. _guide_topic_embeds:
@ -6,459 +7,354 @@
EmbedsEmbeds
==============
Embeds are a fundamental part of Discord's message format.Embeds are special message that are formatted to embed rich content within. You may have ever sent a link to a server and
seen one appear with a brief description and maybe an image or video.
They allow you to add additional content into your messages.
Discord typically uses embeds to display information related to links:
.. image :: /images/guide/topics/embeds/link_embed.png.. |link_embed_google| image :: /images/guide/topics/embeds/link_embed_google.png
:scale: 50% :scale: 38%
:target: https://google.com/search?q=discord%20inc
Bots and webhooks alike are also able to send embeds without any links in the message content:.. |link_embed_discord| image :: /images/guide/topics/embeds/link_embed_discord.png
:scale: 38%
.. image :: /images/guide/topics/embeds/simple_embed.png :target: https://discord.com
:scale: 50% .. |link_embed_youtube| image :: /images/guide/topics/embeds/link_embed_youtube.png
:scale: 38%
Defining an Embed :target: https://www.youtube.com/watch?v=TJ13BA3-NR4&
------------------.. |link_embed_github| image :: /images/guide/topics/embeds/link_embed_github.png
:scale: 38%
Embeds are fairly straightforward to define in discord.py. :target: https://github.com/Rapptz/discord.py
Let's try recreating the image above.
First, we'll need to construct a :class: `Embed` object.
.. code-block :: python3+---------------------+----------------------+----------------------+---------------------+
| |link_embed_google| | |link_embed_discord| | |link_embed_youtube| | |link_embed_github| |
+---------------------+----------------------+----------------------+---------------------+
my_embed = discord.Embed()
We should set the colour of the embed next.The examples above are just a few common samples of what you seen often around Discord, these are automatically generated
by discord based on the netadata from the site that is being linked but you don't need to remember all of this.
Seems like it's conveniently the same colour as :meth: `Colour.purple` ! Internally, an embed is represented with a JSON payload by the API. discord.py offers a
So, all we need to do is provide it to the `` colour `` parameter of the constructor .builder-esque interface over this payload to help make the process more straightforward and intuitive in Python .
.. code-block :: python3Let's take a look at a basic example of using the builder:
:emphasize-lines: 2
my_embed = discord.Embed(.. code-block :: python
colour=discord.Colour.purple()
)
.. tip ::
There is also a `` color `` parameter, and respective aliases for `` discord.Color `` .
In case you prefer that spelling.
Next, we'll set the title of the embed. import discord
Just like `` colour `` , it's another parameter of the constructor, called `` title `` . embed = discord.Embed(
title = "Hello World",
.. code-block :: python3 description = "This is a description",
:emphasize-lines: 3 colour = discord.Colour.blurple()
my_embed = discord.Embed(
colour=discord.Colour.purple(),
title="Hello, World!",
) )
Let's see how that looks so far if we send it.And then we can send it to a channel using the `` embed `` keyword-only argument:
.. code-block :: python3
await channel.send(embed=my_embed) .. code-block :: python
await channel.send(embed=embed)
.. image :: /images/guide/topics/embeds/simple_embed_2.pngOn Discord, this will look like:
:scale: 38%
You can also hyperlink the title using the `` url `` parameter of the constructor:.. image :: /images/guide/topics/embeds/basic_embed.png
.. code-block :: python3
:emphasize-lines: 3
my_embed = discord.Embed(
colour=discord.Colour.purple(),
title="Hello, World!",
url="https://google.com",
)
So close! Now, all we need to do is add the description.
.. code-block :: python3
my_embed = discord.Embed(
colour=discord.Colour.purple(),
title="Hello, World!",
description="This bot is running on discord.py!",
url="https://discord.gg/invite/dpy",
)
.. image :: /images/guide/topics/embeds/simple_embed_final.png
:scale: 50% :scale: 50%
And that's it!Let's break down what we did.
As you can see, the interface that discord.py provides is essentially a direct mapping of what you see in the Discord client.
To summarise, we call the constructor for :class: `Embed` and provide the following keyword arguments:
- `` colour `` to set the colour of the embed.First, we imported the `` discord `` module. This is required to access the `` Embed `` class.
- `` title `` to set the title of the embed.
- `` description `` to set the description of the embed.
- `` url `` to hyperlink the title of the embed.
Let's take a look at what else we can add to an embed... note ::
Using Embed Components
-----------------------
The :class: `Embed` class allows usage of the `factory`
.. hint :: You can also import the `` Embed `` class directly from the `` discord `` module like so:
This means that certain methods will return a modified instance of the embed class, .. code-block :: python
so you can chain method calls.
We will discover this as we go through the guide. from discord import Embed
embed = Embed(...)
MarkdownNext, we created an instance of the `` Embed `` class. This is the object that will contain the basic fields of our embed.
~~~~~~~~~
An embed's description and fields allow you to use markdown, soThe `` title `` and `` description `` fields are pretty self-explanatory. The `` colour `` field is a bit more interesting.
that includes **this** , *that* , and even `` this `` -- read more about it at :ref: `_guide_topic_markdown` .This field is used to set the colour of the left-hand side of the embed. We used the `` blurple `` classmethod on the
`` Colour `` class that discord.py provides to get the blurple colour. The field can also be set to an integer
representing a hexadecimal colour code like `` 0x5865f2 `` or `` 5793266 `` .
Just like masked links in the message content, you can also hyperlink text in the description and fields of an embed:.. note ::
.. code-block :: python3 There is another way to set the basic fields of an embed, you can also set them after construction, like so:
my_embed.description = """**Hello** ! My name is Danny! .. code-block :: python
Check out my GitHub: [click here!](https://github.com/Rapptz)
I have a page dedicated to [`C++ Tutorials`
"""
.. image :: /images/guide/topics/embeds/hyperlink_description_embed.png embed = discord.Embed()
:scale: 38% embed.title = "Hello World"
embed.description = "This is a description"
embed.colour = discord.Colour.blurple()
.. tip :: .. tip ::
Hyperlinks in markdown follow a specific format: `` [text](link) `` . US English spellings can use the respective `color` `Color`
It is also possible to add tooltips to hyperlinks, which are displayed when you hover over the hyperlink.
.. code-block :: python3.. note ::
There are two other basic fields that we didn't show here, `` url `` and `` timestamp `` . The `` url `` field is used to set the
my_embed.description = """**Hello** ! My name is Danny! URL that the title of the embed should be masked with. The `` timestamp `` field is used to set the timestamp of the embed. This
Check out my GitHub: [click here!](https://github.com/Rapptz "My GitHub") field takes a `` datetime.datetime `` aware object.
I have a page dedicated to [`C++ Tutorials`
"""
.. image :: /images/guide/topics/embeds/hyperlink_tooltip_description_embed.png Try adding these two fields to the embed the same way we did with the other fields and see what happens.
:scale: 38%
Finally, we sent the embed to a channel. We used the `` embed `` keyword-only argument to do this. This argument takes an
instance of the `` Embed `` class which we created earlier and assigned to the `` embed `` variable.
FieldsFields
~~~~~~~ -------
Fields can be used to add subsections to an embed, they can contain two articles of information; a name and a value.Fields can be used to add subsections to an embed, each one contains two articles of information; a name and a value.
Let's make an embed that tells us the weather in San Francisco .Starting off with a few basic fields .
We'll start off with the simple stuff, a colour, a title and a description. Since embed fields need both a name and value, a field is added by calling :meth: `embed.add_field()<Embed.add_field>` :
.. code-block :: python3 .. code-block :: python
my_weather_ embed = discord.Embed( embed = discord.Embed(
colour=discord.Colour.yellow() , title = "Weather in San Francisco, CA" ,
title="Weather in San Francisco, CA ", description = "Sunny with a High of 55F and a Low of 49F\nFeels like: 55F ",
description="Clear with a high of 59 degrees Fahrenheit.", colour = discord.Colour.yellow()
) )
That will look like this: embed.add_field(name="Precipitation", value="0%", inline=False)
embed.add_field(name="Wind", value="5 mph", inline=True)
.. image :: /images/guide/topics/embeds/field_weather_embed_1.png embed.add_field(name="Humidity", value="96%")
:scale: 38%
Now, let's add a field that tells us the precipitation in San Francisco. await channel.send(embed=embed)
We should use :meth: `my_weather_embed.add_field() <Embed.add_field>` to add it. Let's see it on Discord:
.. code-block :: python3.. image :: /images/guide/topics/embeds/fields_embed.png
:scale: 50%
my_weather_embed.add_field(name="Precipitation", value="2%")
Let's see what that looks like:Notice how how the fields are in a certain order, the `` Precipitation `` field is on the top and the other two are next to
each other on the bottom. This is because of the `` inline `` parameter. This argument takes either `` True `` or `` False `` to
determine whether or not the field should be on its own block. This is why the `` Precipitation `` field is on the top.
If the parameter is not passed, it's always `` True `` .
.. image :: /images/guide/topics/embeds/field_weather_embed_2.png
:scale: 38%
We should add two more fields to tell us the humidity and wind speed. Let's see what happens when we add a fourth field and don't pass the `` inline `` parameter:
.. code-block :: python3 .. code-block :: python
my_weather_embed.add_field(name="Humidity", value="76%") embed = discord.Embed(
my_weather_embed.add_field(name="Wind Speed", value="4 mph") title = "Weather in San Francisco, CA",
description = "Sunny with a High of 55F and a Low of 49F\nFeels like: 55F",
colour = discord.Colour.yellow()
)
.. image :: /images/guide/topics/embeds/field_weather_embed_3.png embed.add_field(name="Precipitation", value="0%", inline=False)
:scale: 38% embed.add_field(name="Wind", value="5 mph", inline=True)
embed.add_field(name="Humidity", value="96%")
embed.add_field(
name="Fact about this location",
value="Golden Gate Park outstrips Central Park"
)
Alright! Now, what happens if we try to add a fourth field...? await channel.send(embed=embed)
.. image :: /images/guide/topics/embeds/field_weather_embed_4.png.. image :: /images/guide/topics/embeds/fields_embed_inline.png
:scale: 38%
.. hint :: As you can see, the `` Fact about this location `` field was added next to the `` Humidity `` field. This is because we didn't
specify the `` ìnline `` argument. If you want to force a field to be on its own row, you can pass `` inline=False `` to
the `` add_field `` method.
In the Discord client, each row of fields can contain a maximum of 3 fields.Each row of fields can only contain a maximum of 3 fields, depending on the user's display size .
If you wanted to, you could try using the `` inline `` keyword-only argument of :meth: `~Embed.add_field` ... note ::
This determines the positioning of the field within the embed.
By default, `` inline `` is set to `` True `` for all fields. Fields should be displayed in the order they were added, but if you want to change the order, you can use
If it is set to `` False `` it will be displayed in a block, on its own. the :meth: `embed.insert_field_at()<Embed.insert_field_at>` method to insert a field at a specific index or
:meth: `embed.set_field_at()<Embed.set_field_at>` to replace a field at a specific index.
Let's see what happens when we set it to `` False `` for the `` Wind `` fiel d. Try using these methods to change the order of the fields in the embe d.
.. code-block :: python3 Remember that the index of the first field is 0, the second field is 1, and so on.
my_weather_embed.add_field(name="Wind", value="4 mph", inline=False)Author & Footer
----------------
.. image :: /images/guide/topics/embeds/inline_field_embed.pngLet's quickly glance over the `` author `` and `` footer `` fields.
:scale: 50%
.. note :: The `` author `` field is a the top of the embed containing:
If you want to set `` inline `` to `` False `` for a field in the middle, such as the- A name (`` name= `` argument, required)
`` Humidity `` field, it will appear as such:- An icon URL (`` icon_url= `` argument, optional)
- A hyperlinked URL, masked by the name (`` url= `` argument, optional)
.. image :: /images/guide/topics/embeds/inline_middle_field_embed.pngThe `` footer `` field is at the bottom of the embed containing:
:scale: 50%
Author - A text (`` text= `` argument, required)
~~~~~~~ - An icon URL (`` icon_url= `` argument, optional)
Embeds can also have an author.All arguments are keyword-only.
This is a small section of information that appears at the top of the embed, it can contain an icon, a name, and a URL, which is opened when the user clicks on the name.
Let's set the author of the embed to "Today's Weather" and link to a Google search of "Weather In San Francisco".Let's see an example of both:
We'll use :meth: `my_weather_embed.set_author() <Embed.set_author>` to set these values.
.. code-block :: python3 .. code-block :: python
my_weather_embed.set_author( embed = discord.Embed(
name="Today's Weather", title = "Weather in San Francisco, CA",
url="https://goo.gl/search/Weather+In+San+Francisco", description = "Sunny with a High of 55F and a Low of 49F\nFeels like: 55F",
colour = discord.Colour.yellow()
) )
That will like this: embed.add_field(name="Precipitation", value="0%", inline=False)
embed.add_field(name="Wind", value="5 mph", inline=True)
.. image :: /images/guide/topics/embeds/author_embed_1.png embed.add_field(name="Humidity", value="96%")
:scale: 38% embed.add_field(
name="Fact about this location",
It appears like a "subtitle" above the title in the embed. value="Golden Gate Park outstrips Central Park"
)
With :attr: `Embed.author` , we can also set the icon of the author.
The `` icon_url `` keyword-only argument of :meth: `my_weather_embed.set_author() <Embed.set_author>` accepts a string, or anything that can be cast to a string, as the URL.
This allows us to conveniently provide an :class: `Asset` instance, which is used throughout the library.
In this example, we will use the :meth: `bot.user.display_avatar <ClientUser.display_avatar>` , an :class: `Asset` instance, for the icon.
.. code-block :: python3
:emphasize-lines: 3
my_weather_ embed.set_author( embed.set_author(name=bot.user.name, icon_url=bot.user.display_avatar.url)
name="Today's Weather", embed.set_footer(
url="https://goo.gl/search/Weather+In+San+Francisco ", text="Powered by OpenWeatherMap",
icon_url=bot.user.display_avatar, icon_url="https://openweathermap.org/themes/openweathermap/assets/vendor/owm/img/icons/logo_32x32.png"
) )
.. image :: /images/guide/topics/embeds/author_embed.png await channel.send(embed=embed)
.. image :: /images/guide/topics/embeds/author_footer_embed.png
:scale: 50% :scale: 50%
This isn't the only place you can add images though. Let's see how else we can incorporate images into our weather embed.A breakdown of what we did, we set the `` author `` field to the bot's name and avatar URL and the `` footer `` 's text to
"Powered by OpenWeatherMap" and `` icon_url `` to OpenWeatherMap's logo.
ImagesImages
~~~~~~~ -------
There are two ways to add images to an embed:There are two ways to add images to an embed:
- As the embed's `` image `` .- As the embed's `` image `` .
- As the embed's `` thumbnail `` .- As the embed's `` thumbnail `` .
We will add an `image of the Golden Gate Bridge`_ to the weather embed by calling :meth: `my_weather_embed.set_image() <Embed.set_image>` :At the time of writing, bots cannot embed videos.
We will add an `image of the Golden Gate Bridge`_ to the embed by calling :meth: `embed.set_image() <Embed.set_image>` :
.. code-block :: python3.. code-block :: python
image_url = "https://upload.wikimedia.org/wikipedia/commons/0/0c/GoldenGateBridge-001.jpg" image_url = "https://upload.wikimedia.org/wikipedia/commons/0/0c/GoldenGateBridge-001.jpg"
my_weather_ embed.set_image(url=image_url) embed.set_image(url=image_url)
.. _image of the Golden Gate Bridge: https://commons.wikimedia.org/wiki/Golden_Gate_Bridge#/media/File:GoldenGateBridge-001.jpg.. _image of the Golden Gate Bridge: https://commons.wikimedia.org/wiki/Golden_Gate_Bridge#/media/File:GoldenGateBridge-001.jpg
.. image :: /images/guide/topics/embeds/image_embed.png.. image :: /images/guide/topics/embeds/image_embed.png
:scale: 5 0% :scale: 7 0%
As seen above, when setting :attr: `Embed.image` , the provided URL will be displayed at the bottom of the embed.As seen above, when setting :attr: `Embed.image` , the provided URL will be displayed at the bottom of the embed.
The alternative to this, is to set :attr: `Embed.thumbnail` , which would be displayed in the top right corner of the embed.The alternative to this, is to set :attr: `Embed.thumbnail` , which would be displayed in the top right corner of the embed.
Rather than setting the image to a URL like we did before, let's try attaching a file for thumbnail.Files
------
First, we have to construct a :class: `File` object. The first argument is the file path, and the second is the name of the attachment that will be used to refer to it within Discord.
.. code-block :: python3
my_file = discord.File('./images/sunny_weather.png', 'thumbnail.png')You may have noticed that we used URLs to for each of the images in the embeds above but what if we wanted to use a local file?
That's possible too, we can use the :class: `File` class and set the url fields to a special URI scheme that Discord provides - `` attachment:// `` .
Next, we need to call :meth: `my_weather_embed.set_thumbnail() <Embed.set_thumbnail>` to set the thumbnail.Let's set the thumbnail of the weather embed to a local file.
To refer to our attachment for the thumbnail, we will use a special URI scheme that Discord provides - `` attachment:// `` .
Since we called our file `` thumbnail.png `` , we will set the `` url `` parameter to `` attachment://thumbnail.png `` .First, we have to construct a :class: `File` object. The first argument is the file path, and the second is the name of the attachment that will be used to refer to it within Discord .
.. code-block :: python3 .. code-block :: python
my_weather_embed.set_thumbnail(url="attachment://thumbnail.png" ) file = discord.File('./images/sunny_weather.png', 'thumbnail.png' )
.. warning :: .. warning ::
Make sure to provide the file with the `` file `` parameter before sending the message. The filename for these URLs must be ASCII alphanumeric with underscores, dashes, or dots. This is a Discord limitation.
Otherwise, Discord will not know what attachment you are referring to within the embed.
.. code-block :: python3
await message.channel.send(embed=my_weather_embed, file=my_file)
Footer
~~~~~~
Embeds can also have a footer.
This is a small section of information that appears at the bottom of the embed, it can contain an icon, a name, and the timestamp but that's for later.
Let's set the footer of the embed to "Powered by OpenWeatherMap"
.. code-block :: python3
my_weather_embed.set_footer(
text="Powered by OpenWeatherMap",
)
That will look like this:
.. image :: /images/guide/topics/embeds/footer_embed_1.png
:scale: 50%
It appears as the last thing in the embed.Next, we need to call :meth: `embed.set_thumbnail() <Embed.set_thumbnail>` to set the thumbnail.
To refer to our attachment for the thumbnail, we will use a special URI scheme as discussed above.
Just like with the author, we can also set the icon of the footer.
The `` icon_url `` keyword-only argument of :meth: `my_weather_embed.set_footer() <Embed.set_footer>` accepts a string, or anything that can be cast to a string, as the URL.
In this example, we set it to something that matches the `` text `` , the logo of OpenWeatherMap.
.. code-block :: python3
:emphasize-lines: 3
my_weather_embed.set_footer(
text="Powered by OpenWeatherMap",
icon_url="https://openweathermap.org/themes/openweathermap/assets/vendor/owm/img/icons/logo_32x32.png",
)
Here is how it looks:
.. image :: /images/guide/topics/embeds/footer_embed.png
:scale: 50%
Since we called our file `` thumbnail.png `` , we will set the `` url `` parameter to `` attachment://thumbnail.png `` .
Timestamp.. code-block :: python
~~~~~~~~~
There is another parameter of the constructor that we haven't covered yet, `` timestamp `` . embed.set_thumbnail(url="attachment://thumbnail.png")
This is an aware datetime. If a naive datetime is passed, it is converted to an aware datetime with the local timezone.
Let's set the timestamp of the embed to the current tim e.And finally, we will send the embed with the `` file `` parameter set to our file.
.. code-block :: python3 .. code-block :: python
my_weather_embed = discord.Embed( await channel.send(file=file, embed=embed)
colour=discord.Colour.yellow(),
title="Weather in San Francisco, CA",
description="Clear with a high of 59 degrees Fahrenheit.",
timestamp=discord.utils.utcnow(),
)
.. image :: /images/guide/topics/embeds/timestamp_embed_1.pngIt should look the same as before but now we are using a local file instead of a URL.
:scale: 50%
But that's with the footer, what if we remove that? More about this can be found at :ref: `local_image`
.. image :: /images/guide/topics/embeds/timestamp_embed.png
:scale: 50%
As you can see, the timestamp is still there, but without the middle dot between the footer text and the timestamp that discord adds.Reading values off an embed
----------------------------
The timestamp is translated to the user's local time, and it is displayed in the same format as the user's local time format.Now that we have constructed our embed, let's see how we can get the values from it if for example we get it from a :class: `Message` .
Getting
-------
Now that we have constructed our embed, let's see how we can get the values from it.
Let's start by getting the title of the embed.Let's start by getting the title of the embed.
We can do this by accessing the :attr: `Embed.title` attribute.We can do this by using the :attr: `Embed.title` attribute.
.. code-block :: python3
print(my_weather_embed.title) .. code-block :: python
# Weather in San Francisco, CA >>> print(embed.title)
'Weather in San Francisco, CA'
That was easy!That was easy!
Now, let's get the footer text.Now, let's get the footer text.
.. code-block :: python3 .. code-block :: python
print(my_weather_embed.footer.text) >>> print(embed.footer.text)
'Powered by OpenWeatherMap'
# Powered by OpenWeatherMap
But what if we remove the footer and try again?But what if we remove the footer and try again?
.. code-block :: python3.. code-block :: python
my_weather_embed.remove_footer()
print(my_weather_embed.footer.text)
# None >>> embed.remove_footer()
>>> print(my_weather_embed.footer.text)
None
As you can see, it returns `` None `` , this is because attribute like `` author `` and `` footer `` return a special object that returns `` None `` when the attribute is not set.As you can see, it returns `` None `` , this is because attribute like `` author `` and `` footer `` return a special object that returns `` None `` when the attribute is not set.
This is the same for all other attributes that got more than one value like `` fields `` , `` image ` `This is the same for all other attributes that got more than one value like :attr: `Embed.fields` , :attr: `Embed.image `
Setters Most of these attributes have more attributes compared to what we can set, for example, the :attr: `Embed.image` attributes called `` width `` and
------- `` height `` that return the width and height of the image respectively.
You may have noticed that we have been using keyword argument to set the title, description, etc. of the embed. But .. code-block :: python
those can also be set after the embed has been constructed.
Let's change the title of the embed by setting the :attr: `Embed.title` attribute. >>> print(embed.image.width)
1024 # or None
>>> print(embed.image.height)
768 # or None
.. code-block :: python3Other attributes can be found in the :class: `Embed` documentation for the reprecive attribute.
my_weather_embed.title = "San Francisco (CA) Weather"Proxy URLs
~~~~~~~~~~~
And see how that looks: This is a cached version of the url in the case of images. When the message is deleted, this URL might be valid for a few minutes or not valid at all.
.. image :: /images/guide/topics/embeds/setters_embed_title.pngThe following field can have a proxy URL:
:scale: 50%
- :attr: `Embed.image`
- :attr: `Embed.thumbnail`
- :attr: `Embed.author`
- :attr: `Embed.footer`
All possible setters are listed below:.. code-block :: python
- `` title `` >>> print(embed.thumbnail.proxy_url)
- `` description `` 'https://media.discordapp.net/attachments/123456789012345678/8765432187654321/image.png'
- `` url ``
- `` colour `` / `` color ``
- `` timestamp ``
Other MethodsOther Methods
@ -469,35 +365,70 @@ There are a few other methods that may be useful when working with embeds.
.. method :: Embed.from_dict().. method :: Embed.from_dict()
:noindex: :noindex:
Creates an embed from a dictionary. Creates an embed from a Python dictionary.
.. code-block :: python3 .. code-block :: python
embed_dict = { payload = {
"title": "Hello, World!", "title": "Hello, World!",
"description": "This bot is running on discord.py!", "description": "This bot is running on discord.py!",
"colou r": 0x00FF00 "color": 0x00FF00
} }
embed = discord.Embed.from_dict(payload)
my_embed = discord.Embed.from_dict(embed_dict) .. warning ::
.. note :: Each key needs to match the structure of an embed from Discord's API.
Namely, the API doesn't alias `colour` `color`
The dict must match the structure of the Embed from Discord's API. :ddocs: `Embeds as documented by Discord<resources/channel#embed-object>` .
You can find the structure of the Embed in the ':ddocs: `resources/channel#embed-object` '
.. method :: Embed.to_dict().. method :: Embed.to_dict()
:noindex: :noindex:
Converts the embed to a dictionary. Inversely, `to_dict`
.. code-block :: python3
my_embed_dict = my_embed.to_dict() .. code-block :: python
print(my_embed_dict)
# {'title': 'Hello, World!', 'description': 'This bot is running on discord.py!', 'type': 'rich', 'color': 65280} >>> embed.to_dict()
{'title': 'Hello, World!', 'description': 'This bot is running on discord.py!', 'type': 'rich', 'color': 65280}
Other can be found in the :class: `Embed` documentation.Other can be found in the :class: `Embed` documentation.
Restrictions and limits
------------------------
There are a few restrictions and limits that you should be aware of when working with embeds.
Markdown support is limited
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Markdown like **this** , *that* , and even `` this `` is supported in embeds, but only in certain fields.
More about this can be found at :ref: `_guide_topic_markdown` .
All fields must be strings
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Except for `` timestamp `` and `` colour `` which must be a `` datetime.datetime `` object and `` discord.Colour `` / `` int ``
object respectively.
discord.py attempts to convert all values given to string using `` str() `` .
This can be confusing for beginning users of Python as they may not be aware of this, most objects have a `` __str__ `` method that
returns a string representation of the object. Most objects in discord.py also do this, like :class: `discord.Asset` , that is returned from
attributes like :attr: `discord.User.avatar` and :attr: `discord.Guild.icon` and calling `` str() `` on it returns the URL of the asset.
That is precisely why you can pass these attributes to the `` url `` parameter of the embed or :attr: `discord.User` to the `` name `` argument in
:meth: `embed.set_author() <Embed.set_author>` and it will work but it's not encouraged to do so.
Try it out:
.. code-block :: python
embed.set_author(name=bot.user, icon_url=bot.user.avatar)
Each field has a character limit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unfortunately, listing all the limits here would get the fastly outdated, so you can find them in the :ddocs: `API documentation for Embed<resources/channel#embed-object>` .
Soheab_
1 year ago
