Struct Http

pub struct Http {
    pub ratelimiter: Option<Ratelimiter>,
    pub proxy: Option<String>,
    pub default_allowed_mentions: Option<CreateAllowedMentions>,
    /* private fields */
}

Note: For all member functions that return a Result, the Error kind will be either Error::Http or Error::Json.

Fields

ratelimiter: Option<Ratelimiter>

proxy: Option<String>

default_allowed_mentions: Option<CreateAllowedMentions>

Implementations

impl Http

pub fn new(token: &str) -> Self

pub fn application_id(&self) -> Option<ApplicationId>

pub fn set_application_id(&self, application_id: ApplicationId)

pub fn token(&self) -> &str

pub async fn add_guild_member( &self, guild_id: GuildId, user_id: UserId, map: &impl Serialize, ) -> Result<Option<Member>>

Adds a User to a Guild with a valid OAuth2 access token.

Returns the created Member object, or nothing if the user is already a guild member.

pub async fn add_member_role( &self, guild_id: GuildId, user_id: UserId, role_id: RoleId, audit_log_reason: Option<&str>, ) -> Result<()>

Adds a single Role to a Member in a Guild.

Note: Requires the Manage Roles permission and respect of role hierarchy.

pub async fn ban_user( &self, guild_id: GuildId, user_id: UserId, delete_message_days: u8, reason: Option<&str>, ) -> Result<()>

Bans a User from a Guild, removing their messages sent in the last X number of days.

Passing a delete_message_days of 0 is equivalent to not removing any messages. Up to 7 days’ worth of messages may be deleted.

Note: Requires that you have the Ban Members permission.

pub async fn bulk_ban_users( &self, guild_id: GuildId, map: &impl Serialize, reason: Option<&str>, ) -> Result<BulkBanResponse>

Bans multiple users from a Guild, optionally removing their messages.

See the Discord docs for more information.

pub async fn broadcast_typing(&self, channel_id: ChannelId) -> Result<()>

Broadcasts that the current user is typing in the given Channel.

This lasts for about 10 seconds, and will then need to be renewed to indicate that the current user is still typing.

This should rarely be used for bots, although it is a good indicator that a long-running command is still being processed.

pub async fn create_channel( &self, guild_id: GuildId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<GuildChannel>

Creates a GuildChannel in the Guild given its Id.

Refer to the Discord’s docs for information on what fields this requires.

Note: Requires the Manage Channels permission.

pub async fn create_stage_instance( &self, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<StageInstance>

Creates a stage instance.

pub async fn create_thread_from_message( &self, channel_id: ChannelId, message_id: MessageId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<GuildChannel>

Creates a thread channel in the GuildChannel given its Id, with a base message Id.

pub async fn create_thread( &self, channel_id: ChannelId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<GuildChannel>

Creates a thread channel not attached to a message in the GuildChannel given its Id.

pub async fn create_forum_post( &self, channel_id: ChannelId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<GuildChannel>

Shortcut for Self::create_forum_post_with_attachments

pub async fn create_forum_post_with_attachments( &self, channel_id: ChannelId, map: &impl Serialize, files: Vec<CreateAttachment>, audit_log_reason: Option<&str>, ) -> Result<GuildChannel>

Creates a forum post channel in the GuildChannel given its Id.

pub async fn create_emoji( &self, guild_id: GuildId, map: &Value, audit_log_reason: Option<&str>, ) -> Result<Emoji>

Creates an emoji in the given Guild with the given data.

See Guild::create_emoji for required fields.

Note: Requires the Create Guild Expressions permission.

pub async fn create_application_emoji( &self, map: &impl Serialize, ) -> Result<Emoji>

Creates an application emoji with the given data.

See Context::create_application_emoji for required fields.

pub async fn create_followup_message( &self, interaction_token: &str, map: &impl Serialize, files: Vec<CreateAttachment>, ) -> Result<Message>

Create a follow-up message for an Interaction.

Functions the same as Self::execute_webhook

pub async fn create_global_command( &self, map: &impl Serialize, ) -> Result<Command>

Creates a new global command.

New global commands will be available in all guilds after 1 hour.

Refer to Discord’s docs for field information.

Note: Creating a command with the same name as an existing command for your application will overwrite the old command.

pub async fn create_global_commands( &self, map: &impl Serialize, ) -> Result<Vec<Command>>

Creates new global application commands.

pub async fn create_guild_commands( &self, guild_id: GuildId, map: &impl Serialize, ) -> Result<Vec<Command>>

Creates new guild application commands.

pub async fn create_guild(&self, map: &Value) -> Result<PartialGuild>

Creates a guild with the data provided.

Only a PartialGuild will be immediately returned, and a full Guild will be received over a Shard, if at least one is running.

Note: This endpoint is currently limited to 10 active guilds. The limits are raised for whitelisted GameBridge applications. See the documentation on this endpoint for more info.

Examples

Create a guild called "test" in the [US West region]:

use serenity::http::Http;
use serenity::json::json;

let map = json!({
    "name": "test",
});

let _result = http.create_guild(&map).await?;

pub async fn create_guild_command( &self, guild_id: GuildId, map: &impl Serialize, ) -> Result<Command>

Creates a new guild command.

New guild commands will be available in the guild immediately.

Refer to Discord’s docs for field information.

pub async fn create_guild_integration( &self, guild_id: GuildId, integration_id: IntegrationId, map: &Value, audit_log_reason: Option<&str>, ) -> Result<()>

Creates an Integration for a Guild.

Refer to Discord’s docs for field information.

Note: Requires the Manage Guild permission.

pub async fn create_interaction_response( &self, interaction_id: InteractionId, interaction_token: &str, map: &impl Serialize, files: Vec<CreateAttachment>, ) -> Result<()>

Creates a response to an Interaction from the gateway.

Refer to Discord’s docs for the object it takes.

pub async fn create_invite( &self, channel_id: ChannelId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<RichInvite>

Creates a RichInvite for the given channel.

Refer to Discord’s docs for field information.

All fields are optional.

Note: Requires the Create Instant Invite permission.

pub async fn create_permission( &self, channel_id: ChannelId, target_id: TargetId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<()>

Creates a permission override for a member or a role in a channel.

pub async fn create_private_channel( &self, map: &Value, ) -> Result<PrivateChannel>

Creates a private channel with a user.

pub async fn create_reaction( &self, channel_id: ChannelId, message_id: MessageId, reaction_type: &ReactionType, ) -> Result<()>

Reacts to a message.

pub async fn create_super_reaction( &self, channel_id: ChannelId, message_id: MessageId, reaction_type: &ReactionType, ) -> Result<()>

Super reacts to a message.

pub async fn create_role( &self, guild_id: GuildId, body: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<Role>

Creates a role.

pub async fn create_scheduled_event( &self, guild_id: GuildId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<ScheduledEvent>

Creates a Guild Scheduled Event.

Refer to Discord’s docs for field information.

Note: Requires the Create Events permission.

pub async fn create_sticker( &self, guild_id: GuildId, map: impl IntoIterator<Item = (&'static str, String)>, file: CreateAttachment, audit_log_reason: Option<&str>, ) -> Result<Sticker>

Creates a sticker.

Note: Requires the Create Guild Expressions permission.

pub async fn create_test_entitlement( &self, sku_id: SkuId, owner: EntitlementOwner, ) -> Result<Entitlement>

Creates a test entitlement to a given SKU for a given guild or user. Discord will act as though that user/guild has entitlement in perpetuity to the SKU. As a result, the returned entitlement will have starts_at and ends_at both be None.

pub async fn create_webhook( &self, channel_id: ChannelId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<Webhook>

Creates a webhook for the given channel’s Id, passing in the given data.

This method requires authentication.

The Value is a map with the values of:

• avatar: base64-encoded 128x128 image for the webhook’s default avatar (optional);
• name: the name of the webhook, limited to between 2 and 100 characters long.

Examples

Creating a webhook named test:

use serenity::http::Http;
use serenity::json::json;
use serenity::model::prelude::*;

let channel_id = ChannelId::new(81384788765712384);
let map = json!({"name": "test"});

let webhook = http.create_webhook(channel_id, &map, None).await?;

pub async fn delete_channel( &self, channel_id: ChannelId, audit_log_reason: Option<&str>, ) -> Result<Channel>

Deletes a private channel or a channel in a guild.

pub async fn delete_stage_instance( &self, channel_id: ChannelId, audit_log_reason: Option<&str>, ) -> Result<()>

Deletes a stage instance.

pub async fn delete_emoji( &self, guild_id: GuildId, emoji_id: EmojiId, audit_log_reason: Option<&str>, ) -> Result<()>

Deletes an emoji from a guild.

See GuildId::delete_emoji for permissions requirements.

pub async fn delete_application_emoji(&self, emoji_id: EmojiId) -> Result<()>

Deletes an application emoji.

pub async fn delete_followup_message( &self, interaction_token: &str, message_id: MessageId, ) -> Result<()>

Deletes a follow-up message for an interaction.

pub async fn delete_global_command(&self, command_id: CommandId) -> Result<()>

Deletes a global command.

pub async fn delete_guild(&self, guild_id: GuildId) -> Result<()>

Deletes a guild, only if connected account owns it.

pub async fn delete_guild_command( &self, guild_id: GuildId, command_id: CommandId, ) -> Result<()>

Deletes a guild command.

pub async fn delete_guild_integration( &self, guild_id: GuildId, integration_id: IntegrationId, audit_log_reason: Option<&str>, ) -> Result<()>

Removes an integration from a guild.

pub async fn delete_invite( &self, code: &str, audit_log_reason: Option<&str>, ) -> Result<Invite>

Deletes an invite by code.

pub async fn delete_message( &self, channel_id: ChannelId, message_id: MessageId, audit_log_reason: Option<&str>, ) -> Result<()>

Deletes a message if created by us or we have specific permissions.

pub async fn delete_messages( &self, channel_id: ChannelId, map: &Value, audit_log_reason: Option<&str>, ) -> Result<()>

Deletes a bunch of messages, only works for bots.

pub async fn delete_message_reactions( &self, channel_id: ChannelId, message_id: MessageId, ) -> Result<()>

Deletes all of the Reactions associated with a Message.

Examples

use serenity::model::id::{ChannelId, MessageId};

let channel_id = ChannelId::new(7);
let message_id = MessageId::new(8);

http.delete_message_reactions(channel_id, message_id).await?;

pub async fn delete_message_reaction_emoji( &self, channel_id: ChannelId, message_id: MessageId, reaction_type: &ReactionType, ) -> Result<()>

Deletes all the reactions for a given emoji on a message.

pub async fn delete_original_interaction_response( &self, interaction_token: &str, ) -> Result<()>

Deletes the initial interaction response.

pub async fn delete_permission( &self, channel_id: ChannelId, target_id: TargetId, audit_log_reason: Option<&str>, ) -> Result<()>

Deletes a permission override from a role or a member in a channel.

pub async fn delete_reaction( &self, channel_id: ChannelId, message_id: MessageId, user_id: UserId, reaction_type: &ReactionType, ) -> Result<()>

Deletes a user’s reaction from a message.

pub async fn delete_reaction_me( &self, channel_id: ChannelId, message_id: MessageId, reaction_type: &ReactionType, ) -> Result<()>

Deletes a reaction by the current user from a message.

pub async fn delete_role( &self, guild_id: GuildId, role_id: RoleId, audit_log_reason: Option<&str>, ) -> Result<()>

Deletes a role from a server. Can’t remove the default everyone role.

pub async fn delete_scheduled_event( &self, guild_id: GuildId, event_id: ScheduledEventId, ) -> Result<()>

Deletes a Scheduled Event from a server.

Note: Requires the Manage Events permission.

pub async fn delete_sticker( &self, guild_id: GuildId, sticker_id: StickerId, audit_log_reason: Option<&str>, ) -> Result<()>

Deletes a sticker from a server.

See GuildId::delete_sticker for permissions requirements.

pub async fn delete_test_entitlement( &self, entitlement_id: EntitlementId, ) -> Result<()>

Deletes a currently active test entitlement. Discord will act as though the corresponding user/guild no longer has an entitlement to the corresponding SKU.

pub async fn delete_webhook( &self, webhook_id: WebhookId, audit_log_reason: Option<&str>, ) -> Result<()>

Deletes a Webhook given its Id.

This method requires authentication, whereas Self::delete_webhook_with_token does not.

Examples

Deletes a webhook given its Id:

use serenity::http::Http;
use serenity::model::prelude::*;

let webhook_id = WebhookId::new(245037420704169985);
http.delete_webhook(webhook_id, None).await?;
Ok(())

pub async fn delete_webhook_with_token( &self, webhook_id: WebhookId, token: &str, audit_log_reason: Option<&str>, ) -> Result<()>

Deletes a Webhook given its Id and unique token.

This method does not require authentication.

Examples

Deletes a webhook given its Id and unique token:

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

http.delete_webhook_with_token(id, token, None).await?;

pub async fn edit_channel( &self, channel_id: ChannelId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<GuildChannel>

Changes channel information.

pub async fn edit_stage_instance( &self, channel_id: ChannelId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<StageInstance>

Edits a stage instance.

pub async fn edit_emoji( &self, guild_id: GuildId, emoji_id: EmojiId, map: &Value, audit_log_reason: Option<&str>, ) -> Result<Emoji>

Changes guild emoji information.

See GuildId::edit_emoji for permissions requirements.

pub async fn edit_application_emoji( &self, emoji_id: EmojiId, map: &impl Serialize, ) -> Result<Emoji>

Changes application emoji information.

See Context::edit_application_emoji for required fields.

pub async fn edit_followup_message( &self, interaction_token: &str, message_id: MessageId, map: &impl Serialize, new_attachments: Vec<CreateAttachment>, ) -> Result<Message>

Edits a follow-up message for an interaction.

Refer to Discord’s docs for Edit Webhook Message for field information.

pub async fn get_followup_message( &self, interaction_token: &str, message_id: MessageId, ) -> Result<Message>

Get a follow-up message for an interaction.

Refer to Discord’s docs for Get Webhook Message for field information.

pub async fn edit_global_command( &self, command_id: CommandId, map: &impl Serialize, ) -> Result<Command>

Edits a global command.

Updates will be available in all guilds after 1 hour.

Refer to Discord’s docs for field information.

pub async fn edit_guild( &self, guild_id: GuildId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<PartialGuild>

Changes guild information.

pub async fn edit_guild_command( &self, guild_id: GuildId, command_id: CommandId, map: &impl Serialize, ) -> Result<Command>

Edits a guild command.

Updates for guild commands will be available immediately.

Refer to Discord’s docs for field information.

pub async fn edit_guild_command_permissions( &self, guild_id: GuildId, command_id: CommandId, map: &impl Serialize, ) -> Result<CommandPermissions>

Edits a guild command permissions.

Updates for guild commands will be available immediately.

Refer to Discord’s documentation for field information.

pub async fn edit_guild_channel_positions( &self, guild_id: GuildId, value: &Value, ) -> Result<()>

Edits the positions of a guild’s channels.

pub async fn edit_guild_mfa_level( &self, guild_id: GuildId, value: &Value, audit_log_reason: Option<&str>, ) -> Result<MfaLevel>

Edits the MFA level of a guild. Requires guild ownership.

pub async fn edit_guild_widget( &self, guild_id: GuildId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<GuildWidget>

Edits a Guild’s widget.

pub async fn edit_guild_welcome_screen( &self, guild_id: GuildId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<GuildWelcomeScreen>

Edits a guild welcome screen.

pub async fn edit_member( &self, guild_id: GuildId, user_id: UserId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<Member>

Does specific actions to a member.

pub async fn edit_message( &self, channel_id: ChannelId, message_id: MessageId, map: &impl Serialize, new_attachments: Vec<CreateAttachment>, ) -> Result<Message>

Edits a message by Id.

Note: Only the author of a message can modify it.

pub async fn crosspost_message( &self, channel_id: ChannelId, message_id: MessageId, ) -> Result<Message>

Crossposts a message by Id.

Note: Only available on news channels.

pub async fn edit_member_me( &self, guild_id: GuildId, map: &JsonMap, audit_log_reason: Option<&str>, ) -> Result<Member>

Edits the current member for the provided Guild via its Id.

pub async fn edit_nickname( &self, guild_id: GuildId, new_nickname: Option<&str>, audit_log_reason: Option<&str>, ) -> Result<()>

Edits the current user’s nickname for the provided Guild via its Id.

Pass None to reset the nickname.

pub async fn follow_news_channel( &self, news_channel_id: ChannelId, target_channel_id: ChannelId, ) -> Result<FollowedChannel>

Follow a News Channel to send messages to a target channel.

pub async fn get_original_interaction_response( &self, interaction_token: &str, ) -> Result<Message>

Gets the initial interaction response.

pub async fn edit_original_interaction_response( &self, interaction_token: &str, map: &impl Serialize, new_attachments: Vec<CreateAttachment>, ) -> Result<Message>

Edits the initial interaction response.

Refer to Discord’s docs for Edit Webhook Message for field information.

pub async fn edit_profile(&self, map: &impl Serialize) -> Result<CurrentUser>

Edits the current user’s profile settings.

pub async fn edit_role( &self, guild_id: GuildId, role_id: RoleId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<Role>

Changes a role in a guild.

pub async fn edit_role_position( &self, guild_id: GuildId, role_id: RoleId, position: u16, audit_log_reason: Option<&str>, ) -> Result<Vec<Role>>

Changes the position of a role in a guild.

pub async fn edit_scheduled_event( &self, guild_id: GuildId, event_id: ScheduledEventId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<ScheduledEvent>

Modifies a scheduled event.

Note: Requires the Manage Events permission.

pub async fn edit_sticker( &self, guild_id: GuildId, sticker_id: StickerId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<Sticker>

Changes a sticker in a guild.

See GuildId::edit_sticker for permissions requirements.

pub async fn edit_thread( &self, channel_id: ChannelId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<GuildChannel>

Edits a thread channel in the GuildChannel given its Id.

pub async fn edit_voice_state( &self, guild_id: GuildId, user_id: UserId, map: &impl Serialize, ) -> Result<()>

Changes another user’s voice state in a stage channel.

The Value is a map with values of:

• channel_id: ID of the channel the user is currently in (required)
• suppress: Bool which toggles user’s suppressed state. Setting this to false will invite the user to speak.

Example

Suppress a user

use serenity::http::Http;
use serenity::json::json;
use serenity::model::prelude::*;

let guild_id = GuildId::new(187450744427773963);
let user_id = UserId::new(150443906511667200);
let map = json!({
    "channel_id": "826929611849334784",
    "suppress": true,
});

// Edit state for another user
http.edit_voice_state(guild_id, user_id, &map).await?;

pub async fn edit_voice_state_me( &self, guild_id: GuildId, map: &impl Serialize, ) -> Result<()>

Changes the current user’s voice state in a stage channel.

The Value is a map with values of:

• channel_id: ID of the channel the user is currently in (required)
• suppress: Bool which toggles user’s suppressed state. Setting this to false will invite the user to speak.
• request_to_speak_timestamp: ISO8601 timestamp to set the user’s request to speak. This can be any present or future time.

Example

Unsuppress the current bot user

use serenity::http::Http;
use serenity::json::json;
use serenity::model::prelude::*;

let guild_id = GuildId::new(187450744427773963);
let map = json!({
    "channel_id": "826929611849334784",
    "suppress": false,
    "request_to_speak_timestamp": "2021-03-31T18:45:31.297561+00:00"
});

// Edit state for current user
http.edit_voice_state_me(guild_id, &map).await?;

pub async fn edit_voice_status( &self, channel_id: ChannelId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<()>

Changes a voice channel’s status.

pub async fn edit_webhook( &self, webhook_id: WebhookId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<Webhook>

Edits a the webhook with the given data.

The Value is a map with optional values of:

• avatar: base64-encoded 128x128 image for the webhook’s default avatar (optional);
• name: the name of the webhook, limited to between 2 and 100 characters long.

Note that, unlike with Self::create_webhook, all values are optional.

This method requires authentication, whereas Self::edit_webhook_with_token does not.

Examples

Edit the image of a webhook given its Id and unique token:

use serenity::builder::CreateAttachment;
use serenity::http::Http;
use serenity::json::json;
use serenity::model::prelude::*;

let id = WebhookId::new(245037420704169985);
let image = CreateAttachment::path("./webhook_img.png").await?;
let map = json!({
    "avatar": image.to_base64(),
});

let edited = http.edit_webhook(id, &map, None).await?;

pub async fn edit_webhook_with_token( &self, webhook_id: WebhookId, token: &str, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<Webhook>

Edits the webhook with the given data.

Refer to the documentation for Self::edit_webhook for more information.

This method does not require authentication.

Examples

Edit the name of a webhook given its Id and unique token:

use serenity::http::Http;
use serenity::json::json;
use serenity::model::prelude::*;

let id = WebhookId::new(245037420704169985);
let token = "ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV";
let map = json!({"name": "new name"});

let edited = http.edit_webhook_with_token(id, token, &map, None).await?;

pub async fn execute_webhook( &self, webhook_id: WebhookId, thread_id: Option<ChannelId>, token: &str, wait: bool, files: Vec<CreateAttachment>, map: &impl Serialize, ) -> Result<Option<Message>>

Executes a webhook, posting a Message in the webhook’s associated Channel.

This method does not require authentication.

If thread_id is not None, then the message will be sent to the thread in the webhook’s associated Channel with the corresponding Id, which will be automatically unarchived.

If wait is false, this function will return Ok(None) on success. Otherwise, it will wait for server confirmation of the message having been sent, and return Ok(Some(msg)). From the Discord docs:

waits for server confirmation of message send before response, and returns the created message body (defaults to false; when false a message that is not saved does not return an error)

The map can optionally contain the following data:

• avatar_url: Override the default avatar of the webhook with a URL.
• tts: Whether this is a text-to-speech message (defaults to false).
• username: Override the default username of the webhook.

Additionally, at least one of the following must be given:

• content: The content of the message.
• embeds: An array of rich embeds.

Note: For embed objects, all fields are registered by Discord except for height, provider, proxy_url, type (it will always be rich), video, and width. The rest will be determined by Discord.

Examples

Sending a webhook with message content of test:

use serenity::http::Http;
use serenity::json::json;
use serenity::model::prelude::*;

let id = WebhookId::new(245037420704169985);
let token = "ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV";
let map = json!({"content": "test"});
let files = vec![];

let message = http.execute_webhook(id, None, token, true, files, &map).await?;

pub async fn get_webhook_message( &self, webhook_id: WebhookId, thread_id: Option<ChannelId>, token: &str, message_id: MessageId, ) -> Result<Message>

pub async fn edit_webhook_message( &self, webhook_id: WebhookId, thread_id: Option<ChannelId>, token: &str, message_id: MessageId, map: &impl Serialize, new_attachments: Vec<CreateAttachment>, ) -> Result<Message>

Edits a webhook’s message by Id.

pub async fn delete_webhook_message( &self, webhook_id: WebhookId, thread_id: Option<ChannelId>, token: &str, message_id: MessageId, ) -> Result<()>

Deletes a webhook’s message by Id.

pub async fn get_active_maintenances(&self) -> Result<Vec<Maintenance>>

Gets the active maintenances from Discord’s Status API.

Does not require authentication.

pub async fn get_bans( &self, guild_id: GuildId, target: Option<UserPagination>, limit: Option<u8>, ) -> Result<Vec<Ban>>

Gets all the users that are banned in specific guild, with additional options for filtering.

If limit is left unset, by default at most 1000 worths of data for banned users is returned.

If target is set, then users will be filtered by Id, such that their Id comes before or after the provided UserId wrapped by the UserPagination.

pub async fn get_audit_logs( &self, guild_id: GuildId, action_type: Option<Action>, user_id: Option<UserId>, before: Option<AuditLogEntryId>, limit: Option<u8>, ) -> Result<AuditLogs>

Gets all audit logs in a specific guild.

pub async fn get_automod_rules(&self, guild_id: GuildId) -> Result<Vec<Rule>>

Retrieves all auto moderation rules in a guild.

This method requires MANAGE_GUILD permissions.

pub async fn get_automod_rule( &self, guild_id: GuildId, rule_id: RuleId, ) -> Result<Rule>

Retrieves an auto moderation rule in a guild.

This method requires MANAGE_GUILD permissions.

pub async fn create_automod_rule( &self, guild_id: GuildId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<Rule>

Creates an auto moderation rule in a guild.

This method requires MANAGE_GUILD permissions.

pub async fn edit_automod_rule( &self, guild_id: GuildId, rule_id: RuleId, map: &impl Serialize, audit_log_reason: Option<&str>, ) -> Result<Rule>

Retrieves an auto moderation rule in a guild.

This method requires MANAGE_GUILD permissions.

pub async fn delete_automod_rule( &self, guild_id: GuildId, rule_id: RuleId, audit_log_reason: Option<&str>, ) -> Result<()>

Deletes an auto moderation rule in a guild.

This method requires MANAGE_GUILD permissions.

pub async fn get_bot_gateway(&self) -> Result<BotGateway>

Gets current bot gateway.

pub async fn get_channel_invites( &self, channel_id: ChannelId, ) -> Result<Vec<RichInvite>>

Gets all invites for a channel.

pub async fn get_channel_thread_members( &self, channel_id: ChannelId, ) -> Result<Vec<ThreadMember>>

Gets all thread members for a thread.

pub async fn get_guild_active_threads( &self, guild_id: GuildId, ) -> Result<ThreadsData>

Gets all active threads from a guild.

pub async fn get_channel_archived_public_threads( &self, channel_id: ChannelId, before: Option<u64>, limit: Option<u64>, ) -> Result<ThreadsData>

Gets all archived public threads from a channel.

pub async fn get_channel_archived_private_threads( &self, channel_id: ChannelId, before: Option<u64>, limit: Option<u64>, ) -> Result<ThreadsData>

Gets all archived private threads from a channel.

pub async fn get_channel_joined_archived_private_threads( &self, channel_id: ChannelId, before: Option<u64>, limit: Option<u64>, ) -> Result<ThreadsData>

Gets all archived private threads joined from a channel.

pub async fn join_thread_channel(&self, channel_id: ChannelId) -> Result<()>

Joins a thread channel.

pub async fn leave_thread_channel(&self, channel_id: ChannelId) -> Result<()>

Leaves a thread channel.

pub async fn add_thread_channel_member( &self, channel_id: ChannelId, user_id: UserId, ) -> Result<()>

Adds a member to a thread channel.

pub async fn remove_thread_channel_member( &self, channel_id: ChannelId, user_id: UserId, ) -> Result<()>

Removes a member from a thread channel.

pub async fn get_thread_channel_member( &self, channel_id: ChannelId, user_id: UserId, with_member: bool, ) -> Result<ThreadMember>

pub async fn get_channel_webhooks( &self, channel_id: ChannelId, ) -> Result<Vec<Webhook>>

Retrieves the webhooks for the given channel’s Id.

This method requires authentication.

Examples

Retrieve all of the webhooks owned by a channel:

let channel_id = ChannelId::new(81384788765712384);

let webhooks = http.get_channel_webhooks(channel_id).await?;

pub async fn get_channel(&self, channel_id: ChannelId) -> Result<Channel>

Gets channel information.

pub async fn get_channels(&self, guild_id: GuildId) -> Result<Vec<GuildChannel>>

Gets all channels in a guild.

pub async fn get_stage_instance( &self, channel_id: ChannelId, ) -> Result<StageInstance>

Gets a stage instance.

pub async fn get_poll_answer_voters( &self, channel_id: ChannelId, message_id: MessageId, answer_id: AnswerId, after: Option<UserId>, limit: Option<u8>, ) -> Result<Vec<User>>

Get a list of users that voted for this specific answer.

pub async fn expire_poll( &self, channel_id: ChannelId, message_id: MessageId, ) -> Result<Message>

pub async fn get_current_application_info( &self, ) -> Result<CurrentApplicationInfo>

Gets information about the current application.

Note: Only applications may use this endpoint.

pub async fn get_current_user(&self) -> Result<CurrentUser>

Gets information about the user we’re connected with.

pub async fn get_emojis(&self, guild_id: GuildId) -> Result<Vec<Emoji>>

Gets all emojis of a guild.

pub async fn get_emoji( &self, guild_id: GuildId, emoji_id: EmojiId, ) -> Result<Emoji>

Gets information about an emoji in a guild.

pub async fn get_application_emojis(&self) -> Result<Vec<Emoji>>

Gets all emojis for the current application.

pub async fn get_application_emoji(&self, emoji_id: EmojiId) -> Result<Emoji>

Gets information about an application emoji.

pub async fn get_entitlements( &self, user_id: Option<UserId>, sku_ids: Option<Vec<SkuId>>, before: Option<EntitlementId>, after: Option<EntitlementId>, limit: Option<u8>, guild_id: Option<GuildId>, exclude_ended: Option<bool>, ) -> Result<Vec<Entitlement>>

Gets all entitlements for the current app, active and expired.

pub async fn get_gateway(&self) -> Result<Gateway>

Gets current gateway.

pub async fn get_global_commands(&self) -> Result<Vec<Command>>

Fetches all of the global commands for your application.

pub async fn get_global_commands_with_localizations( &self, ) -> Result<Vec<Command>>

Fetches all of the global commands for your application with localizations.

pub async fn get_global_command(&self, command_id: CommandId) -> Result<Command>

Fetches a global commands for your application by its Id.

pub async fn get_guild(&self, guild_id: GuildId) -> Result<PartialGuild>

Gets guild information.

pub async fn get_guild_with_counts( &self, guild_id: GuildId, ) -> Result<PartialGuild>

Gets guild information with counts.

pub async fn get_guild_commands( &self, guild_id: GuildId, ) -> Result<Vec<Command>>

Fetches all of the guild commands for your application for a specific guild.

pub async fn get_guild_commands_with_localizations( &self, guild_id: GuildId, ) -> Result<Vec<Command>>

Fetches all of the guild commands with localizations for your application for a specific guild.

pub async fn get_guild_command( &self, guild_id: GuildId, command_id: CommandId, ) -> Result<Command>

Fetches a guild command by its Id.

pub async fn get_guild_commands_permissions( &self, guild_id: GuildId, ) -> Result<Vec<CommandPermissions>>

Fetches all of the guild commands permissions for your application for a specific guild.

pub async fn get_guild_command_permissions( &self, guild_id: GuildId, command_id: CommandId, ) -> Result<CommandPermissions>

Gives the guild command permission for your application for a specific guild.

pub async fn get_guild_widget(&self, guild_id: GuildId) -> Result<GuildWidget>

Gets a guild widget information.

pub async fn get_guild_preview(&self, guild_id: GuildId) -> Result<GuildPreview>

Gets a guild preview.

pub async fn get_guild_welcome_screen( &self, guild_id: GuildId, ) -> Result<GuildWelcomeScreen>

Gets a guild welcome screen information.

pub async fn get_guild_integrations( &self, guild_id: GuildId, ) -> Result<Vec<Integration>>

Gets integrations that a guild has.

pub async fn get_guild_invites( &self, guild_id: GuildId, ) -> Result<Vec<RichInvite>>

Gets all invites to a guild.

pub async fn get_guild_vanity_url(&self, guild_id: GuildId) -> Result<String>

Gets a guild’s vanity URL if it has one.

pub async fn get_guild_members( &self, guild_id: GuildId, limit: Option<u64>, after: Option<u64>, ) -> Result<Vec<Member>>

Gets the members of a guild. Optionally pass a limit and the Id of the user to offset the result by.

pub async fn get_guild_prune_count( &self, guild_id: GuildId, days: u8, ) -> Result<GuildPrune>

Gets the amount of users that can be pruned.

pub async fn get_guild_regions( &self, guild_id: GuildId, ) -> Result<Vec<VoiceRegion>>

Gets regions that a guild can use. If a guild has the VIP_REGIONS feature enabled, then additional VIP-only regions are returned.

pub async fn get_guild_role( &self, guild_id: GuildId, role_id: RoleId, ) -> Result<Role>

Retrieves a specific role in a Guild.

pub async fn get_guild_roles(&self, guild_id: GuildId) -> Result<Vec<Role>>

Retrieves a list of roles in a Guild.

pub async fn get_scheduled_event( &self, guild_id: GuildId, event_id: ScheduledEventId, with_user_count: bool, ) -> Result<ScheduledEvent>

Gets a scheduled event by Id.

Note: Requires the View Channel permission for the channel associated with the event.

pub async fn get_scheduled_events( &self, guild_id: GuildId, with_user_count: bool, ) -> Result<Vec<ScheduledEvent>>

Gets a list of all scheduled events for the corresponding guild.

Note: Requires the View Channel permission at the guild level.

pub async fn get_scheduled_event_users( &self, guild_id: GuildId, event_id: ScheduledEventId, limit: Option<u64>, target: Option<UserPagination>, with_member: Option<bool>, ) -> Result<Vec<ScheduledEventUser>>

Gets a list of all interested users for the corresponding scheduled event, with additional options for filtering.

If limit is left unset, by default at most 100 users are returned.

If target is set, then users will be filtered by Id, such that their Id comes before or after the provided UserId wrapped by the UserPagination.

If with_member is set to Some(true), then the member field of the user struct will be populated with Guild Member information, if the interested user is a member of the guild the event takes place in.

Note: Requires the [View Channel] permission for the channel associated with the event.

pub async fn get_guild_stickers( &self, guild_id: GuildId, ) -> Result<Vec<Sticker>>

Retrieves a list of stickers in a Guild.

pub async fn get_guild_sticker( &self, guild_id: GuildId, sticker_id: StickerId, ) -> Result<Sticker>

Retrieves a single sticker in a Guild.

pub async fn get_guild_webhooks( &self, guild_id: GuildId, ) -> Result<Vec<Webhook>>

Retrieves the webhooks for the given guild’s Id.

This method requires authentication.

Examples

Retrieve all of the webhooks owned by a guild:

let guild_id = GuildId::new(81384788765712384);

let webhooks = http.get_guild_webhooks(guild_id).await?;

pub async fn get_guilds( &self, target: Option<GuildPagination>, limit: Option<u64>, ) -> Result<Vec<GuildInfo>>

Gets a paginated list of the current user’s guilds.

The limit has a maximum value of 100.

Discord’s documentation

Examples

Get the first 10 guilds after a certain guild’s Id:

use serenity::http::GuildPagination;
use serenity::model::id::GuildId;

let guild_id = GuildId::new(81384788765712384);

let guilds = http.get_guilds(Some(GuildPagination::After(guild_id)), Some(10)).await?;

pub async fn get_current_user_guild_member( &self, guild_id: GuildId, ) -> Result<Member>

Returns a guild Member object for the current user.

Authorization

This method only works for user tokens with the GuildsMembersRead OAuth2 scope.

Examples

Get the member object for the current user within the specified guild.

use serenity::model::id::GuildId;

let guild_id = GuildId::new(81384788765712384);

let member = http.get_current_user_guild_member(guild_id).await?;

See the Discord Developer Portal documentation for more.

pub async fn get_invite( &self, code: &str, member_counts: bool, expiration: bool, event_id: Option<ScheduledEventId>, ) -> Result<Invite>

Gets information about a specific invite.

Arguments

• code - The invite code.
• member_counts - Whether to include information about the current number of members in the server that the invite belongs to.
• expiration - Whether to include information about when the invite expires.
• event_id - An optional server event ID to include with the invite.

More information about these arguments can be found on Discord’s API documentation.

pub async fn get_member( &self, guild_id: GuildId, user_id: UserId, ) -> Result<Member>

Gets member of a guild.

pub async fn get_message( &self, channel_id: ChannelId, message_id: MessageId, ) -> Result<Message>

Gets a message by an Id, bots only.

pub async fn get_messages( &self, channel_id: ChannelId, target: Option<MessagePagination>, limit: Option<u8>, ) -> Result<Vec<Message>>

Gets X messages from a channel.

pub async fn get_sticker_pack( &self, sticker_pack_id: StickerPackId, ) -> Result<StickerPack>

Retrieves a specific StickerPack from it’s StickerPackId

pub async fn get_nitro_stickers(&self) -> Result<Vec<StickerPack>>

Retrieves a list of all nitro sticker packs.

pub async fn get_pins(&self, channel_id: ChannelId) -> Result<Vec<Message>>

Gets all pins of a channel.

pub async fn get_reaction_users( &self, channel_id: ChannelId, message_id: MessageId, reaction_type: &ReactionType, limit: u8, after: Option<u64>, ) -> Result<Vec<User>>

Gets user Ids based on their reaction to a message. This endpoint is dumb.

pub async fn get_skus(&self) -> Result<Vec<Sku>>

Gets all SKUs for the current application.

pub async fn get_sticker(&self, sticker_id: StickerId) -> Result<Sticker>

Gets a sticker.

pub async fn get_unresolved_incidents(&self) -> Result<Vec<Incident>>

Gets the current unresolved incidents from Discord’s Status API.

Does not require authentication.

pub async fn get_upcoming_maintenances(&self) -> Result<Vec<Maintenance>>

Gets the upcoming (planned) maintenances from Discord’s Status API.

Does not require authentication.

pub async fn get_user(&self, user_id: UserId) -> Result<User>

Gets a user by Id.

pub async fn get_user_connections(&self) -> Result<Vec<Connection>>

Gets the current user’s third party connections.

This method only works for user tokens with the Connections OAuth2 scope.

pub async fn get_user_dm_channels(&self) -> Result<Vec<PrivateChannel>>

Gets our DM channels.

pub async fn get_voice_regions(&self) -> Result<Vec<VoiceRegion>>

Gets all voice regions.

pub async fn get_webhook(&self, webhook_id: WebhookId) -> Result<Webhook>

Retrieves a webhook given its Id.

This method requires authentication, whereas Http::get_webhook_with_token and Http::get_webhook_from_url do not.

Examples

Retrieve a webhook by Id:

let id = WebhookId::new(245037420704169985);
let webhook = http.get_webhook(id).await?;

pub async fn get_webhook_with_token( &self, webhook_id: WebhookId, token: &str, ) -> Result<Webhook>

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 = http.get_webhook_with_token(id, token).await?;

pub async fn get_webhook_from_url(&self, url: &str) -> Result<Webhook>

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 = http.get_webhook_from_url(url).await?;

pub async fn kick_member( &self, guild_id: GuildId, user_id: UserId, reason: Option<&str>, ) -> Result<()>

Kicks a member from a guild with a provided reason.

pub async fn leave_guild(&self, guild_id: GuildId) -> Result<()>

Leaves a guild.

pub async fn send_message( &self, channel_id: ChannelId, files: Vec<CreateAttachment>, map: &impl Serialize, ) -> Result<Message>

Sends a message to a channel.

Errors

Returns an HttpError::UnsuccessfulRequest if the files are too large to send.

pub async fn pin_message( &self, channel_id: ChannelId, message_id: MessageId, audit_log_reason: Option<&str>, ) -> Result<()>

Pins a message in a channel.

pub async fn remove_ban( &self, guild_id: GuildId, user_id: UserId, audit_log_reason: Option<&str>, ) -> Result<()>

Unbans a user from a guild.

pub async fn remove_member_role( &self, guild_id: GuildId, user_id: UserId, role_id: RoleId, audit_log_reason: Option<&str>, ) -> Result<()>

Deletes a single Role from a Member in a Guild.

Note: Requires the Manage Roles permission and respect of role hierarchy.

pub async fn search_guild_members( &self, guild_id: GuildId, query: &str, limit: Option<u64>, ) -> Result<Vec<Member>>

Returns a list of Members in a Guild whose username or nickname starts with a provided string.

pub async fn start_guild_prune( &self, guild_id: GuildId, days: u8, audit_log_reason: Option<&str>, ) -> Result<GuildPrune>

Starts removing some members from a guild based on the last time they’ve been online.

pub async fn start_integration_sync( &self, guild_id: GuildId, integration_id: IntegrationId, ) -> Result<()>

Starts syncing an integration with a guild.

pub fn start_typing(self: &Arc<Self>, channel_id: ChannelId) -> Typing

Starts typing in the specified Channel for an indefinite period of time.

Returns Typing that is used to trigger the typing. Typing::stop must be called on the returned struct to stop typing. Note that on some clients, typing may persist for a few seconds after Typing::stop is called. Typing is also stopped when the struct is dropped.

If a message is sent while typing is triggered, the user will stop typing for a brief period of time and then resume again until either Typing::stop is called or the struct is dropped.

This should rarely be used for bots, although it is a good indicator that a long-running command is still being processed.

Examples

// Initiate typing (assuming http is `Arc<Http>`)
let channel_id = ChannelId::new(7);
let typing = http.start_typing(channel_id);

// Run some long-running process
long_process();

// Stop typing
typing.stop();

pub async fn unpin_message( &self, channel_id: ChannelId, message_id: MessageId, audit_log_reason: Option<&str>, ) -> Result<()>

Unpins a message from a channel.

pub async fn fire<T: DeserializeOwned>(&self, req: Request<'_>) -> Result<T>

Fires off a request, deserializing the response reader via the given type bound.

If you don’t need to deserialize the response and want the response instance itself, use Self::request.

Examples

Create a new message and deserialize the response into a Message:

use serenity::{
    http::{LightMethod, Request, Route},
    model::prelude::*,
};

let bytes = vec![
    // payload bytes here
];
let channel_id = ChannelId::new(381880193700069377);
let route = Route::ChannelMessages { channel_id };

let mut request = Request::new(route, LightMethod::Post).body(Some(bytes));

let message = http.fire::<Message>(request).await?;

println!("Message content: {}", message.content);

Errors

If there is an error, it will be either Error::Http or Error::Json.

pub async fn request(&self, req: Request<'_>) -> Result<ReqwestResponse>

Performs a request, ratelimiting it if necessary.

Returns the raw reqwest Response. Use Self::fire to deserialize the response into some type.

Examples

Send a body of bytes over the create message endpoint:

use serenity::http::{LightMethod, Request, Route};

let bytes = vec![
    // payload bytes here
];
let channel_id = ChannelId::new(381880193700069377);
let route = Route::ChannelMessages { channel_id };

let mut request = Request::new(route, LightMethod::Post).body(Some(bytes));

let response = http.request(request).await?;

println!("Response successful?: {}", response.status().is_success());

Trait Implementations

impl AsRef<Http> for (&Arc<Cache>, &Http)

fn as_ref(&self) -> &Http

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Http> for Arc<Context>

fn as_ref(&self) -> &Http

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Http> for Context

fn as_ref(&self) -> &Http

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Http> for Http

fn as_ref(&self) -> &Http

Converts this type into a shared reference of the (usually inferred) input type.

impl CacheHttp for Http

fn http(&self) -> &Http

fn cache(&self) -> Option<&Arc<Cache>>

impl Debug for Http

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

Formats the value using the given formatter.