Struct serenity::http::client::Http[][src]

pub struct Http {
    pub ratelimiter: Ratelimiter,
    pub ratelimiter_disabled: bool,
    pub proxy: Option<Url>,
    pub token: String,
    pub application_id: u64,
    // some fields omitted
}
Expand description

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

Fields

ratelimiter: Ratelimiterratelimiter_disabled: boolproxy: Option<Url>token: Stringapplication_id: u64

Implementations

Adds a single Role to a Member in a Guild.

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

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.

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.

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.

Creates a stage instance.

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

Creates a private thread channel in the GuildChannel given its Id.

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

View the source code for Guild::create_emoji method to see what fields this requires.

Note: Requires the Manage Emojis permission.

Create a follow-up message for an Interaction.

Functions the same as Self::execute_webhook

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.

Creates new global application commands.

Creates new guild application commands.

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 serde_json::json;
use serenity::http::Http;

let map = json!({
    "name": "test",
    "region": "us-west",
});

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

Creates a new guild command.

New guild commands will be available in the guild immediately.

Refer to Discord’s docs for field information.

Creates an Integration for a Guild.

Refer to Discord’s docs for field information.

Note: Requires the Manage Guild permission.

Creates a response to an Interaction from the gateway.

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

Creates a RichInvite for the given channel.

Refer to Discord’s docs for field information.

All fields are optional.

Note: Requires the Create Invite permission.

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

Creates a private channel with a user.

Reacts to a message.

Creates a role.

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 serde_json::json;
use serenity::http::Http;

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

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

Deletes a private channel or a channel in a guild.

Deletes a stage instance.

Deletes an emoji from a server.

Deletes a follow-up message for an interaction.

Deletes a global command.

Deletes a guild, only if connected account owns it.

Deletes a guild command.

Removes an integration from a guild.

Deletes an invite by code.

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

Deletes a bunch of messages, only works for bots.

Deletes all of the Reactions associated with a Message.

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

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

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

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

Deletes the initial interaction response.

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

Deletes a reaction from a message if owned by us or we have specific permissions.

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

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;

// Due to the `delete_webhook` function requiring you to authenticate, you
// must have set the token first.
let http = Http::default();

http.delete_webhook(245037420704169985).await?;
Ok(())

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 = 245037420704169985;
let token = "ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV";

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

Changes channel information.

Edits a stage instance.

Changes emoji information.

Edits a follow-up message for an interaction.

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

Get a follow-up message for an interaction.

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

Edits a global command.

Updates will be available in all guilds after 1 hour.

Refer to Discord’s docs for field information.

Changes guild information.

Edits a guild command.

Updates for guild commands will be available immediately.

Refer to Discord’s docs for field information.

Edits a guild command permissions.

Updates for guild commands will be available immediately.

Refer to Discord’s documentation for field information.

Edits a guild commands permissions.

Updates for guild commands will be available immediately.

Refer to Discord’s documentation for field information.

Edits the positions of a guild’s channels.

Edits a Guild’s widget.

Edits a guild welcome screen.

Does specific actions to a member.

Edits a message by Id.

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

Crossposts a message by Id.

Note: Only available on announcements channels.

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

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

Pass None to reset the nickname.

Gets the initial interaction response.

Edits the initial interaction response.

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

Edits the current user’s profile settings.

Changes a role in a guild.

Changes the position of a role in a guild.

Edits a thread channel in the GuildChannel given its Id.

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)
  • supress: Bool which toggles user’s suppressed state. Setting this to false will invite the user to speak.
Example

Suppress a user

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

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

let map = value.as_object().unwrap();

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

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)
  • supress: 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 serde_json::json;
use serenity::http::Http;

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

let map = value.as_object().unwrap();

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

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 serde_json::json;
use serenity::http::Http;

let id = 245037420704169985;
let image = serenity::utils::read_image("./webhook_img.png")?;
let map = json!({
    "avatar": image,
});

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

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 serde_json::json;
use serenity::http::Http;

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

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

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

This method does not require authentication.

Pass true to wait to wait for server confirmation of the message sending before receiving a response. 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 serde_json::json;
use serenity::http::Http;

let id = 245037420704169985;
let token = "ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV";
let value = json!({"content": "test"});
let map = value.as_object().unwrap();

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

Send file(s) over a webhook.

Errors

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

Edits a webhook’s message by Id.

Deletes a webhook’s messsage by Id.

Gets the active maintenances from Discord’s Status API.

Does not require authentication.

Gets all the users that are banned in specific guild.

Gets all audit logs in a specific guild.

Gets current bot gateway.

Gets all invites for a channel.

Gets all thread members for a thread.

Gets all active threads from a guild.

👎 Deprecated:

Use get_guild_active_threads instead

Gets all active threads from a channel.

Gets all archived public threads from a channel.

Gets all archived private threads from a channel.

Gets all archived private threads joined from a channel.

Joins a thread channel.

Leaves a thread channel.

Adds a member to a thread channel.

Removes a member from a thread channel.

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 = 81384788765712384;

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

Gets channel information.

Gets all channels in a guild.

Gets a stage instance.

Gets information about the current application.

Note: Only applications may use this endpoint.

Gets information about the user we’re connected with.

Gets all emojis of a guild.

Gets information about an emoji in a guild.

Gets current gateway.

Fetches all of the global commands for your application.

Fetches a global commands for your application by its Id.

Gets guild information.

Gets guild information with counts.

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

Fetches a guild command by its Id.

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

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

👎 Deprecated:

get_guild_embed was renamed to get_guild_widget

Gets a guild embed information.

Gets a guild widget information.

Gets a guild preview.

Gets a guild welcome screen information.

Gets integrations that a guild has.

Gets all invites to a guild.

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

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

Gets the amount of users that can be pruned.

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

Retrieves a list of roles in a Guild.

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 = 81384788765712384;

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

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, model::id::GuildId};

let guild_id = GuildId(81384788765712384);

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

Gets information about a specific invite.

Gets member of a guild.

Gets a message by an Id, bots only.

Gets X messages from a channel.

Gets all pins of a channel.

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

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

Does not require authentication.

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

Does not require authentication.

Gets a user by Id.

Gets the current user’s third party connections.

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

Gets our DM channels.

Gets all voice regions.

Retrieves a webhook given its Id.

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

Examples

Retrieve a webhook by Id:

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

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 = 245037420704169985;
let token = "ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV";

let webhook = http.get_webhook_with_token(id, token).await?;

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?;

Kicks a member from a guild.

Kicks a member from a guild with a provided reason.

Leaves a guild.

Sends file(s) to a channel.

Errors

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

Sends a message to a channel.

Pins a message in a channel.

Unbans a user from a guild.

Deletes a single Role from a Member in a Guild.

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

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

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

Starts syncing an integration with a guild.

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 typing = http.start_typing(7)?;

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

// Stop typing
typing.stop();

Unpins a message from a channel.

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 via the RouteInfo::CreateMessage endpoint and deserialize the response into a Message:

use serenity::{
    http::{
        routing::RouteInfo,
        request::RequestBuilder,
    },
    model::channel::Message,
};

let bytes = vec![
    // payload bytes here
];
let channel_id = 381880193700069377;
let route_info = RouteInfo::CreateMessage { channel_id };

let mut request = RequestBuilder::new(route_info);
request.body(Some(&bytes));

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

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

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

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 RouteInfo::CreateMessage endpoint:

use serenity::http::{
    request::RequestBuilder,
    routing::RouteInfo,
};

let bytes = vec![
    // payload bytes here
];
let channel_id = 381880193700069377;
let route_info = RouteInfo::CreateMessage { channel_id };

let mut request = RequestBuilder::new(route_info);
request.body(Some(&bytes));

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

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

Trait Implementations

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Performs the conversion.

Should always be Self

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more