Struct Webhook

#[non_exhaustive]
pub struct Webhook {
    pub id: WebhookId,
    pub kind: WebhookType,
    pub guild_id: Option<GuildId>,
    pub channel_id: Option<ChannelId>,
    pub user: Option<User>,
    pub name: Option<String>,
    pub avatar: Option<ImageHash>,
    pub token: Option<SecretString>,
    pub application_id: Option<ApplicationId>,
    pub source_guild: Option<WebhookGuild>,
    pub source_channel: Option<WebhookChannel>,
    pub url: Option<SecretString>,
}

A representation of a webhook, which is a low-effort way to post messages to channels. They do not necessarily require a bot user or authentication to use.

Discord docs.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

id: WebhookId

The unique Id.

Can be used to calculate the creation date of the webhook.

kind: WebhookType

The type of the webhook.

guild_id: Option<GuildId>

The Id of the guild that owns the webhook.

channel_id: Option<ChannelId>

The Id of the channel that owns the webhook.

user: Option<User>

The user that created the webhook.

Note: This is not received when getting a webhook by its token.

name: Option<String>

The default name of the webhook.

This can be temporarily overridden via ExecuteWebhook::username.

avatar: Option<ImageHash>

The default avatar.

This can be temporarily overridden via ExecuteWebhook::avatar_url.

token: Option<SecretString>

The webhook’s secure token.

application_id: Option<ApplicationId>

The bot/OAuth2 application that created this webhook.

source_guild: Option<WebhookGuild>

The guild of the channel that this webhook is following (returned for WebhookType::ChannelFollower)

source_channel: Option<WebhookChannel>

The channel that this webhook is following (returned for WebhookType::ChannelFollower).

url: Option<SecretString>

The url used for executing the webhook (returned by the webhooks OAuth2 flow).

Implementations

impl Webhook

pub async fn from_id( http: impl AsRef<Http>, webhook_id: impl Into<WebhookId>, ) -> Result<Self>

Retrieves a webhook given its Id.

This method requires authentication, whereas Webhook::from_id_with_token and Webhook::from_url do not.

Examples

Retrieve a webhook by Id:

let id = WebhookId::new(245037420704169985);
let webhook = Webhook::from_id(&http, id).await?;

Errors

Returns an Error::Http if the current user is not authenticated, or if the webhook does not exist.

May also return an Error::Json if there is an error in deserialising Discord’s response.

pub async fn from_id_with_token( http: impl AsRef<Http>, webhook_id: impl Into<WebhookId>, token: &str, ) -> Result<Self>

Retrieves a webhook given its Id and unique token.

This method does not require authentication.

Examples

Retrieve a webhook by Id and its unique token:

let id = WebhookId::new(245037420704169985);
let token = "ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV";

let webhook = Webhook::from_id_with_token(&http, id, token).await?;

Errors

Returns an Error::Http if the webhook does not exist, or if the token is invalid.

May also return an Error::Json if there is an error in deserialising Discord’s response.

pub async fn from_url(http: impl AsRef<Http>, url: &str) -> Result<Self>

Retrieves a webhook given its url.

This method does not require authentication.

Examples

Retrieve a webhook by url:

let url = "https://discord.com/api/webhooks/245037420704169985/ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV";
let webhook = Webhook::from_url(&http, url).await?;

Errors

Returns an Error::Http if the url is malformed, or otherwise if the webhook does not exist, or if the token is invalid.

May also return an Error::Json if there is an error in deserialising Discord’s response.

pub async fn delete(&self, http: impl AsRef<Http>) -> Result<()>

Deletes the webhook.

If Self::token is set, then authentication is not required. Otherwise, if it is None, then authentication is required.

Errors

Returns Error::Http if the webhook does not exist, the token is invalid, or if the webhook could not otherwise be deleted.

pub async fn edit( &mut self, cache_http: impl CacheHttp, builder: EditWebhook<'_>, ) -> Result<()>

Edits the webhook.

If Self::token is set, then authentication is not required. Otherwise, if it is None, then authentication is required.

Examples

let url = "https://discord.com/api/webhooks/245037420704169985/ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV";
let mut webhook = Webhook::from_url(&http, url).await?;

let builder = EditWebhook::new().name("new name");
webhook.edit(&http, builder).await?;

Errors

Returns an Error::Model if Self::token is None.

May also return an Error::Http if the content is malformed, or if the token is invalid.

Or may return an Error::Json if there is an error in deserialising Discord’s response.

pub async fn execute( &self, cache_http: impl CacheHttp, wait: bool, builder: ExecuteWebhook, ) -> Result<Option<Message>>

Executes a webhook with the fields set via the given builder.

Examples

Execute a webhook with message content of test:

let url = "https://discord.com/api/webhooks/245037420704169985/ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV";
let mut webhook = Webhook::from_url(&http, url).await?;

let builder = ExecuteWebhook::new().content("test");
webhook.execute(&http, false, builder).await?;

Execute a webhook with message content of test, overriding the username to serenity, and sending an embed:

use serenity::builder::{CreateEmbed, ExecuteWebhook};

let url = "https://discord.com/api/webhooks/245037420704169985/ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV";
let mut webhook = Webhook::from_url(&http, url).await?;

let embed = CreateEmbed::new()
    .title("Rust's website")
    .description(
        "Rust is a systems programming language that runs blazingly fast, prevents \
        segfaults, and guarantees thread safety.",
    )
    .url("https://rust-lang.org");

let builder = ExecuteWebhook::new().content("test").username("serenity").embed(embed);
webhook.execute(&http, false, builder).await?;

Errors

Returns an Error::Model if Self::token is None.

May also return an Error::Http if the content is malformed, or if the webhook’s token is invalid.

Or may return an Error::Json if there is an error deserialising Discord’s response.

pub async fn get_message( &self, http: impl AsRef<Http>, thread_id: Option<ChannelId>, message_id: MessageId, ) -> Result<Message>

Gets a previously sent message from the webhook.

Errors

Returns an Error::Model if the Self::token is None.

May also return Error::Http if the webhook’s token is invalid, or the given message Id does not belong to the current webhook.

Or may return an Error::Json if there is an error deserialising Discord’s response.

pub async fn edit_message( &self, cache_http: impl CacheHttp, message_id: MessageId, builder: EditWebhookMessage, ) -> Result<Message>

Edits a webhook message with the fields set via the given builder.

Note: Message contents must be under 2000 unicode code points.

Errors

Returns an Error::Model if Self::token is None, or if the message content is too long.

May also return an Error::Http if the content is malformed, the webhook’s token is invalid, or the given message Id does not belong to the current webhook.

Or may return an Error::Json if there is an error deserialising Discord’s response.

pub async fn delete_message( &self, http: impl AsRef<Http>, thread_id: Option<ChannelId>, message_id: MessageId, ) -> Result<()>

Deletes a webhook message.

Errors

Returns an Error::Model if the Self::token is None.

May also return an Error::Http if the webhook’s token is invalid or the given message Id does not belong to the current webhook.

pub async fn refresh(&mut self, http: impl AsRef<Http>) -> Result<()>

Retrieves the latest information about the webhook, editing the webhook in-place.

As this calls the Http::get_webhook_with_token function, authentication is not required.

Errors

Returns an Error::Model if the Self::token is None.

May also return an Error::Http if the http client errors or if Discord returns an error. Such as if the Webhook was deleted.

Or may return an Error::Json if there is an error deserialising Discord’s response.

pub fn url(&self) -> Result<String>

Returns the url of the webhook.

assert_eq!(hook.url(), "https://discord.com/api/webhooks/245037420704169985/ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV")

Errors

Returns an Error::Model if the Self::token is None.

Trait Implementations

impl Clone for Webhook

fn clone(&self) -> Webhook

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Webhook

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Webhook

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Webhook

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.