Struct twilight_http::client::Client[][src]

pub struct Client { /* fields omitted */ }
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.

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

Cloning

The client internally wraps its data within an Arc. This means that the client can be cloned and passed around tasks and threads cheaply.

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");

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")
    .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.

Retrieve the ApplicationId used by interaction methods.

Set a new ApplicationId after building the client.

Returns the previous ID, if there was one.

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::GuildId;

let guild_id = GuildId(101);
let audit_log = client
// not done
    .audit_log(guild_id)
    .await?;

Retrieve the bans for a guild.

Examples

Retrieve the bans for guild 1:

use twilight_model::id::GuildId;
let guild_id = GuildId(1);

let bans = client.bans(guild_id).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::{GuildId, UserId};
let guild_id = GuildId(100);
let user_id = UserId(200);
client.create_ban(guild_id, user_id)
    .delete_message_days(1)?
    .reason("memes")?
    .await?;

Remove a ban from a user in a guild.

Examples

Unban user 200 from guild 100:

use twilight_model::id::{GuildId, UserId};
let guild_id = GuildId(100);
let user_id = UserId(200);

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

Get a channel by its ID.

Examples

Get channel 100:

let channel_id = ChannelId(100);
let channel = client.channel(channel_id).await?;

Delete a channel by ID.

Update a channel.

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

Follows a news channel by ChannelId.

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

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::{ChannelId, MessageId};

let client = Client::new("my token");
let channel_id = ChannelId(123);
let message_id = MessageId(234);
let limit: u64 = 6;

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

Errors

Returns a GetChannelMessagesErrorType::LimitInvalid error type 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::{ChannelId, RoleId};

let channel_id = ChannelId(123);
let allow = Permissions::VIEW_CHANNEL;
let deny = Permissions::SEND_MESSAGES;
let role_id = RoleId(432);

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

Get all the webhooks of a channel.

Get information about the current user.

Get information about the current bot application.

Update the current user.

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

Update the current user’s voice state.

All paramaters 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::GuildId;

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

Changes the user’s nickname in a guild.

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

Examples

Get the emojis for guild 100:

let guild_id = GuildId(100);

client.emojis(guild_id).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 = GuildId(50);
let emoji_id = EmojiId(100);

client.emoji(guild_id, emoji_id).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().await?;

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

let info = client.gateway().authed().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 2 UTF-16 characters and the maximum is 100 UTF-16 characters.

Errors

Returns a CreateGuildChannelErrorType::NameInvalid error type when the length of the name is either fewer than 2 UTF-16 characters or more than 100 UTF-16 characters.

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

Returns a CreateGuildChannelErrorType::TopicInvalid error type 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 (ChannelId, 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::{GuildId, UserId};
let guild_id = GuildId(100);
let user_id = UserId(3000);
let members = client.guild_members(guild_id).after(user_id).await?;

Errors

Returns a GetGuildMembersErrorType::LimitInvalid error type 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::GuildId;

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

let guild_id = GuildId(100);
let members = client.search_guild_members(guild_id, String::from("Wumpus")).limit(10)?.await?;

Errors

Returns a SearchGuildMembersErrorType::LimitInvalid error type 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 AddGuildMemberErrorType::NicknameInvalid 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::{GuildId, UserId};

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

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

Errors

Returns UpdateGuildMemberErrorType::NicknameInvalid if the nickname length is too short or too long.

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::{GuildId, RoleId, UserId};
let guild_id = GuildId(1);
let role_id = RoleId(2);
let user_id = UserId(3);

client.add_guild_member_role(guild_id, user_id, role_id).reason("test")?.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()
    .await?;

Create an invite, with options.

Requires the CREATE_INVITE permission.

Examples

let channel_id = ChannelId(123);
let invite = client
    .create_invite(channel_id)
    .max_uses(3)?
    .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 ChannelId and MessageId.

Send a message to a channel.

Example

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

Errors

The method content returns CreateMessageErrorType::ContentInvalid if the content is over 2000 UTF-16 characters.

The method embed returns CreateMessageErrorType::EmbedTooLarge if the length of the embed is over 6000 characters.

Delete a message by ChannelId and MessageId.

Delete messages by ChannelId and Vec<MessageId>.

The vec count can be between 2 and 100. If the supplied MessageIds 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 ChannelId and MessageId.

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::{ChannelId, MessageId};

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

Remove the message’s content:

client.update_message(ChannelId(1), MessageId(2))
    .content(None)?
    .await?;

Crosspost a message by ChannelId and MessageId.

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

Create a reaction in a ChannelId on a MessageId.

The reaction must be a variant of RequestReactionType.

Examples

let channel_id = ChannelId(123);
let message_id = MessageId(456);
let emoji = RequestReactionType::Unicode { name: String::from("🌃") };

let reaction = client
    .create_reaction(channel_id, message_id, emoji)
    .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::GuildId;

let guild_id = GuildId(234);

client.create_role(guild_id)
    .color(0xd90083)
    .name("Bright Pink")
    .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 a CreateStageInstanceError of type InvalidTopic 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 a CreateGuildFromTemplateErrorType::NameInvalid error type 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 a CreateTemplateErrorType::NameInvalid error type 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.

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 = ChannelId(123);

let webhook = client
    .create_webhook(channel_id, "Twily Bot")
    .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 file.

Examples

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

Get a webhook message by WebhookId, token, and MessageId.

Update a message executed by a webhook.

Examples

use twilight_model::id::{MessageId, WebhookId};

client.update_webhook_message(WebhookId(1), "token here", MessageId(2))
    .content(Some("new message content".to_owned()))?
    .await?;

Delete a message executed by a webhook.

Examples

use twilight_model::id::{MessageId, WebhookId};

client
    .delete_webhook_message(WebhookId(1), "token here", MessageId(2))
    .await?;

Respond to an interaction, by ID and token.

Edit the original message, by its token.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Delete the original message, by its token.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Create a followup message, by an interaction token.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Edit a followup message, by an interaction token.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Delete a followup message by interaction token and the message’s ID.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Create a new command in a guild.

The name must be between 3 and 32 characters in length, and the description must be between 1 and 100 characters in length. Creating a guild command with the same name as an already-existing guild command in the same guild will overwrite the old command. See the discord docs for more information.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Returns an InteractionErrorType::CommandNameValidationFailed error type if the command name is not between 3 and 32 characters.

Returns an InteractionErrorType::CommandDescriptionValidationFailed error type if the command description is not between 1 and 100 characters.

Fetch all commands for a guild, by ID.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Edit a command in a guild, by ID.

You must specify a name and description. See the discord docs for more information.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Delete a command in a guild, by ID.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Set a guild’s commands.

This method is idempotent: it can be used on every start, without being ratelimited if there aren’t changes to the commands.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Create a new global command.

The name must be between 3 and 32 characters in length, and the description must be between 1 and 100 characters in length. Creating a command with the same name as an already-existing global command will overwrite the old command. See the discord docs for more information.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Returns an InteractionErrorType::CommandNameValidationFailed error type if the command name is not between 3 and 32 characters.

Returns an InteractionErrorType::CommandDescriptionValidationFailed error type if the command description is not between 1 and 100 characters.

Fetch all global commands for your application.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Edit a global command, by ID.

You must specify a name and description. See the discord docs for more information.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Delete a global command, by ID.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Set global commands.

This method is idempotent: it can be used on every start, without being ratelimited if there aren’t changes to the commands.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Fetch command permissions for a command from the current application in a guild.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Fetch command permissions for all commands from the current application in a guild.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Update command permissions for a single command in a guild.

This overwrites the command permissions so the full set of permissions have to be sent every time.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Update command permissions for all commands in a guild.

This overwrites the command permissions so the full set of permissions have to be sent every time.

Errors

Returns an InteractionErrorType::ApplicationIdNotPresent error type if an application ID has not been configured via Client::set_application_id.

Execute a request, returning the response.

Errors

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

Execute a request, chunking and deserializing the response.

Errors

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

Execute a request, checking only that the response was a success.

This will not chunk and deserialize the body of the response.

Errors

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

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

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 resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

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.