Struct discord::Discord

pub struct Discord { /* fields omitted */ }

Client for the Discord REST API.

Log in to the API with a user's email and password using new(). Call connect() to create a Connection on which to receive events. If desired, use logout() to invalidate the token when done. Other methods manipulate the Discord REST API.

Methods

impl Discord

fn new(email: &str, password: &str) -> Result<Discord>

Deprecated

: Login automation is not recommended. Use from_user_token instead.

Log in to the Discord Rest API and acquire a token.

fn new_cache<P: AsRef<Path>>(
    path: P,
    email: &str,
    password: Option<&str>
) -> Result<Discord>

Deprecated

: Login automation is not recommended. Use from_user_token instead.

Log in to the Discord Rest API, possibly using a cached login token.

Cached login tokens are keyed to the email address and will be read from and written to the specified path. If no cached token was found and no password was specified, an error is returned.

fn from_bot_token(token: &str) -> Result<Discord>

Log in as a bot account using the given authentication token.

The token will automatically be prefixed with "Bot ".

fn from_user_token(token: &str) -> Result<Discord>

Log in as a user account using the given authentication token.

fn logout(self) -> Result<()>

Deprecated

: Accomplishes nothing and may fail for no reason.

Log out from the Discord API, invalidating this clients's token.

fn create_channel(
    &self,
    server: ServerId,
    name: &str,
    kind: ChannelType
) -> Result<Channel>

Create a channel.

fn get_server_channels(&self, server: ServerId) -> Result<Vec<PublicChannel>>

Get the list of channels in a server.

fn get_channel(&self, channel: ChannelId) -> Result<Channel>

Get information about a channel.

fn edit_channel<F: FnOnce(EditChannel) -> EditChannel>(
    &self,
    channel: ChannelId,
    f: F
) -> Result<PublicChannel>

Edit a channel's details. See EditChannel for the editable fields.

// Edit a channel's name and topic
discord.edit_channel(channel_id, "general", |ch| ch
    .topic("Welcome to the general chat!")
);

fn delete_channel(&self, channel: ChannelId) -> Result<Channel>

Delete a channel.

fn broadcast_typing(&self, channel: ChannelId) -> Result<()>

Indicate typing on a channel for the next 5 seconds.

fn get_message(&self, channel: ChannelId, message: MessageId) -> Result<Message>

Get a single message by ID from a given channel.

fn get_messages(
    &self,
    channel: ChannelId,
    what: GetMessages,
    limit: Option<u64>
) -> Result<Vec<Message>>

Get messages in the backlog for a given channel.

The what argument should be one of the options in the GetMessages enum, and will determine which messages will be returned. A message limit can also be specified, and defaults to 50. More recent messages will appear first in the list.

fn get_pinned_messages(&self, channel: ChannelId) -> Result<Vec<Message>>

Gets the pinned messages for a given channel.

fn pin_message(&self, channel: ChannelId, message: MessageId) -> Result<()>

Pin the given message to the given channel.

Requires that the logged in account have the "MANAGE_MESSAGES" permission.

fn unpin_message(&self, channel: ChannelId, message: MessageId) -> Result<()>

Removes the given message from being pinned to the given channel.

Requires that the logged in account have the "MANAGE_MESSAGES" permission.

fn send_message(
    &self,
    channel: ChannelId,
    text: &str,
    nonce: &str,
    tts: bool
) -> Result<Message>

Send a message to a given channel.

The nonce will be returned in the result and also transmitted to other clients. The empty string is a good default if you don't care.

fn edit_message(
    &self,
    channel: ChannelId,
    message: MessageId,
    text: &str
) -> Result<Message>

Edit a previously posted message.

Requires that either the message was posted by this user, or this user has permission to manage other members' messages.

fn delete_message(&self, channel: ChannelId, message: MessageId) -> Result<()>

Delete a previously posted message.

Requires that either the message was posted by this user, or this user has permission to manage other members' messages.

fn delete_messages(
    &self,
    channel: ChannelId,
    messages: &[MessageId]
) -> Result<()>

Bulk deletes a list of MessageIds from a given channel.

A minimum of 2 unique messages and a maximum of 100 unique messages may be supplied, otherwise an Error::Other will be returned.

Each MessageId should be unique as duplicates will be removed from the array before being sent to the Discord API.

Only bots can use this endpoint. Regular user accounts can not use this endpoint under any circumstance.

Requires that either the message was posted by this user, or this user has permission to manage other members' messages.

fn send_embed<F: FnOnce(EmbedBuilder) -> EmbedBuilder>(
    &self,
    channel: ChannelId,
    text: &str,
    f: F
) -> Result<Message>

Send some embedded rich content attached to a message on a given channel.

See the EmbedBuilder struct for the editable fields. text may be empty.

fn edit_embed<F: FnOnce(EmbedBuilder) -> EmbedBuilder>(
    &self,
    channel: ChannelId,
    message: MessageId,
    f: F
) -> Result<Message>

Edit the embed portion of a previously posted message.

The text is unmodified, but the previous embed is entirely replaced.

fn send_file<R: Read>(
    &self,
    channel: ChannelId,
    text: &str,
    file: R,
    filename: &str
) -> Result<Message>

Send a file attached to a message on a given channel.

The text is allowed to be empty, but the filename must always be specified.

fn ack_message(&self, channel: ChannelId, message: MessageId) -> Result<()>

Acknowledge this message as "read" by this client.

fn create_permission(
    &self,
    channel: ChannelId,
    target: PermissionOverwrite
) -> Result<()>

Create permissions for a Channel for a Member or Role.

Examples

An example of creating channel role permissions for a Member:

use discord::model::{PermissionOverwriteType, permissions};

// Assuming that a `Discord` instance, member, and channel have already
// been defined previously.
let target = PermissionOverwrite {
    kind: PermissionOverwriteType::Member(member.user.id),
    allow: permissions::VOICE_CONNECT | permissions::VOICE_SPEAK,
    deny: permissions::VOICE_MUTE_MEMBERS | permissions::VOICE_MOVE_MEMBERS,
};
let result = discord.create_permission(channel.id, target);

The same can similarly be accomplished for a Role:

use discord::model::{PermissionOverwriteType, permissions};

// Assuming that a `Discord` instance, role, and channel have already
// been defined previously.
let target = PermissionOverwrite {
    kind: PermissionOverwriteType::Role(role.id),
    allow: permissions::VOICE_CONNECT | permissions::VOICE_SPEAK,
    deny: permissions::VOICE_MUTE_MEMBERS | permissions::VOICE_MOVE_MEMBERS,
};
let result = discord.create_permission(channel.id, target);

fn delete_permission(
    &self,
    channel: ChannelId,
    permission_type: PermissionOverwriteType
) -> Result<()>

Delete a Member or Role's permissions for a Channel.

Examples

Delete a Member's permissions for a Channel:

use discord::model::PermissionOverwriteType;

// Assuming that a `Discord` instance, channel, and member have already
// been previously defined.
let target = PermissionOverwriteType::Member(member.user.id);
let response = discord.delete_permission(channel.id, target);

The same can be accomplished for a Role similarly:

use discord::model::PermissionOverwriteType;

// Assuming that a `Discord` instance, channel, and role have already
// been previously defined.
let target = PermissionOverwriteType::Role(role.id);
let response = discord.delete_permission(channel.id, target);

fn add_reaction(
    &self,
    channel: ChannelId,
    message: MessageId,
    emoji: ReactionEmoji
) -> Result<()>

Add a Reaction to a Message.

Examples

Add an unicode emoji to a Message:

// Assuming that a `Discord` instance, channel, message have
// already been previously defined.
use discord::model::ReactionEmoji;

let _ = discord.add_reaction(&channel.id, message.id, ReactionEmoji::Unicode("👌".to_string));

Add a custom emoji to a Message:

// Assuming that a `Discord` instance, channel, message have
// already been previously defined.
use discord::model::{EmojiId, ReactionEmoji};

let _ = discord.add_reaction(&channel.id, message.id, ReactionEmoji::Custom {
    name: "ThisIsFine",
    id: EmojiId(1234)
});

Requires the ADD_REACTIONS permission.

fn delete_reaction(
    &self,
    channel: ChannelId,
    message: MessageId,
    user_id: Option<UserId>,
    emoji: ReactionEmoji
) -> Result<()>

Delete a Reaction from a Message.

Examples

Delete a Reaction from a Message (unicode emoji):

// Assuming that a `Discord` instance, channel, message, state have
// already been previously defined.
use discord::model::ReactionEmoji;

let _ = discord.delete_reaction(&channel.id, message.id, None, ReactionEmoji::Unicode("👌".to_string()));

Delete your Reaction from a Message (custom emoji):

// Assuming that a `Discord` instance, channel, message have
// already been previously defined.
use discord::model::ReactionEmoji;

let _ = discord.delete_reaction(&channel.id, message.id, None, ReactionEmoji::Custom {
    name: "ThisIsFine",
    id: EmojiId(1234)
});

Delete someone else's Reaction from a Message (custom emoji):

// Assuming that a `Discord` instance, channel, message have
// already been previously defined.
use discord::model::{EmojiId, ReactionEmoji};

let _ = discord.delete_reaction(&channel.id, message.id, Some(UserId(1234)), ReactionEmoji::Custom {
    name: "ThisIsFine",
    id: EmojiId(1234)
});

Requires MANAGE_MESSAGES if deleting someone else's Reaction.

fn get_reactions(
    &self,
    channel: ChannelId,
    message: MessageId,
    emoji: ReactionEmoji,
    limit: Option<i32>,
    after: Option<UserId>
) -> Result<Vec<User>>

Get reactors for the Emoji in a Message.

The default limit is 50. The optional value of after is the ID of the user to retrieve the next reactions after.

fn get_servers(&self) -> Result<Vec<ServerInfo>>

Get the list of servers this user knows about.

fn create_server(
    &self,
    name: &str,
    region: &str,
    icon: Option<&str>
) -> Result<Server>

Create a new server with the given name.

fn edit_server<F: FnOnce(EditServer) -> EditServer>(
    &self,
    server_id: ServerId,
    f: F
) -> Result<Server>

Edit a server's information. See EditServer for the editable fields.

// Rename a server
discord.edit_server(server_id, |server| server.name("My Cool Server"));
// Edit many properties at once
discord.edit_server(server_id, |server| server
    .name("My Cool Server")
    .icon(Some("data:image/jpg;base64,..."))
    .afk_timeout(300)
    .region("us-south")
);

fn leave_server(&self, server: ServerId) -> Result<Server>

Leave the given server.

fn delete_server(&self, server: ServerId) -> Result<Server>

Delete the given server. Only available to the server owner.

fn create_emoji(
    &self,
    server: ServerId,
    name: &str,
    image: &str
) -> Result<Emoji>

Creates an emoji in a server.

read_image may be used to build an image string. Requires that the logged in account be a user and have the ADMINISTRATOR or MANAGE_EMOJIS permission.

fn edit_emoji(
    &self,
    server: ServerId,
    emoji: EmojiId,
    name: &str
) -> Result<Emoji>

Edits a server's emoji.

Requires that the logged in account be a user and have the ADMINISTRATOR or MANAGE_EMOJIS permission.

fn delete_emoji(&self, server: ServerId, emoji: EmojiId) -> Result<()>

Delete an emoji in a server.

Requires that the logged in account be a user and have the ADMINISTRATOR or MANAGE_EMOJIS permission.

fn get_bans(&self, server: ServerId) -> Result<Vec<Ban>>

Get the ban list for the given server.

fn add_ban(
    &self,
    server: ServerId,
    user: UserId,
    delete_message_days: u32
) -> Result<()>

Ban a user from the server, optionally deleting their recent messages.

Zero may be passed for delete_message_days if no deletion is desired.

fn remove_ban(&self, server: ServerId, user: UserId) -> Result<()>

Unban a user from the server.

fn get_invite(&self, invite: &str) -> Result<Invite>

Extract information from an invite.

The invite should either be a URL of the form http://discord.gg/CODE, or a string containing just the CODE.

fn get_server_invites(&self, server: ServerId) -> Result<Vec<RichInvite>>

Get the active invites for a server.

fn get_channel_invites(&self, channel: ChannelId) -> Result<Vec<RichInvite>>

Get the active invites for a channel.

fn accept_invite(&self, invite: &str) -> Result<Invite>

Accept an invite. See get_invite for details.

fn create_invite(
    &self,
    channel: ChannelId,
    max_age: u64,
    max_uses: u64,
    temporary: bool
) -> Result<RichInvite>

Create an invite to a channel.

Passing 0 for max_age or max_uses means no limit. max_age should be specified in seconds.

fn delete_invite(&self, invite: &str) -> Result<Invite>

Delete an invite. See get_invite for details.

fn get_member(&self, server: ServerId, user: UserId) -> Result<Member>

Retrieve a member object for a server given the member's user id.

fn edit_member_roles(
    &self,
    server: ServerId,
    user: UserId,
    roles: &[RoleId]
) -> Result<()>

Edit the list of roles assigned to a member of a server.

fn edit_member<F: FnOnce(EditMember) -> EditMember>(
    &self,
    server: ServerId,
    user: UserId,
    f: F
) -> Result<()>

Edit member information, including roles, nickname, and voice state.

See the EditMember struct for the editable fields.

fn kick_member(&self, server: ServerId, user: UserId) -> Result<()>

Kick a member from a server.

fn create_private_channel(&self, recipient: UserId) -> Result<PrivateChannel>

Create a private channel with the given user, or return the existing one if it exists.

fn get_user_avatar_url(&self, user: UserId, avatar: &str) -> String

Get the URL at which a user's avatar is located.

fn get_user_avatar(&self, user: UserId, avatar: &str) -> Result<Vec<u8>>

Download a user's avatar.

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

Get the logged-in user's profile.

fn edit_profile<F: FnOnce(EditProfile) -> EditProfile>(
    &self,
    f: F
) -> Result<CurrentUser>

Edit the logged-in bot or user's profile. See EditProfile for editable fields.

Usable for bot and user accounts. Only allows updating the username and avatar.

fn edit_user_profile<F: FnOnce(EditUserProfile) -> EditUserProfile>(
    &mut self,
    f: F
) -> Result<CurrentUser>

Edit the logged-in non-bot user's profile. See EditUserProfile for editable fields.

Usable only for user (non-bot) accounts. Requires mutable access in order to keep the login token up to date in the event of a password change.

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

Get the list of available voice regions for a server.

fn move_member_voice(
    &self,
    server: ServerId,
    user: UserId,
    channel: ChannelId
) -> Result<()>

Move a server member to another voice channel.

fn begin_server_prune(&self, server: ServerId, days: u16) -> Result<ServerPrune>

Start a prune operation, kicking members who have been inactive for the specified number of days. Members with a role assigned will never be pruned.

fn get_server_prune_count(
    &self,
    server: ServerId,
    days: u16
) -> Result<ServerPrune>

Get the number of members who have been inactive for the specified number of days and would be pruned by a prune operation. Members with a role assigned will never be pruned.

fn edit_note(&self, user: UserId, note: &str) -> Result<()>

Sets a note for the user that is readable only to the currently logged in user.

This endpoint is only available for users, and so does not work for bots.

fn get_application_info(&self) -> Result<ApplicationInfo>

Retrieves information about the application and the owner.

fn suggested_shard_count(&self) -> Result<u64>

Retrieves the number of guild shards Discord suggests to use based on the number of guilds.

This endpoint is only available for bots.

fn connect(&self) -> Result<(Connection, ReadyEvent)>

Establish a websocket connection over which events can be received.

Also returns the ReadyEvent sent by Discord upon establishing the connection, which contains the initial state as seen by the client.

See connect_sharded if you want to use guild sharding.

fn connect_sharded(
    &self,
    shard_id: u8,
    total_shards: u8
) -> Result<(Connection, ReadyEvent)>

Establish a sharded websocket connection over which events can be received.

The shard_id is indexed at 0 while total_shards is indexed at 1.

Also returns the ReadyEvent sent by Discord upon establishing the connection, which contains the initial state as seen by the client.

See connect if you do not want to use guild sharding.