Struct twilight_http::client::Client

pub struct Client { /* private fields */ }

Twilight’s http client.

Almost all of the client methods require authentication, and as such, the client must be supplied with a Discord Token. Get yours here.

Interactions

HTTP interaction requests may be accessed via the Client::interaction method.

OAuth

To use Bearer tokens prefix the token with "Bearer ", including the space at the end like so:

use std::env;
use twilight_http::Client;

let bearer = env::var("BEARER_TOKEN")?;
let token = format!("Bearer {bearer}");

let client = Client::new(token);

Using the client in multiple tasks

To use a client instance in multiple tasks, consider wrapping it in an std::sync::Arc or std::rc::Rc.

Unauthorized behavior

When the client encounters an Unauthorized response it will take note that the configured token is invalid. This may occur when the token has been revoked or expired. When this happens, you must create a new client with the new token. The client will no longer execute requests in order to prevent API bans and will always return ErrorType::Unauthorized.

Examples

Create a client called client:

use twilight_http::Client;

let client = Client::new("my token".to_owned());

Use ClientBuilder to create a client called client, with a shorter timeout:

use std::time::Duration;
use twilight_http::Client;

let client = Client::builder()
    .token("my token".to_owned())
    .timeout(Duration::from_secs(5))
    .build();

All the examples on this page assume you have already created a client, and have named it client.

Implementations

impl Client

pub fn new(token: String) -> Self

Create a new client with a token.

pub fn builder() -> ClientBuilder

Create a new builder to create a client.

Refer to its documentation for more information.

pub fn token(&self) -> Option<&str>

Retrieve an immutable reference to the token used by the client.

If the initial token provided is not prefixed with Bot , it will be, and this method reflects that.

pub const fn interaction( &self, application_id: Id<ApplicationMarker> ) -> InteractionClient<'_>

Create an interface for using interactions.

An application ID is required to be passed in to use interactions. The ID may be retrieved via current_user_application and cached for use with this method.

Examples

Retrieve the application ID and then use an interaction request:

use std::env;
use twilight_http::Client;

let client = Client::new(env::var("DISCORD_TOKEN")?);

// Cache the application ID for repeated use later in the process.
let application_id = {
    let response = client.current_user_application().await?;

    response.model().await?.id
};

// Later in the process...
let commands = client
    .interaction(application_id)
    .global_commands()
    .await?
    .models()
    .await?;

println!("there are {} global commands", commands.len());

pub const fn default_allowed_mentions(&self) -> Option<&AllowedMentions>

Get an immutable reference to the default AllowedMentions for sent messages.

pub fn ratelimiter(&self) -> Option<&dyn Ratelimiter>

Get the Ratelimiter used by the client internally.

This will return None only if ratelimit handling has been explicitly disabled in the ClientBuilder.

pub const fn auto_moderation_rule( &self, guild_id: Id<GuildMarker>, auto_moderation_rule_id: Id<AutoModerationRuleMarker> ) -> GetAutoModerationRule<'_>

Get an auto moderation rule in a guild.

Requires the MANAGE_GUILD permission.

pub const fn auto_moderation_rules( &self, guild_id: Id<GuildMarker> ) -> GetGuildAutoModerationRules<'_>

Get the auto moderation rules in a guild.

Requires the MANAGE_GUILD permission.

pub const fn create_auto_moderation_rule<'a>( &'a self, guild_id: Id<GuildMarker>, name: &'a str, event_type: AutoModerationEventType ) -> CreateAutoModerationRule<'a>

Create an auto moderation rule within a guild.

Requires the MANAGE_GUILD permission.

Examples

Create a rule that deletes messages that contain the word “darn”:

use twilight_http::Client;
use twilight_model::{guild::auto_moderation::AutoModerationEventType, id::Id};

let client = Client::new("my token".to_owned());

let guild_id = Id::new(1);
client
    .create_auto_moderation_rule(guild_id, "no darns", AutoModerationEventType::MessageSend)
    .action_block_message()
    .enabled(true)
    .with_keyword(&["darn"])
    .await?;

pub const fn delete_auto_moderation_rule( &self, guild_id: Id<GuildMarker>, auto_moderation_rule_id: Id<AutoModerationRuleMarker> ) -> DeleteAutoModerationRule<'_>

Delete an auto moderation rule in a guild.

Requires the MANAGE_GUILD permission.

pub const fn update_auto_moderation_rule( &self, guild_id: Id<GuildMarker>, auto_moderation_rule_id: Id<AutoModerationRuleMarker> ) -> UpdateAutoModerationRule<'_>

Update an auto moderation rule in a guild.

Requires the MANAGE_GUILD permission.

pub const fn audit_log(&self, guild_id: Id<GuildMarker>) -> GetAuditLog<'_>

Get the audit log for a guild.

Examples

use twilight_model::id::Id;

let guild_id = Id::new(101);
let audit_log = client.audit_log(guild_id).await?;

pub const fn bans(&self, guild_id: Id<GuildMarker>) -> GetBans<'_>

Retrieve the bans for a guild.

Examples

Retrieve the bans for guild 1:

use twilight_model::id::Id;
let guild_id = Id::new(1);

let bans = client.bans(guild_id).await?;

pub const fn ban( &self, guild_id: Id<GuildMarker>, user_id: Id<UserMarker> ) -> GetBan<'_>

Get information about a ban of a guild.

Includes the user banned and the reason.

pub const fn create_ban( &self, guild_id: Id<GuildMarker>, user_id: Id<UserMarker> ) -> CreateBan<'_>

Bans a user from a guild, optionally with the number of seconds’ worth of messages to delete and the reason.

Examples

Ban user 200 from guild 100, deleting 86_400 second’s (this is equivalent to 1 day) worth of messages, for the reason "memes":

use twilight_model::id::Id;
let guild_id = Id::new(100);
let user_id = Id::new(200);
client
    .create_ban(guild_id, user_id)
    .delete_message_seconds(86_400)?
    .reason("memes")?
    .await?;

pub const fn delete_ban( &self, guild_id: Id<GuildMarker>, user_id: Id<UserMarker> ) -> DeleteBan<'_>

Remove a ban from a user in a guild.

Examples

Unban user 200 from guild 100:

use twilight_model::id::Id;
let guild_id = Id::new(100);
let user_id = Id::new(200);

client.delete_ban(guild_id, user_id).await?;

pub const fn channel(&self, channel_id: Id<ChannelMarker>) -> GetChannel<'_>

Get a channel by its ID.

Examples

Get channel 100:

let channel_id = Id::new(100);
let channel = client.channel(channel_id).await?;

pub const fn delete_channel( &self, channel_id: Id<ChannelMarker> ) -> DeleteChannel<'_>

Delete a channel by ID.

pub const fn update_channel( &self, channel_id: Id<ChannelMarker> ) -> UpdateChannel<'_>

Update a channel.

pub const fn follow_news_channel( &self, channel_id: Id<ChannelMarker>, webhook_channel_id: Id<ChannelMarker> ) -> FollowNewsChannel<'_>

Follows a news channel by Id<ChannelMarker>.

The type returned is FollowedChannel.

pub const fn channel_invites( &self, channel_id: Id<ChannelMarker> ) -> GetChannelInvites<'_>

Get the invites for a guild channel.

Requires the MANAGE_CHANNELS permission. This method only works if the channel is a guild channel.

pub const fn channel_messages( &self, channel_id: Id<ChannelMarker> ) -> GetChannelMessages<'_>

Get channel messages, by Id<ChannelMarker>.

Only one of after, around, and before can be specified at a time. Once these are specified, the type returned is GetChannelMessagesConfigured.

If limit is unspecified, the default set by Discord is 50.

Examples

use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new("my token".to_owned());
let channel_id = Id::new(123);
let message_id = Id::new(234);
let limit: u16 = 6;

let messages = client
    .channel_messages(channel_id)
    .before(message_id)
    .limit(limit)?
    .await?;

Errors

Returns an error of type ValidationErrorType::GetChannelMessages if the amount is less than 1 or greater than 100.

pub const fn delete_channel_permission( &self, channel_id: Id<ChannelMarker> ) -> DeleteChannelPermission<'_>

pub const fn update_channel_permission( &self, channel_id: Id<ChannelMarker>, permission_overwrite: &PermissionOverwrite ) -> UpdateChannelPermission<'_>

Update the permissions for a role or a user in a channel.

Examples:

Create permission overrides for a role to view the channel, but not send messages:

use twilight_model::{
    guild::Permissions,
    http::permission_overwrite::{PermissionOverwrite, PermissionOverwriteType},
    id::{marker::RoleMarker, Id},
};

let channel_id = Id::new(123);
let role_id: Id<RoleMarker> = Id::new(432);
let permission_overwrite = PermissionOverwrite {
    allow: Some(Permissions::VIEW_CHANNEL),
    deny: Some(Permissions::SEND_MESSAGES),
    id: role_id.cast(),
    kind: PermissionOverwriteType::Role,
};

client
    .update_channel_permission(channel_id, &permission_overwrite)
    .await?;

pub const fn channel_webhooks( &self, channel_id: Id<ChannelMarker> ) -> GetChannelWebhooks<'_>

Get all the webhooks of a channel.

pub const fn current_user(&self) -> GetCurrentUser<'_>

Get information about the current user.

pub const fn current_user_guild_member( &self, guild_id: Id<GuildMarker> ) -> GetCurrentUserGuildMember<'_>

Get information about the current user in a guild.

pub const fn current_authorization( &self ) -> GetCurrentAuthorizationInformation<'_>

Get information about the current OAuth authorization.

pub const fn current_user_application(&self) -> GetUserApplicationInfo<'_>

Get information about the current bot application.

pub const fn update_current_user(&self) -> UpdateCurrentUser<'_>

Update the current user.

All parameters are optional. If the username is changed, it may cause the discriminator to be randomized.

pub const fn update_current_user_voice_state( &self, guild_id: Id<GuildMarker> ) -> UpdateCurrentUserVoiceState<'_>

Update the current user’s voice state.

All parameters are optional.

Caveats

• channel_id must currently point to a stage channel.
• Current user must have already joined channel_id.

pub const fn current_user_connections(&self) -> GetCurrentUserConnections<'_>

Get the current user’s connections.

Requires the connections OAuth2 scope.

pub const fn current_user_guilds(&self) -> GetCurrentUserGuilds<'_>

Returns a list of guilds for the current user.

Examples

Get the first 25 guilds with an ID after 300 and before 400:

use twilight_model::id::Id;

let after = Id::new(300);
let before = Id::new(400);
let guilds = client
    .current_user_guilds()
    .after(after)
    .before(before)
    .limit(25)?
    .await?;

pub const fn emojis(&self, guild_id: Id<GuildMarker>) -> GetEmojis<'_>

Get the emojis for a guild, by the guild’s id.

Examples

Get the emojis for guild 100:

let guild_id = Id::new(100);

client.emojis(guild_id).await?;

pub const fn emoji( &self, guild_id: Id<GuildMarker>, emoji_id: Id<EmojiMarker> ) -> GetEmoji<'_>

Get an emoji for a guild by the the guild’s ID and emoji’s ID.

Examples

Get emoji 100 from guild 50:

let guild_id = Id::new(50);
let emoji_id = Id::new(100);

client.emoji(guild_id, emoji_id).await?;

pub const fn create_emoji<'a>( &'a self, guild_id: Id<GuildMarker>, name: &'a str, image: &'a str ) -> CreateEmoji<'a>

Create an emoji in a guild.

The emoji must be a Data URI, in the form of data:image/{type};base64,{data} where {type} is the image MIME type and {data} is the base64-encoded image. See Discord Docs/Image Data.

pub const fn delete_emoji( &self, guild_id: Id<GuildMarker>, emoji_id: Id<EmojiMarker> ) -> DeleteEmoji<'_>

Delete an emoji in a guild, by id.

pub const fn update_emoji( &self, guild_id: Id<GuildMarker>, emoji_id: Id<EmojiMarker> ) -> UpdateEmoji<'_>

Update an emoji in a guild, by id.

pub const fn gateway(&self) -> GetGateway<'_>

Get information about the gateway, optionally with additional information detailing the number of shards to use and sessions remaining.

Examples

Get the gateway connection URL without bot information:

let info = client.gateway().await?;

Get the gateway connection URL with additional shard and session information, which requires specifying a bot token:

let info = client.gateway().authed().await?.model().await?;

println!("URL: {}", info.url);
println!("Recommended shards to use: {}", info.shards);

pub const fn guild(&self, guild_id: Id<GuildMarker>) -> GetGuild<'_>

Get information about a guild.

pub fn create_guild( &self, name: String ) -> Result<CreateGuild<'_>, CreateGuildError>

Create a new request to create a guild.

The minimum length of the name is 2 UTF-16 characters and the maximum is 100 UTF-16 characters. This endpoint can only be used by bots in less than 10 guilds.

Errors

Returns a CreateGuildErrorType::NameInvalid error type if the name length is too short or too long.

pub const fn delete_guild(&self, guild_id: Id<GuildMarker>) -> DeleteGuild<'_>

Delete a guild permanently. The user must be the owner.

pub const fn update_guild(&self, guild_id: Id<GuildMarker>) -> UpdateGuild<'_>

Update a guild.

All endpoints are optional. See Discord Docs/Modify Guild.

pub const fn leave_guild(&self, guild_id: Id<GuildMarker>) -> LeaveGuild<'_>

Leave a guild by id.

pub const fn guild_channels( &self, guild_id: Id<GuildMarker> ) -> GetGuildChannels<'_>

Get the channels in a guild.

pub fn create_guild_channel<'a>( &'a self, guild_id: Id<GuildMarker>, name: &'a str ) -> Result<CreateGuildChannel<'a>, ChannelValidationError>

Create a new request to create a guild channel.

All fields are optional except for name. The minimum length of the name is 1 UTF-16 character and the maximum is 100 UTF-16 characters.

Errors

Returns an error of type NameInvalid when the length of the name is either fewer than 1 UTF-16 character or more than 100 UTF-16 characters.

Returns an error of type RateLimitPerUserInvalid when the seconds of the rate limit per user is more than 21600.

Returns an error of type TopicInvalid when the length of the topic is more than 1024 UTF-16 characters.

pub const fn update_guild_channel_positions<'a>( &'a self, guild_id: Id<GuildMarker>, channel_positions: &'a [Position] ) -> UpdateGuildChannelPositions<'a>

Modify the positions of the channels.

The minimum amount of channels to modify, is a swap between two channels.

This function accepts an Iterator of (Id<ChannelMarker>, u64). It also accepts an Iterator of Position, which has extra fields.

pub const fn guild_widget( &self, guild_id: Id<GuildMarker> ) -> GetGuildWidget<'_>

Get a guild’s widget.

See Discord Docs/Get Guild Widget.

pub const fn guild_widget_settings( &self, guild_id: Id<GuildMarker> ) -> GetGuildWidgetSettings<'_>

Get a guild’s widget settings.

See [Discord Docs/Get Guild Widget Settings].

pub const fn update_guild_widget_settings( &self, guild_id: Id<GuildMarker> ) -> UpdateGuildWidgetSettings<'_>

Modify a guild’s widget.

See Discord Docs/Modify Guild Widget.

pub const fn guild_integrations( &self, guild_id: Id<GuildMarker> ) -> GetGuildIntegrations<'_>

Get the guild’s integrations.

pub const fn delete_guild_integration( &self, guild_id: Id<GuildMarker>, integration_id: Id<IntegrationMarker> ) -> DeleteGuildIntegration<'_>

Delete an integration for a guild, by the integration’s id.

pub const fn guild_invites( &self, guild_id: Id<GuildMarker> ) -> GetGuildInvites<'_>

Get information about the invites of a guild.

Requires the MANAGE_GUILD permission.

pub const fn update_guild_mfa( &self, guild_id: Id<GuildMarker>, level: MfaLevel ) -> UpdateGuildMfa<'_>

Update a guild’s MFA level.

pub const fn guild_members( &self, guild_id: Id<GuildMarker> ) -> GetGuildMembers<'_>

Get the members of a guild, by id.

The upper limit to this request is 1000. If more than 1000 members are needed, the requests must be chained. Discord defaults the limit to 1.

Examples

Get the first 500 members of guild 100 after user ID 3000:

use twilight_model::id::Id;
let guild_id = Id::new(100);
let user_id = Id::new(3000);
let members = client
    .guild_members(guild_id)
    .after(user_id)
    .limit(500)?
    .await?;

Errors

Returns an error of type ValidationErrorType::GetGuildMembers if the limit is invalid.

pub const fn search_guild_members<'a>( &'a self, guild_id: Id<GuildMarker>, query: &'a str ) -> SearchGuildMembers<'a>

Search the members of a specific guild by a query.

The upper limit to this request is 1000. Discord defaults the limit to 1.

Examples

Get the first 10 members of guild 100 matching Wumpus:

use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new("my token".to_owned());

let guild_id = Id::new(100);
let members = client
    .search_guild_members(guild_id, "Wumpus")
    .limit(10)?
    .await?;

Errors

Returns an error of type ValidationErrorType::SearchGuildMembers if the limit is invalid.

pub const fn guild_member( &self, guild_id: Id<GuildMarker>, user_id: Id<UserMarker> ) -> GetMember<'_>

Get a member of a guild, by their id.

pub const fn add_guild_member<'a>( &'a self, guild_id: Id<GuildMarker>, user_id: Id<UserMarker>, access_token: &'a str ) -> AddGuildMember<'a>

Add a user to a guild.

An access token for the user with guilds.join scope is required. All other fields are optional. See Discord Docs/Add Guild Member.

Errors

Returns an error of type ValidationErrorType::Nickname if the nickname is too short or too long.

pub const fn remove_guild_member( &self, guild_id: Id<GuildMarker>, user_id: Id<UserMarker> ) -> RemoveMember<'_>

Kick a member from a guild.

pub const fn update_guild_member( &self, guild_id: Id<GuildMarker>, user_id: Id<UserMarker> ) -> UpdateGuildMember<'_>

Update a guild member.

All fields are optional. See Discord Docs/Modify Guild Member.

Examples

Update a member’s nickname to “pinky pie” and server mute them:

use std::env;
use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new(env::var("DISCORD_TOKEN")?);
let member = client
    .update_guild_member(Id::new(1), Id::new(2))
    .mute(true)
    .nick(Some("pinkie pie"))?
    .await?
    .model()
    .await?;

println!(
    "user {} now has the nickname '{:?}'",
    member.user.id, member.nick,
);

Errors

Returns an error of type ValidationErrorType::Nickname if the nickname length is too short or too long.

pub const fn update_current_member( &self, guild_id: Id<GuildMarker> ) -> UpdateCurrentMember<'_>

Update the user’s member in a guild.

pub const fn add_guild_member_role( &self, guild_id: Id<GuildMarker>, user_id: Id<UserMarker>, role_id: Id<RoleMarker> ) -> AddRoleToMember<'_>

Add a role to a member in a guild.

Examples

In guild 1, add role 2 to user 3, for the reason "test":

use twilight_model::id::Id;
let guild_id = Id::new(1);
let role_id = Id::new(2);
let user_id = Id::new(3);

client
    .add_guild_member_role(guild_id, user_id, role_id)
    .reason("test")?
    .await?;

pub const fn remove_guild_member_role( &self, guild_id: Id<GuildMarker>, user_id: Id<UserMarker>, role_id: Id<RoleMarker> ) -> RemoveRoleFromMember<'_>

Remove a role from a member in a guild, by id.

pub const fn guild_onboarding( &self, guild_id: Id<GuildMarker> ) -> GetGuildOnboarding<'_>

Retrieves the onboarding data for a guild.

pub const fn guild_preview( &self, guild_id: Id<GuildMarker> ) -> GetGuildPreview<'_>

For public guilds, get the guild preview.

This works even if the user is not in the guild.

pub const fn guild_prune_count( &self, guild_id: Id<GuildMarker> ) -> GetGuildPruneCount<'_>

Get the counts of guild members to be pruned.

pub const fn create_guild_prune( &self, guild_id: Id<GuildMarker> ) -> CreateGuildPrune<'_>

Begin a guild prune.

See Discord Docs/Begin Guild Prune.

pub const fn guild_vanity_url( &self, guild_id: Id<GuildMarker> ) -> GetGuildVanityUrl<'_>

Get a guild’s vanity url, if there is one.

pub const fn guild_voice_regions( &self, guild_id: Id<GuildMarker> ) -> GetGuildVoiceRegions<'_>

Get voice region data for the guild.

Can return VIP servers if the guild is VIP-enabled.

pub const fn guild_webhooks( &self, guild_id: Id<GuildMarker> ) -> GetGuildWebhooks<'_>

Get the webhooks of a guild.

pub const fn guild_welcome_screen( &self, guild_id: Id<GuildMarker> ) -> GetGuildWelcomeScreen<'_>

Get the guild’s welcome screen.

If the welcome screen is not enabled, this requires the MANAGE_GUILD permission.

pub const fn update_guild_welcome_screen( &self, guild_id: Id<GuildMarker> ) -> UpdateGuildWelcomeScreen<'_>

Update the guild’s welcome screen.

Requires the MANAGE_GUILD permission.

pub const fn invite<'a>(&'a self, code: &'a str) -> GetInvite<'a>

Get information about an invite by its code.

If with_counts is called, the returned invite will contain approximate member counts. If with_expiration is called, it will contain the expiration date.

Examples

let invite = client.invite("code").with_counts().await?;

pub const fn create_invite( &self, channel_id: Id<ChannelMarker> ) -> CreateInvite<'_>

Create an invite, with options.

Requires the CREATE_INVITE permission.

Examples

let channel_id = Id::new(123);
let invite = client.create_invite(channel_id).max_uses(3)?.await?;

pub const fn delete_invite<'a>(&'a self, code: &'a str) -> DeleteInvite<'a>

Delete an invite by its code.

Requires the MANAGE_CHANNELS permission on the channel this invite belongs to, or MANAGE_GUILD to remove any invite across the guild.

pub const fn message( &self, channel_id: Id<ChannelMarker>, message_id: Id<MessageMarker> ) -> GetMessage<'_>

Get a message by Id<ChannelMarker> and Id<MessageMarker>.

pub const fn create_message( &self, channel_id: Id<ChannelMarker> ) -> CreateMessage<'_>

Send a message to a channel.

The message must include at least one of attachments, components, content, embeds, or sticker_ids.

Example

use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new("my token".to_owned());

let channel_id = Id::new(123);
let message = client
    .create_message(channel_id)
    .content("Twilight is best pony")?
    .tts(true)
    .await?;

pub const fn delete_message( &self, channel_id: Id<ChannelMarker>, message_id: Id<MessageMarker> ) -> DeleteMessage<'_>

Delete a message by Id<ChannelMarker> and Id<MessageMarker>.

pub fn delete_messages<'a>( &'a self, channel_id: Id<ChannelMarker>, message_ids: &'a [Id<MessageMarker>] ) -> Result<DeleteMessages<'a>, ChannelValidationError>

Delete messages by Id<ChannelMarker> and Vec<Id<MessageMarker>>.

The vec count can be between 2 and 100. If the supplied Id<MessageMarker>s are invalid, they still count towards the lower and upper limits. This method will not delete messages older than two weeks. See Discord Docs/Bulk Delete Messages.

Errors

Returns an error of type ChannelValidationErrorType::BulkDeleteMessagesInvalid when the number of messages to delete in bulk is invalid.

pub const fn update_message( &self, channel_id: Id<ChannelMarker>, message_id: Id<MessageMarker> ) -> UpdateMessage<'_>

Update a message by Id<ChannelMarker> and Id<MessageMarker>.

You can pass None to any of the methods to remove the associated field. Pass None to content to remove the content. You must ensure that the message still contains at least one of attachments, components, content, embeds, or stickers.

Examples

Replace the content with "test update":

use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new("my token".to_owned());
client
    .update_message(Id::new(1), Id::new(2))
    .content(Some("test update"))?
    .await?;

Remove the message’s content:

client
    .update_message(Id::new(1), Id::new(2))
    .content(None)?
    .await?;

pub const fn crosspost_message( &self, channel_id: Id<ChannelMarker>, message_id: Id<MessageMarker> ) -> CrosspostMessage<'_>

Crosspost a message by Id<ChannelMarker> and Id<MessageMarker>.

pub const fn pins(&self, channel_id: Id<ChannelMarker>) -> GetPins<'_>

Get the pins of a channel.

pub const fn create_pin( &self, channel_id: Id<ChannelMarker>, message_id: Id<MessageMarker> ) -> CreatePin<'_>

Create a new pin in a channel, by ID.

pub const fn delete_pin( &self, channel_id: Id<ChannelMarker>, message_id: Id<MessageMarker> ) -> DeletePin<'_>

Delete a pin in a channel, by ID.

pub const fn reactions<'a>( &'a self, channel_id: Id<ChannelMarker>, message_id: Id<MessageMarker>, emoji: &'a RequestReactionType<'a> ) -> GetReactions<'a>

Get a list of users that reacted to a message with an emoji.

This endpoint is limited to 100 users maximum, so if a message has more than 100 reactions, requests must be chained until all reactions are retrieved.

pub const fn create_reaction<'a>( &'a self, channel_id: Id<ChannelMarker>, message_id: Id<MessageMarker>, emoji: &'a RequestReactionType<'a> ) -> CreateReaction<'a>

Create a reaction in a Id<ChannelMarker> on a Id<MessageMarker>.

The reaction must be a variant of RequestReactionType.

Examples

let channel_id = Id::new(123);
let message_id = Id::new(456);
let emoji = RequestReactionType::Unicode { name: "🌃" };

let reaction = client
    .create_reaction(channel_id, message_id, &emoji)
    .await?;

pub const fn delete_current_user_reaction<'a>( &'a self, channel_id: Id<ChannelMarker>, message_id: Id<MessageMarker>, emoji: &'a RequestReactionType<'a> ) -> DeleteReaction<'a>

Delete the current user’s (@me) reaction on a message.

pub const fn delete_reaction<'a>( &'a self, channel_id: Id<ChannelMarker>, message_id: Id<MessageMarker>, emoji: &'a RequestReactionType<'a>, user_id: Id<UserMarker> ) -> DeleteReaction<'a>

Delete a reaction by a user on a message.

pub const fn delete_all_reaction<'a>( &'a self, channel_id: Id<ChannelMarker>, message_id: Id<MessageMarker>, emoji: &'a RequestReactionType<'a> ) -> DeleteAllReaction<'a>

Remove all reactions on a message of an emoji.

pub const fn delete_all_reactions( &self, channel_id: Id<ChannelMarker>, message_id: Id<MessageMarker> ) -> DeleteAllReactions<'_>

Delete all reactions by all users on a message.

pub const fn create_typing_trigger( &self, channel_id: Id<ChannelMarker> ) -> CreateTypingTrigger<'_>

Fire a Typing Start event in the channel.

pub const fn create_private_channel( &self, recipient_id: Id<UserMarker> ) -> CreatePrivateChannel<'_>

Create a DM channel with a user.

pub const fn roles(&self, guild_id: Id<GuildMarker>) -> GetGuildRoles<'_>

Get the roles of a guild.

pub const fn create_role(&self, guild_id: Id<GuildMarker>) -> CreateRole<'_>

Create a role in a guild.

Examples

use twilight_model::id::Id;

let guild_id = Id::new(234);

client
    .create_role(guild_id)
    .color(0xd90083)
    .name("Bright Pink")
    .await?;

pub const fn delete_role( &self, guild_id: Id<GuildMarker>, role_id: Id<RoleMarker> ) -> DeleteRole<'_>

Delete a role in a guild, by id.

pub const fn update_role( &self, guild_id: Id<GuildMarker>, role_id: Id<RoleMarker> ) -> UpdateRole<'_>

Update a role by guild id and its id.

pub const fn update_role_positions<'a>( &'a self, guild_id: Id<GuildMarker>, roles: &'a [(Id<RoleMarker>, u64)] ) -> UpdateRolePositions<'a>

Modify the position of the roles.

The minimum amount of roles to modify, is a swap between two roles.

pub fn create_stage_instance<'a>( &'a self, channel_id: Id<ChannelMarker>, topic: &'a str ) -> Result<CreateStageInstance<'a>, ValidationError>

Create a new stage instance associated with a stage channel.

Requires the user to be a moderator of the stage channel.

Errors

Returns an error of type ValidationError::StageTopic when the topic is not between 1 and 120 characters in length.

pub const fn stage_instance( &self, channel_id: Id<ChannelMarker> ) -> GetStageInstance<'_>

Gets the stage instance associated with a stage channel, if it exists.

pub const fn update_stage_instance( &self, channel_id: Id<ChannelMarker> ) -> UpdateStageInstance<'_>

Update fields of an existing stage instance.

Requires the user to be a moderator of the stage channel.

pub const fn delete_stage_instance( &self, channel_id: Id<ChannelMarker> ) -> DeleteStageInstance<'_>

Delete the stage instance of a stage channel.

Requires the user to be a moderator of the stage channel.

pub fn create_guild_from_template<'a>( &'a self, template_code: &'a str, name: &'a str ) -> Result<CreateGuildFromTemplate<'a>, ValidationError>

Create a new guild based on a template.

This endpoint can only be used by bots in less than 10 guilds.

Errors

Returns an error of type ValidationErrorType::TemplateName if the name is invalid.

pub fn create_template<'a>( &'a self, guild_id: Id<GuildMarker>, name: &'a str ) -> Result<CreateTemplate<'a>, ValidationError>

Create a template from the current state of the guild.

Requires the MANAGE_GUILD permission. The name must be at least 1 and at most 100 characters in length.

Errors

Returns an error of type ValidationErrorType::TemplateName if the name is invalid.

pub const fn delete_template<'a>( &'a self, guild_id: Id<GuildMarker>, template_code: &'a str ) -> DeleteTemplate<'a>

Delete a template by ID and code.

pub const fn get_template<'a>( &'a self, template_code: &'a str ) -> GetTemplate<'a>

Get a template by its code.

pub const fn get_templates(&self, guild_id: Id<GuildMarker>) -> GetTemplates<'_>

Get a list of templates in a guild, by ID.

pub const fn sync_template<'a>( &'a self, guild_id: Id<GuildMarker>, template_code: &'a str ) -> SyncTemplate<'a>

Sync a template to the current state of the guild, by ID and code.

pub const fn update_template<'a>( &'a self, guild_id: Id<GuildMarker>, template_code: &'a str ) -> UpdateTemplate<'a>

Update the template’s metadata, by ID and code.

pub const fn active_threads( &self, guild_id: Id<GuildMarker> ) -> GetActiveThreads<'_>

Returns all active threads in the guild.

Includes public and private threads. Threads are ordered by their ID in descending order.

Examples

use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new("my token".to_owned());
let guild_id = Id::new(234);

let threads = client.active_threads(guild_id).await?.model().await?;

pub const fn add_thread_member( &self, channel_id: Id<ChannelMarker>, user_id: Id<UserMarker> ) -> AddThreadMember<'_>

Add another member to a thread.

Requires the ability to send messages in the thread, and that the thread is not archived.

pub const fn create_forum_thread<'a>( &'a self, channel_id: Id<ChannelMarker>, name: &'a str ) -> CreateForumThread<'_>

Start a thread in a forum channel.

pub fn create_thread<'a>( &'a self, channel_id: Id<ChannelMarker>, name: &'a str, kind: ChannelType ) -> Result<CreateThread<'_>, ChannelValidationError>

Start a thread that is not connected to a message.

Automatic archive durations are not locked behind the guild’s boost level.

To make a PrivateThread, the guild must also have the PRIVATE_THREADS feature.

Errors

Returns an error of type NameInvalid if the channel’s name’s length is incorrect.

Returns an error of type TypeInvalid if the channel is not a thread.

pub fn create_thread_from_message<'a>( &'a self, channel_id: Id<ChannelMarker>, message_id: Id<MessageMarker>, name: &'a str ) -> Result<CreateThreadFromMessage<'_>, ChannelValidationError>

Create a new thread from an existing message.

When called on a GuildText channel, this creates a PublicThread.

When called on a GuildAnnouncement channel, this creates a AnnouncementThread.

Automatic archive durations are not locked behind the guild’s boost level.

The thread’s ID will be the same as its parent message. This ensures only one thread can be created per message.

Errors

Returns an error of type NameInvalid if the channel’s name’s length is incorrect.

Returns an error of type TypeInvalid if the channel is not a thread.

pub const fn join_thread(&self, channel_id: Id<ChannelMarker>) -> JoinThread<'_>

Add the current user to a thread.

pub const fn joined_private_archived_threads( &self, channel_id: Id<ChannelMarker> ) -> GetJoinedPrivateArchivedThreads<'_>

Returns archived private threads in the channel that the current user has joined.

Threads are ordered by their ID in descending order.

pub const fn leave_thread( &self, channel_id: Id<ChannelMarker> ) -> LeaveThread<'_>

Remove the current user from a thread.

Requires that the thread is not archived.

pub const fn private_archived_threads( &self, channel_id: Id<ChannelMarker> ) -> GetPrivateArchivedThreads<'_>

Returns archived private threads in the channel.

Requires both READ_MESSAGE_HISTORY and MANAGE_THREADS.

pub const fn public_archived_threads( &self, channel_id: Id<ChannelMarker> ) -> GetPublicArchivedThreads<'_>

Returns archived public threads in the channel.

Requires the READ_MESSAGE_HISTORY permission.

Threads are ordered by archive_timestamp in descending order.

When called in a GuildText channel, returns PublicThreads.

When called in a GuildAnnouncement channel, returns AnnouncementThreads.

pub const fn remove_thread_member( &self, channel_id: Id<ChannelMarker>, user_id: Id<UserMarker> ) -> RemoveThreadMember<'_>

Remove another member from a thread.

Requires that the thread is not archived.

Requires the MANAGE_THREADS permission, unless both the thread is a PrivateThread, and the current user is the creator of the thread.

pub const fn thread_member( &self, channel_id: Id<ChannelMarker>, user_id: Id<UserMarker> ) -> GetThreadMember<'_>

Returns a ThreadMember in a thread.

pub const fn thread_members( &self, channel_id: Id<ChannelMarker> ) -> GetThreadMembers<'_>

Returns the ThreadMembers of the thread.

pub const fn update_thread( &self, channel_id: Id<ChannelMarker> ) -> UpdateThread<'_>

Update a thread.

All fields are optional. The minimum length of the name is 1 UTF-16 characters and the maximum is 100 UTF-16 characters.

pub const fn user(&self, user_id: Id<UserMarker>) -> GetUser<'_>

Get a user’s information by id.

pub const fn update_user_voice_state( &self, guild_id: Id<GuildMarker>, user_id: Id<UserMarker>, channel_id: Id<ChannelMarker> ) -> UpdateUserVoiceState<'_>

Update another user’s voice state.

Caveats

• channel_id must currently point to a stage channel.
• User must already have joined channel_id.

pub const fn voice_regions(&self) -> GetVoiceRegions<'_>

Get a list of voice regions that can be used when creating a guild.

pub const fn webhook(&self, id: Id<WebhookMarker>) -> GetWebhook<'_>

Get a webhook by ID.

pub fn create_webhook<'a>( &'a self, channel_id: Id<ChannelMarker>, name: &'a str ) -> Result<CreateWebhook<'a>, ValidationError>

Create a webhook in a channel.

Examples

let channel_id = Id::new(123);

let webhook = client.create_webhook(channel_id, "Twily Bot")?.await?;

Errors

Returns an error of type WebhookUsername if the webhook’s name is invalid.

pub const fn delete_webhook(&self, id: Id<WebhookMarker>) -> DeleteWebhook<'_>

Delete a webhook by its ID.

pub const fn update_webhook( &self, webhook_id: Id<WebhookMarker> ) -> UpdateWebhook<'_>

Update a webhook by ID.

pub const fn update_webhook_with_token<'a>( &'a self, webhook_id: Id<WebhookMarker>, token: &'a str ) -> UpdateWebhookWithToken<'a>

Update a webhook, with a token, by ID.

pub const fn execute_webhook<'a>( &'a self, webhook_id: Id<WebhookMarker>, token: &'a str ) -> ExecuteWebhook<'a>

Execute a webhook, sending a message to its channel.

The message must include at least one of attachments, components content, or embeds.

Examples

use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new("my token".to_owned());
let id = Id::new(432);

let webhook = client
    .execute_webhook(id, "webhook token")
    .content("Pinkie...")?
    .await?;

pub const fn webhook_message<'a>( &'a self, webhook_id: Id<WebhookMarker>, token: &'a str, message_id: Id<MessageMarker> ) -> GetWebhookMessage<'a>

Get a webhook message by webhook ID, token, and message ID.

pub const fn update_webhook_message<'a>( &'a self, webhook_id: Id<WebhookMarker>, token: &'a str, message_id: Id<MessageMarker> ) -> UpdateWebhookMessage<'a>

Update a message executed by a webhook.

You can pass None to any of the methods to remove the associated field. Pass None to content to remove the content. You must ensure that the message still contains at least one of attachments, components, content, or embeds.

Examples

use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new("token".to_owned());
client
    .update_webhook_message(Id::new(1), "token here", Id::new(2))
    .content(Some("new message content"))?
    .await?;

pub const fn delete_webhook_message<'a>( &'a self, webhook_id: Id<WebhookMarker>, token: &'a str, message_id: Id<MessageMarker> ) -> DeleteWebhookMessage<'a>

Delete a message executed by a webhook.

Examples

use twilight_model::id::Id;

client
    .delete_webhook_message(Id::new(1), "token here", Id::new(2))
    .await?;

pub const fn delete_guild_scheduled_event( &self, guild_id: Id<GuildMarker>, scheduled_event_id: Id<ScheduledEventMarker> ) -> DeleteGuildScheduledEvent<'_>

Delete a scheduled event in a guild.

Examples

let guild_id = Id::new(1);
let scheduled_event_id = Id::new(2);

client
    .delete_guild_scheduled_event(guild_id, scheduled_event_id)
    .await?;

pub const fn create_guild_scheduled_event( &self, guild_id: Id<GuildMarker>, privacy_level: PrivacyLevel ) -> CreateGuildScheduledEvent<'_>

Create a scheduled event in a guild.

Once a guild is selected, you must choose one of three event types to create. The request builders will ensure you provide the correct data to Discord. See Discord Docs/Create Guild Scheduled Event.

The name must be between 1 and 100 characters in length. For external events, the location must be between 1 and 100 characters in length.

Examples

Create an event in a stage instance:

use twilight_model::{guild::scheduled_event::PrivacyLevel, id::Id, util::Timestamp};
let guild_id = Id::new(1);
let channel_id = Id::new(2);
let garfield_start_time = Timestamp::parse("2022-01-01T14:00:00+00:00")?;

client
    .create_guild_scheduled_event(guild_id, PrivacyLevel::GuildOnly)
    .stage_instance(
        channel_id,
        "Garfield Appreciation Hour",
        &garfield_start_time,
    )?
    .description("Discuss: How important is Garfield to You?")?
    .await?;

Create an external event:

use twilight_model::{guild::scheduled_event::PrivacyLevel, id::Id, util::Timestamp};
let guild_id = Id::new(1);
let garfield_con_start_time = Timestamp::parse("2022-01-04T08:00:00+00:00")?;
let garfield_con_end_time = Timestamp::parse("2022-01-06T17:00:00+00:00")?;

client
    .create_guild_scheduled_event(guild_id, PrivacyLevel::GuildOnly)
    .external(
        "Garfield Con 2022",
        "Baltimore Convention Center",
        &garfield_con_start_time,
        &garfield_con_end_time,
    )?
    .description(
        "In a spiritual successor to BronyCon, Garfield fans from \
around the globe celebrate all things related to the loveable cat.",
    )?
    .await?;

pub const fn guild_scheduled_event( &self, guild_id: Id<GuildMarker>, scheduled_event_id: Id<ScheduledEventMarker> ) -> GetGuildScheduledEvent<'_>

Get a scheduled event in a guild.

pub const fn guild_scheduled_event_users( &self, guild_id: Id<GuildMarker>, scheduled_event_id: Id<ScheduledEventMarker> ) -> GetGuildScheduledEventUsers<'_>

Get a list of users subscribed to a scheduled event.

Users are returned in ascending order by user_id. before and after both take a user id. If both are specified, only before is respected. The default limit is 100. See Discord Docs/Get Guild Scheduled Event Users.

pub const fn guild_scheduled_events( &self, guild_id: Id<GuildMarker> ) -> GetGuildScheduledEvents<'_>

Get a list of scheduled events in a guild.

pub const fn update_guild_scheduled_event( &self, guild_id: Id<GuildMarker>, scheduled_event_id: Id<ScheduledEventMarker> ) -> UpdateGuildScheduledEvent<'_>

Update a scheduled event in a guild.

This endpoint supports changing the type of event. When changing the entity type to either EntityType::StageInstance or EntityType::Voice, an Id<ChannelMarker> must be provided if it does not already exist.

When changing the entity type to EntityType::External, the channel_id field is cleared and the channel_id method has no effect. Additionally, you must set a location with location.

pub const fn sticker(&self, sticker_id: Id<StickerMarker>) -> GetSticker<'_>

Returns a single sticker by its ID.

Examples

use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new("my token".to_owned());

let id = Id::new(123);
let sticker = client.sticker(id).await?.model().await?;

println!("{sticker:#?}");

pub const fn nitro_sticker_packs(&self) -> GetNitroStickerPacks<'_>

Returns a list of sticker packs available to Nitro subscribers.

Examples

use twilight_http::Client;

let client = Client::new("my token".to_owned());

let packs = client.nitro_sticker_packs().await?.model().await?;

println!("{}", packs.sticker_packs.len());

pub const fn guild_stickers( &self, guild_id: Id<GuildMarker> ) -> GetGuildStickers<'_>

Returns a list of stickers in a guild.

Examples

use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new("my token".to_owned());

let guild_id = Id::new(1);
let stickers = client.guild_stickers(guild_id).await?.models().await?;

println!("{}", stickers.len());

pub const fn guild_sticker( &self, guild_id: Id<GuildMarker>, sticker_id: Id<StickerMarker> ) -> GetGuildSticker<'_>

Returns a guild sticker by the guild’s ID and the sticker’s ID.

Examples

use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new("my token".to_owned());

let guild_id = Id::new(1);
let sticker_id = Id::new(2);
let sticker = client
    .guild_sticker(guild_id, sticker_id)
    .await?
    .model()
    .await?;

println!("{sticker:#?}");

pub fn create_guild_sticker<'a>( &'a self, guild_id: Id<GuildMarker>, name: &'a str, description: &'a str, tags: &'a str, file: &'a [u8] ) -> Result<CreateGuildSticker<'_>, StickerValidationError>

Creates a sticker in a guild, and returns the created sticker.

Examples

use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new("my token".to_owned());

let guild_id = Id::new(1);
let sticker = client
    .create_guild_sticker(
        guild_id,
        &"sticker name",
        &"sticker description",
        &"sticker,tags",
        &[23, 23, 23, 23],
    )?
    .await?
    .model()
    .await?;

println!("{sticker:#?}");

Errors

Returns an error of type DescriptionInvalid if the length is invalid.

Returns an error of type NameInvalid if the length is invalid.

Returns an error of type TagsInvalid if the length is invalid.

pub const fn update_guild_sticker( &self, guild_id: Id<GuildMarker>, sticker_id: Id<StickerMarker> ) -> UpdateGuildSticker<'_>

Updates a sticker in a guild, and returns the updated sticker.

Examples

use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new("my token".to_owned());

let guild_id = Id::new(1);
let sticker_id = Id::new(2);
let sticker = client
    .update_guild_sticker(guild_id, sticker_id)
    .description("new description")?
    .await?
    .model()
    .await?;

println!("{sticker:#?}");

pub const fn delete_guild_sticker( &self, guild_id: Id<GuildMarker>, sticker_id: Id<StickerMarker> ) -> DeleteGuildSticker<'_>

Deletes a guild sticker by the ID of the guild and its ID.

Examples

use twilight_http::Client;
use twilight_model::id::Id;

let client = Client::new("my token".to_owned());

let guild_id = Id::new(1);
let sticker_id = Id::new(2);

client.delete_guild_sticker(guild_id, sticker_id).await?;

pub fn request<T>(&self, request: Request) -> ResponseFuture<T>

Execute a request, returning a future resolving to a Response.

Errors

Returns an ErrorType::Unauthorized error type if the configured token has become invalid due to expiration, revocation, etc.

Trait Implementations

impl Debug for Client

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

Formats the value using the given formatter.