Struct twilight_http::client::Client

source · [−]
pub struct Client { /* private fields */ }
Expand description

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 twilight_http::Client;
use std::time::Duration;

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

Create a new hyper-rustls or hyper-tls backed client with a token.

Create a new builder to create a client.

Refer to its documentation for more information.

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.

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().exec().await?;

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

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

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

Get the default AllowedMentions for sent messages.

Get the Ratelimiter used by the client internally.

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

Get the audit log for a guild.

Examples
use twilight_model::id::Id;

let guild_id = Id::new(101);
let audit_log = client
// not done
    .audit_log(guild_id)
    .exec()
    .await?;

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).exec().await?;

Get information about a ban of a guild.

Includes the user banned and the reason.

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

Examples

Ban user 200 from guild 100, deleting 1 day’s 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_days(1)?
    .reason("memes")?
    .exec()
    .await?;

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).exec().await?;

Get a channel by its ID.

Examples

Get channel 100:

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

Delete a channel by ID.

Update a channel.

Follows a news channel by Id<ChannelMarker>.

The type returned is FollowedChannel.

Get the invites for a guild channel.

Requires the MANAGE_CHANNELS permission. This method only works if the channel is of type GuildChannel.

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: u64 = 6;

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

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

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;
use twilight_model::id::Id;

let channel_id = Id::new(123);
let allow = Permissions::VIEW_CHANNEL;
let deny = Permissions::SEND_MESSAGES;
let role_id = Id::new(432);

client.update_channel_permission(channel_id, allow, deny)
    .role(role_id)
    .exec()
    .await?;

Get all the webhooks of a channel.

Get information about the current user.

Get information about the current user in a guild.

Get information about the current bot application.

Update the current user.

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

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.

Get the current user’s connections.

Requires the connections OAuth2 scope.

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)?
    .exec()
    .await?;

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).exec().await?;

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).exec().await?;

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. Refer to the discord docs for more information about image data.

Delete an emoji in a guild, by id.

Update an emoji in a guild, by id.

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().exec().await?;

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

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

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

Get information about a guild.

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.

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

Update a guild.

All endpoints are optional. Refer to the discord docs for more information.

Leave a guild by id.

Get the channels in a guild.

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.

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.

Get the guild widget.

Refer to the discord docs for more information.

Modify the guild widget.

Get the guild’s integrations.

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

Get information about the invites of a guild.

Requires the MANAGE_GUILD permission.

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).exec().await?;
Errors

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

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)?
    .exec()
    .await?;
Errors

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

Get a member of a guild, by their id.

Add a user to a guild.

An access token for the user with guilds.join scope is required. All other fields are optional. Refer to the discord docs for more information.

Errors

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

Kick a member from a guild.

Update a guild member.

All fields are optional. Refer to the discord docs for more information.

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"))?
    .exec()
    .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.

Update the user’s member in a guild.

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")?
    .exec()
    .await?;

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

For public guilds, get the guild preview.

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

Get the counts of guild members to be pruned.

Begin a guild prune.

Refer to the discord docs for more information.

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

Get voice region data for the guild.

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

Get the webhooks of a guild.

Get the guild’s welcome screen.

Update the guild’s welcome screen.

Requires the MANAGE_GUILD permission.

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()
    .exec()
    .await?;

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)?
    .exec()
    .await?;

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.

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

Send a message to a channel.

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

The method content returns an error of type MessageValidationErrorType::ContentInvalid if the content is over 2000 UTF-16 characters.

The method embeds returns an error of type MessageValidationErrorType::EmbedInvalid if the embed is invalid.

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

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. Refer to the discord docs for more information.

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

You can pass None to any of the methods to remove the associated field. For example, if you have a message with an embed you want to remove, you can use .[embed](None) to remove the embed.

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"))?
    .exec()
    .await?;

Remove the message’s content:

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

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

Get the pins of a channel.

Create a new pin in a channel, by ID.

Delete a pin in a channel, by ID.

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.

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)
    .exec()
    .await?;

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

Delete a reaction by a user on a message.

Remove all reactions on a message of an emoji.

Delete all reactions by all users on a message.

Fire a Typing Start event in the channel.

Create a group DM.

This endpoint is limited to 10 active group DMs.

Get the roles of a guild.

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")
    .exec()
    .await?;

Delete a role in a guild, by id.

Update a role by guild id and its id.

Modify the position of the roles.

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

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.

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

Update fields of an existing stage instance.

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

Delete the stage instance of a stage channel.

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

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.

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.

Delete a template by ID and code.

Get a template by its code.

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

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

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

Returns all active threads in the channel.

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

Add another member to a thread.

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

Start a thread that is not connected to a message.

Values of ThreeDays and Week require the guild to be boosted. The guild’s features will indicate if a guild is able to use these settings.

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

Create a new thread from an existing message.

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

When called on a GuildNews channel, this creates a GuildNewsThread.

Values of ThreeDays and Week require the guild to be boosted. The guild’s features will indicate if a guild is able to use these settings.

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

Add the current user to a thread.

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

Threads are ordered by their ID in descending order.

Remove the current user from a thread.

Requires that the thread is not archived.

Returns archived private threads in the channel.

Requires both READ_MESSAGE_HISTORY and MANAGE_THREADS.

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 GuildPublicThreads.

When called in a GuildNews channel, returns GuildNewsThreads.

Remove another member from a thread.

Requires that the thread is not archived.

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

Returns a ThreadMember in a thread.

Returns the ThreadMembers of the thread.

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.

Get a user’s information by id.

Update another user’s voice state.

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

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

Get a webhook by ID.

Create a webhook in a channel.

Examples
let channel_id = Id::new(123);

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

Delete a webhook by its ID.

Update a webhook by ID.

Update a webhook, with a token, by ID.

Executes a webhook, sending a message to its channel.

You can only specify one of content, embeds, or files.

Examples
let id = Id::new(432);
let webhook = client
    .execute_webhook(id, "webhook token")
    .content("Pinkie...")?
    .exec()
    .await?;

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

Update a message executed by a webhook.

Examples
use twilight_model::id::Id;

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

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))
    .exec()
    .await?;

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)
    .exec()
    .await?;

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 the Discord docs for more information on which events require which fields.

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::{datetime::Timestamp, id::Id};
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)
    .stage_instance(
        channel_id,
        "Garfield Appreciation Hour",
        &garfield_start_time
    )?
    .description("Discuss: How important is Garfield to You?")?
    .exec()
    .await?;

Create an external event:

use twilight_model::{datetime::Timestamp, id::Id};
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)
    .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.")?
    .exec()
    .await?;

Get a scheduled event in a guild.

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 the Discord docs for more information.

Get a list of scheduled events in a guild.

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.

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).exec().await?.model().await?;

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

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().exec().await?.model().await?;

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

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)
    .exec()
    .await?
    .models()
    .await?;

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

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)
    .exec()
    .await?
    .model()
    .await?;

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

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]
    )?
    .exec()
    .await?
    .model()
    .await?;

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

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")?
    .exec()
    .await?
    .model()
    .await?;

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

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)
    .exec()
    .await?;

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

Formats the value using the given formatter. 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

Performs the conversion.

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