serenity/builder/
edit_message.rs

1#[cfg(feature = "http")]
2use super::{check_overflow, Builder};
3use super::{
4    CreateActionRow,
5    CreateAllowedMentions,
6    CreateAttachment,
7    CreateEmbed,
8    EditAttachments,
9};
10#[cfg(feature = "http")]
11use crate::constants;
12#[cfg(feature = "http")]
13use crate::http::CacheHttp;
14#[cfg(feature = "http")]
15use crate::internal::prelude::*;
16use crate::model::prelude::*;
17
18/// A builder to specify the fields to edit in an existing message.
19///
20/// # Examples
21///
22/// Editing the content of a [`Message`] to `"hello"`:
23///
24/// ```rust,no_run
25/// # use serenity::builder::EditMessage;
26/// # use serenity::model::channel::Message;
27/// # use serenity::model::id::ChannelId;
28/// # use serenity::http::CacheHttp;
29///
30/// # async fn example(ctx: impl CacheHttp, mut message: Message) -> Result<(), Box<dyn std::error::Error>> {
31/// let builder = EditMessage::new().content("hello");
32/// message.edit(ctx, builder).await?;
33/// # Ok(())
34/// # }
35/// ```
36///
37/// [Discord docs](https://discord.com/developers/docs/resources/channel#edit-message)
38#[derive(Clone, Debug, Default, Serialize, PartialEq)]
39#[must_use]
40pub struct EditMessage {
41    #[serde(skip_serializing_if = "Option::is_none")]
42    content: Option<String>,
43    #[serde(skip_serializing_if = "Option::is_none")]
44    embeds: Option<Vec<CreateEmbed>>,
45    #[serde(skip_serializing_if = "Option::is_none")]
46    flags: Option<MessageFlags>,
47    #[serde(skip_serializing_if = "Option::is_none")]
48    allowed_mentions: Option<CreateAllowedMentions>,
49    #[serde(skip_serializing_if = "Option::is_none")]
50    components: Option<Vec<CreateActionRow>>,
51    #[serde(skip_serializing_if = "Option::is_none")]
52    attachments: Option<EditAttachments>,
53}
54
55impl EditMessage {
56    /// Equivalent to [`Self::default`].
57    pub fn new() -> Self {
58        Self::default()
59    }
60
61    #[cfg(feature = "http")]
62    fn check_length(&self) -> Result<()> {
63        if let Some(content) = &self.content {
64            check_overflow(content.chars().count(), constants::MESSAGE_CODE_LIMIT)
65                .map_err(|overflow| Error::Model(ModelError::MessageTooLong(overflow)))?;
66        }
67
68        if let Some(embeds) = &self.embeds {
69            check_overflow(embeds.len(), constants::EMBED_MAX_COUNT)
70                .map_err(|_| Error::Model(ModelError::EmbedAmount))?;
71            for embed in embeds {
72                embed.check_length()?;
73            }
74        }
75
76        Ok(())
77    }
78
79    /// Set the content of the message.
80    ///
81    /// **Note**: Message contents must be under 2000 unicode code points.
82    #[inline]
83    pub fn content(mut self, content: impl Into<String>) -> Self {
84        self.content = Some(content.into());
85        self
86    }
87
88    /// Add an embed for the message.
89    ///
90    /// **Note**: This will keep all existing embeds. Use [`Self::embed()`] to replace existing
91    /// embeds.
92    pub fn add_embed(mut self, embed: CreateEmbed) -> Self {
93        self.embeds.get_or_insert_with(Vec::new).push(embed);
94        self
95    }
96
97    /// Add multiple embeds for the message.
98    ///
99    /// **Note**: This will keep all existing embeds. Use [`Self::embeds()`] to replace existing
100    /// embeds.
101    pub fn add_embeds(mut self, embeds: Vec<CreateEmbed>) -> Self {
102        self.embeds.get_or_insert_with(Vec::new).extend(embeds);
103        self
104    }
105
106    /// Set an embed for the message.
107    ///
108    /// **Note**: This will replace all existing embeds. Use [`Self::add_embed()`] to keep existing
109    /// embeds.
110    pub fn embed(self, embed: CreateEmbed) -> Self {
111        self.embeds(vec![embed])
112    }
113
114    /// Set multiple embeds for the message.
115    ///
116    /// **Note**: This will replace all existing embeds. Use [`Self::add_embeds()`] to keep existing
117    /// embeds.
118    pub fn embeds(mut self, embeds: Vec<CreateEmbed>) -> Self {
119        self.embeds = Some(embeds);
120        self
121    }
122
123    /// Suppress or unsuppress embeds in the message, this includes those generated by Discord
124    /// themselves.
125    ///
126    /// If this is sent directly after posting the message, there is a small chance Discord hasn't
127    /// yet fully parsed the contained links and generated the embeds, so this embed suppression
128    /// request has no effect. To mitigate this, you can defer the embed suppression until the
129    /// embeds have loaded:
130    ///
131    /// ```rust,no_run
132    /// # use serenity::all::*;
133    /// # #[cfg(feature = "collector")]
134    /// # async fn test(ctx: &Context, channel_id: ChannelId) -> Result<(), Error> {
135    /// use std::time::Duration;
136    ///
137    /// use futures::StreamExt;
138    ///
139    /// let mut msg = channel_id.say(ctx, "<link that spawns an embed>").await?;
140    ///
141    /// // When the embed appears, a MessageUpdate event is sent and we suppress the embed.
142    /// // No MessageUpdate event is sent if the message contains no embeddable link or if the link
143    /// // has been posted before and is still cached in Discord's servers (in which case the
144    /// // embed appears immediately), no MessageUpdate event is sent. To not wait forever in those
145    /// // cases, a timeout of 2000ms was added.
146    /// let msg_id = msg.id;
147    /// let mut message_updates = serenity::collector::collect(&ctx.shard, move |ev| match ev {
148    ///     Event::MessageUpdate(x) if x.id == msg_id => Some(()),
149    ///     _ => None,
150    /// });
151    /// let _ = tokio::time::timeout(Duration::from_millis(2000), message_updates.next()).await;
152    /// msg.edit(&ctx, EditMessage::new().suppress_embeds(true)).await?;
153    /// # Ok(()) }
154    /// ```
155    pub fn suppress_embeds(mut self, suppress: bool) -> Self {
156        // See for details: https://discord.com/developers/docs/resources/message#edit-message-jsonform-params
157        self.flags
158            .get_or_insert(MessageFlags::empty())
159            .set(MessageFlags::SUPPRESS_EMBEDS, suppress);
160        self
161    }
162
163    /// Set the allowed mentions for the message.
164    pub fn allowed_mentions(mut self, allowed_mentions: CreateAllowedMentions) -> Self {
165        self.allowed_mentions = Some(allowed_mentions);
166        self
167    }
168
169    /// Sets the components of this message.
170    pub fn components(mut self, components: Vec<CreateActionRow>) -> Self {
171        self.components = Some(components);
172        self
173    }
174    super::button_and_select_menu_convenience_methods!(self.components);
175
176    /// Sets the flags for the message.
177    pub fn flags(mut self, flags: MessageFlags) -> Self {
178        self.flags = Some(flags);
179        self
180    }
181
182    /// Sets attachments, see [`EditAttachments`] for more details.
183    pub fn attachments(mut self, attachments: EditAttachments) -> Self {
184        self.attachments = Some(attachments);
185        self
186    }
187
188    /// Adds a new attachment to the message.
189    ///
190    /// Resets existing attachments. See the documentation for [`EditAttachments`] for details.
191    pub fn new_attachment(mut self, attachment: CreateAttachment) -> Self {
192        let attachments = self.attachments.get_or_insert_with(Default::default);
193        self.attachments = Some(std::mem::take(attachments).add(attachment));
194        self
195    }
196
197    /// Shorthand for [`EditAttachments::keep`].
198    pub fn keep_existing_attachment(mut self, id: AttachmentId) -> Self {
199        let attachments = self.attachments.get_or_insert_with(Default::default);
200        self.attachments = Some(std::mem::take(attachments).keep(id));
201        self
202    }
203
204    /// Shorthand for [`EditAttachments::remove`].
205    pub fn remove_existing_attachment(mut self, id: AttachmentId) -> Self {
206        if let Some(attachments) = self.attachments {
207            self.attachments = Some(attachments.remove(id));
208        }
209        self
210    }
211
212    /// Shorthand for calling [`Self::attachments`] with [`EditAttachments::new`].
213    pub fn remove_all_attachments(mut self) -> Self {
214        self.attachments = Some(EditAttachments::new());
215        self
216    }
217}
218
219#[cfg(feature = "http")]
220#[async_trait::async_trait]
221impl Builder for EditMessage {
222    type Context<'ctx> = (ChannelId, MessageId, Option<UserId>);
223    type Built = Message;
224
225    /// Edits a message in the channel.
226    ///
227    /// **Note**: Message contents must be under 2000 unicode code points, and embeds must be under
228    /// 6000 code points.
229    ///
230    /// **Note**: Requires that the current user be the author of the message. Other users can only
231    /// call [`Self::suppress_embeds`], but additionally require the [Manage Messages] permission
232    /// to do so.
233    ///
234    /// **Note**: If any embeds or attachments are set, they will overwrite the existing contents
235    /// of the message, deleting existing embeds and attachments. Preserving them requires calling
236    /// [`Self::keep_existing_attachment`] in the case of attachments. In the case of embeds,
237    /// duplicate copies of the existing embeds must be sent. Luckily, [`CreateEmbed`] implements
238    /// [`From<Embed>`], so one can simply call `embed.into()`.
239    ///
240    /// # Errors
241    ///
242    /// Returns a [`ModelError::MessageTooLong`] if the message contents are over the above limits.
243    ///
244    /// Returns [`Error::Http`] if the user lacks permission, as well as if invalid data is given.
245    ///
246    /// [Manage Messages]: Permissions::MANAGE_MESSAGES
247    /// [`From<Embed>`]: CreateEmbed#impl-From<Embed>
248    async fn execute(
249        mut self,
250        cache_http: impl CacheHttp,
251        ctx: Self::Context<'_>,
252    ) -> Result<Self::Built> {
253        self.check_length()?;
254
255        #[cfg(feature = "cache")]
256        if let Some(user_id) = ctx.2 {
257            if let Some(cache) = cache_http.cache() {
258                let reference_builder = EditMessage::new().suppress_embeds(true);
259
260                if user_id != cache.current_user().id && self != reference_builder {
261                    return Err(Error::Model(ModelError::InvalidUser));
262                }
263            }
264        }
265
266        let files = self.attachments.as_mut().map_or(Vec::new(), |a| a.take_files());
267
268        let http = cache_http.http();
269        if self.allowed_mentions.is_none() {
270            self.allowed_mentions.clone_from(&http.default_allowed_mentions);
271        }
272
273        http.edit_message(ctx.0, ctx.1, &self, files).await
274    }
275}
serenity/builder/edit_message.rs

serenity/builder/
edit_message.rs
