module Discord::REST

Direct including types

Defined in:

discordcr/mappings/enums.cr
discordcr/mappings/rest.cr
discordcr/rest.cr

Constant Summary

API_BASE = "https://discordapp.com/api/v6"
SSL_CONTEXT = OpenSSL::SSL::Context::Client.new
USER_AGENT = "DiscordBot (https://github.com/meew0/discordcr, #{Discord::VERSION})"

Instance Method Summary

Instance Method Detail

def accept_invite(code : String) #

Makes a user accept an invite. Will not work for bots. For example, this can be used with a Client instantiated with an OAuth2 Bearer token that has been granted the guilds.join scope.

client = Discord::Client.new token: "Bearer XYZ"
client.accept_invite("ABCdef")

API docs for this method


[View source]
def add_guild_member(guild_id : UInt64, user_id : UInt64, access_token : String, nick : String? = nil, roles : Array(UInt64)? = nil, mute : Bool? = nil, deaf : Bool? = nil) #

Adds a user to the guild, provided you have a valid OAuth2 access token for the user with the guilds.join scope.

NOTE The bot must be a member of the target guild, and have permissions to create instant invites.

API docs for this method


[View source]
def add_guild_member_role(guild_id : UInt64, user_id : UInt64, role_id : UInt64) #

Adds a role to a member. Requires the "Manage Roles" permission.

API docs for this method


[View source]
def add_pinned_channel_message(channel_id : UInt64 | Snowflake, message_id : UInt64 | Snowflake) #

Pins a new message to this channel. Requires the "Manage Messages" permission.

API docs for this method


[View source]
def begin_guild_prune(guild_id : UInt64 | Snowflake, days : UInt32) #

Prunes all members from this guild which haven't been seen for more than days days. Requires the "Kick Members" permission.

API docs for this method


[View source]
def bulk_delete_messages(channel_id : UInt64 | Snowflake, message_ids : Array(UInt64 | Snowflake)) #

Deletes multiple messages at once from the channel. The maximum amount is 100 messages, the minimum is 2. Requires the "Manage Messages" permission.

API docs for this method


[View source]
def create_channel_invite(channel_id : UInt64 | Snowflake, max_age : UInt32 = 0_u32, max_uses : UInt32 = 0_u32, temporary : Bool = false) #

Creates a new invite for the channel. Requires the "Create Instant Invite" permission.

API docs for this method


[View source]
def create_channel_webhook(channel_id : UInt64 | Snowflake, name : String, avatar : String) #

Create a channel webhook.

API docs for this method.


[View source]
def create_dm(recipient_id : UInt64 | Snowflake) #

Creates a new DM channel with a given recipient. If there was already one before, it will be reopened.

API docs for this method


[View source]
def create_guild_ban(guild_id : UInt64 | Snowflake, user_id : UInt64 | Snowflake, delete_message_days : Int32? = nil, reason : String? = nil) #

Bans a member from the guild. Requires the "Ban Members" permission.

API docs for this method


[View source]
def create_guild_channel(guild_id : UInt64 | Snowflake, name : String, type : ChannelType, bitrate : UInt32?, user_limit : UInt32?) #

Creates a new channel on this guild. Requires the "Manage Channels" permission.

API docs for this method


[View source]
def create_guild_emoji(guild_id : UInt64 | Snowflake, name : String, image : String) #

Creates a guild emoji. Requires the "Manage Emojis" permission.

API docs for this method


[View source]
def create_guild_integration(guild_id : UInt64 | Snowflake, type : String, id : UInt64 | Snowflake) #

Creates a new integration for this guild. Requires the "Manage Guild" permission.

API docs for this method


[View source]
def create_guild_role(guild_id : UInt64 | Snowflake, name : String? = nil, permissions : Permissions? = nil, colour : UInt32 = 0_u32, hoist : Bool = false, mentionable : Bool = false) #

Creates a new role on the guild. Requires the "Manage Roles" permission.

API docs for this method


[View source]
def create_message(channel_id : UInt64 | Snowflake, content : String, embed : Embed? = nil, tts : Bool = false) #

Sends a message to the channel. Requires the "Send Messages" permission.

API docs for this method

The embed parameter can be used to append a rich embed to the message which allows for displaying certain kinds of data in a more structured way. An example:

embed = Discord::Embed.new(
  title: "Title of Embed",
  description: "Description of embed. This can be a long text. Neque porro quisquam est, qui dolorem ipsum, quia dolor sit, amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt, ut labore et dolore magnam aliquam quaerat voluptatem.",
  timestamp: Time.now,
  url: "https://example.com",
  image: Discord::EmbedImage.new(
    url: "https://example.com/image.png",
  ),
  fields: [
    Discord::EmbedField.new(
      name: "Name of Field",
      value: "Value of Field",
    ),
  ],
)

client.create_message(channel_id, "The content of the message. This will display separately above the embed. This string can be empty.", embed)

For more details on the format of the embed object, look at the relevant documentation.


[View source]
def create_reaction(channel_id : UInt64 | Snowflake, message_id : UInt64 | Snowflake, emoji : String) #

Adds a reaction to a message. The emoji property must be in the format name:id for custom emoji. For unicode emoji it can simply be the UTF-8 encoded characters.

API docs for this method


[View source]
def delete_all_reactions(channel_id : UInt64 | Snowflake, message_id : UInt64 | Snowflake) #

Removes all reactions from a message. Requires the "Manage Messages" permission.

API docs for this method


[View source]
def delete_channel(channel_id : UInt64 | Snowflake) #

Deletes a channel by ID. Requires the "Manage Channel" permission.

API docs for this method


[View source]
def delete_channel_permission(channel_id : UInt64 | Snowflake, overwrite_id : UInt64 | Snowflake) #

Deletes a permission overwrite from a channel. Requires the "Manage Permissions" permission.

API docs for this method


[View source]
def delete_guild(guild_id : UInt64 | Snowflake) #

Deletes a guild. Requires the bot to be the server owner.

API docs for this method


[View source]
def delete_guild_integration(guild_id : UInt64 | Snowflake, integration_id : UInt64 | Snowflake) #

Deletes a guild integration. Requires the "Manage Guild" permission.

API docs for this method


[View source]
def delete_guild_role(guild_id : UInt64 | Snowflake, role_id : UInt64 | Snowflake) #

Deletes a role. Requires the "Manage Roles" permission as well as the role to be lower than the bot's highest role.

API docs for this method


[View source]
def delete_invite(code : String) #

Deletes (revokes) an invite. Requires the "Manage Channel" permission for the channel the invite is for, or the "Manage Server" permission for the server.

API docs for this method


[View source]
def delete_message(channel_id : UInt64 | Snowflake, message_id : UInt64 | Snowflake) #

Deletes a message from the channel. Requires the message to either have been sent by the bot itself or the bot to have the "Manage Messages" permission.

API docs for this method


[View source]
def delete_own_reaction(channel_id : UInt64 | Snowflake, message_id : UInt64 | Snowflake, emoji : String) #

Removes the bot's own reaction from a message. The emoji property must be in the format name:id for custom emoji. For unicode emoji it can simply be the UTF-8 encoded characters.

API docs for this method


[View source]
def delete_pinned_channel_message(channel_id : UInt64 | Snowflake, message_id : UInt64 | Snowflake) #

Unpins a message from this channel. Requires the "Manage Messages" permission.

API docs for this method


[View source]
def delete_user_reaction(channel_id : UInt64 | Snowflake, message_id : UInt64 | Snowflake, emoji : String, user_id : UInt64 | Snowflake) #

Removes another user's reaction from a message. The emoji property must be in the format name:id for custom emoji. For unicode emoji it can simply be the UTF-8 encoded characters. Requires the "Manage Messages" permission.

API docs for this method


[View source]
def delete_webhook(webhook_id : UInt64 | Snowflake, token : String) #

Deletes a webhook with a token. Does not require authentication.

API docs for this method


[View source]
def delete_webhook(webhook_id : UInt64 | Snowflake) #

Deletes a webhook. User must be owner.

API docs for this method


[View source]
def edit_channel_permissions(channel_id : UInt64 | Snowflake, overwrite_id : UInt64 | Snowflake, type : String, allow : Permissions, deny : Permissions) #

Edits an existing permission overwrite on a channel with new permissions, or creates a new one. The overwrite_id should be either a user or a role ID. Requires the "Manage Roles" permission.

API docs for this method


[View source]
def edit_message(channel_id : UInt64 | Snowflake, message_id : UInt64 | Snowflake, content : String, embed : Embed? = nil) #

Edits an existing message on the channel. This only works for messages sent by the bot itself - you can't edit others' messages.

API docs for this method


[View source]
def execute_webhook(webhook_id : UInt64 | Snowflake, token : String, content : String? = nil, file : String? = nil, embeds : Array(Embed)? = nil, tts : Bool? = nil, avatar_url : String? = nil, username : String? = nil, wait : Bool? = false) #

Executes a webhook, with a token.

API docs for this method


[View source]
def get_channel(channel_id : UInt64 | Snowflake) #

Gets a channel by ID.

API docs for this method


[View source]
def get_channel_invites(channel_id : UInt64 | Snowflake) #

Gets a list of invites for this channel. Requires the "Manage Channel" permission.

API docs for this method


[View source]
def get_channel_message(channel_id : UInt64 | Snowflake, message_id : UInt64 | Snowflake) #

Gets a single message from the channel's history. Requires the "Read Message History" permission.

API docs for this method


[View source]
def get_channel_messages(channel_id : UInt64 | Snowflake, limit : Int32 = 50, before : UInt64 | Snowflake | Nil = nil, after : UInt64 | Snowflake | Nil = nil, around : UInt64 | Snowflake | Nil = nil) #

Gets a list of messages from the channel's history. Requires the "Read Message History" permission.

API docs for this method


[View source]
def get_channel_webhooks(channel_id : UInt64 | Snowflake) #

Get an array of channel webhooks.

API docs for this method.


[View source]
def get_current_user #

Gets the current bot user.

API docs for this method


[View source]
def get_current_user_guilds(limit : Int32 = 100, before : UInt64 | Snowflake = 0_u64, after : UInt64 | Snowflake = 0_u64) #

Gets a list of user guilds the current user is on.

API docs for this method


[View source]
def get_gateway #

Gets the gateway URL to connect to.

API docs for this method


[View source]
def get_gateway_bot #

Gets the gateway Bot URL to connect to, and the recommended amount of shards to make.

API docs for this method


[View source]
def get_guild(guild_id : UInt64 | Snowflake) #

Gets a guild by ID.

API docs for this method


[View source]
def get_guild_ban(guild_id : UInt64 | Snowflake, user_id : UInt64 | Snowflake) #

Returns information about a banned user in a guild. Requires the "Ban Members" permission.

API docs for this method


[View source]
def get_guild_bans(guild_id : UInt64 | Snowflake) #

Gets a list of members banned from this server. Requires the "Ban Members" permission.

API docs for this method


[View source]
def get_guild_channels(guild_id : UInt64 | Snowflake) #

Gets a list of channels in a guild.

API docs for this method


[View source]
def get_guild_embed(guild_id : UInt64 | Snowflake) #

Gets embed data for a guild. Requires the "Manage Guild" permission.

API docs for this method


[View source]
def get_guild_emojis(guild_id : UInt64 | Snowflake) #

Gets a list of emoji on the guild.

API docs for this method


[View source]
def get_guild_integrations(guild_id : UInt64 | Snowflake) #

Gets a list of integrations (Twitch, YouTube, etc.) for this guild. Requires the "Manage Guild" permission.

API docs for this method


[View source]
def get_guild_member(guild_id : UInt64 | Snowflake, user_id : UInt64 | Snowflake) #

Gets a specific member by both IDs.

API docs for this method


[View source]
def get_guild_prune_count(guild_id : UInt64 | Snowflake, days : UInt32) #

Get a number of members that would be pruned with the given number of days. Requires the "Kick Members" permission.

API docs for this method


[View source]
def get_guild_roles(guild_id : UInt64 | Snowflake) #

Get a list of roles on the guild. Requires the "Manage Roles" permission.

API docs for this method


[View source]
def get_guild_vanity_url(guild_id : UInt64 | Snowflake) #

Gets the vanity URL of a guild. Requires the guild to be partnered.

There are no API docs for this method.


[View source]
def get_guild_voice_regions(guild_id : UInt64 | Snowflake) #

Gets a list of voice regions available for this guild. This may include VIP regions for VIP servers.

API docs for this method


[View source]
def get_guild_webhooks(guild_id : UInt64 | Snowflake) #

Get an array of guild webhooks.

API docs for this method.


[View source]
def get_invite(code : String) #

Gets a specific invite by its code.

API docs for this method


[View source]
def get_oauth2_application #

Gets the OAuth2 application tied to a client.

API docs for this method


[View source]
def get_pinned_messages(channel_id : UInt64 | Snowflake) #

Get a list of messages pinned to this channel.

API docs for this method


[View source]
def get_reactions(channel_id : UInt64 | Snowflake, message_id : UInt64 | Snowflake, emoji : String) #

Returns all users that have reacted with a specific emoji.

API docs for this method


[View source]
def get_user(user_id : UInt64 | Snowflake) #

Gets a specific user by ID.

API docs for this method


[View source]
def get_user_dms #

Gets a list of DM channels the bot has access to.

API docs for this method


[View source]
def get_users_connections #

Gets a list of connections the user has set up (Twitch, YouTube, etc.)

API docs for this method


[View source]
def get_webhook(webhook_id : UInt64 | Snowflake, token : String) #

Get a webhook, with a token.

API docs for this method.


[View source]
def get_webhook(webhook_id : UInt64 | Snowflake) #

Get a webhook.

API docs for this method.


[View source]
def leave_guild(guild_id : UInt64 | Snowflake) #

Makes the bot leave a guild.

API docs for this method


[View source]
def list_guild_members(guild_id : UInt64 | Snowflake, limit : Int32 = 1000, after : UInt64 | Snowflake = 0_u64) #

Gets multiple guild members at once. The limit can be at most 1000. The resulting list will be sorted by user IDs, use the after parameter to specify what ID to start at.

API docs for this method


[View source]
def list_voice_regions #

Gets a list of voice regions newly created servers have access to.

API docs for this method


[View source]
def modify_channel(channel_id : UInt64 | Snowflake, name : String? = nil, position : UInt32? = nil, topic : String? = nil, bitrate : UInt32? = nil, user_limit : UInt32? = nil, nsfw : Bool? = nil, rate_limit_per_user : Int32? = nil) #

Modifies a channel with new properties. Requires the "Manage Channel" permission.

API docs for this method


[View source]
def modify_current_user(username : String? = nil, avatar : String? = nil) #

Modifies the current bot user, changing the username and avatar.

NOTE To remove the current user's avatar, you can send an empty string for the avatar argument.

API docs for this method


[View source]
def modify_current_user_nick(guild_id : UInt64, nick : String) #

Modifies the nickname of the current user in a guild.

NOTE To remove a nickname, you can send an empty string for the nick argument.

API docs for this method


[View source]
def modify_guild(guild_id : UInt64 | Snowflake, name : String? = nil, region : String? = nil, verification_level : UInt8? = nil, afk_channel_id : UInt64 | Snowflake | Nil = nil, afk_timeout : Int32? = nil, icon : String? = nil, owner_id : UInt64 | Snowflake | Nil = nil, splash : String? = nil) #

Modifies an existing guild with new properties. Requires the "Manage Server" permission.

NOTE To remove a guild's icon, you can send an empty string for the icon argument.

API docs for this method


[View source]
def modify_guild_channel_positions(guild_id : UInt64 | Snowflake, positions : Array(ModifyChannelPositionPayload)) #

Modifies the position of channels within a guild. Requires the "Manage Channels" permission.

API docs for this method


[View source]
def modify_guild_embed(guild_id : UInt64 | Snowflake, enabled : Bool, channel_id : UInt64 | Snowflake) #

Modifies embed data for a guild. Requires the "Manage Guild" permission.

API docs for this method


[View source]
def modify_guild_emoji(guild_id : UInt64 | Snowflake, emoji_id : UInt64 | Snowflake, name : String) #

Modifies a guild emoji. Requires the "Manage Emojis" permission.

API docs for this method


[View source]
def modify_guild_integration(guild_id : UInt64 | Snowflake, integration_id : UInt64 | Snowflake, expire_behaviour : UInt8, expire_grace_period : Int32, enable_emoticons : Bool) #

Modifies an existing guild integration. Requires the "Manage Guild" permission.

API docs for this method


[View source]
def modify_guild_member(guild_id : UInt64 | Snowflake, user_id : UInt64 | Snowflake, nick : String? = nil, roles : Array(UInt64 | Snowflake)? = nil, mute : Bool? = nil, deaf : Bool? = nil, channel_id : UInt64 | Snowflake | Nil = nil) #

Changes a specific member's properties. Requires:

  • the "Manage Roles" permission and the role to change to be lower than the bot's highest role if changing the roles,
  • the "Manage Nicknames" permission when changing the nickname,
  • the "Mute Members" permission when changing mute status,
  • the "Deafen Members" permission when changing deaf status,
  • and the "Move Members" permission as well as the "Connect" permission to the new channel when changing voice channel ID.

NOTE To remove a member's nickname, you can send an empty string for the nick argument.

API docs for this method


[View source]
def modify_guild_role(guild_id : UInt64 | Snowflake, role_id : UInt64 | Snowflake, name : String? = nil, permissions : Permissions? = nil, colour : UInt32? = nil, position : Int32? = nil, hoist : Bool? = nil) #

Changes a role's properties. Requires the "Manage Roles" permission as well as the role to be lower than the bot's highest role.

API docs for this method


[View source]
def modify_guild_vanity_url(guild_id : UInt64 | Snowflake, code : String) #

Sets the vanity URL on this guild. Requires the guild to be partnered.

There are no API docs for this method.


[View source]
def modify_webhook(webhook_id : UInt64 | Snowflake, name : String? = nil, avatar : String? = nil, channel_id : UInt64 | Snowflake | Nil = nil) #

Modify a webhook. Accepts optional parameters name, avatar, and channel_id.

API docs for this method.


[View source]
def modify_webhook_with_token(webhook_id : UInt64 | Snowflake, token : String, name : String? = nil, avatar : String? = nil) #

Modify a webhook, with a token. Accepts optional parameters name, avatar, and channel_id.

API docs for this method.


[View source]
def page_channel_messages(channel_id : UInt64 | Snowflake, start_id : UInt64 | Snowflake = 0_u64, limit : Int32? = 100, direction : Paginator::Direction = Paginator::Direction::Down, page_size : Int32 = 100) #

Returns a Paginator over a channel's message history. Requires the "Read Message History" permission. See #get_channel_messages.

Will yield a channels message history in the given direction starting at start_id until limit number of messages are observed, or the channel has no further history. Setting limit to nil will have the paginator continue to make requests until all messages are fetched in the given direction.


[View source]
def page_current_user_guilds(start_id : UInt64 | Snowflake = 0_u64, limit : Int32? = 100, direction : Paginator::Direction = Paginator::Direction::Down, page_size : Int32 = 100) #

Returns a Paginator over the current users guilds.

Will yield guilds in the given direction starting at start_id until limit number of guilds are observed, or the user has no further guilds. Setting limit to nil will have the paginator continue to make requests until all guilds are fetched in the given direction.


[View source]
def page_guild_members(guild_id : UInt64 | Snowflake, start_id : UInt64 | Snowflake = 0_u64, limit : Int32? = 1000, page_size : Int32 = 1000) #

Returns a Paginator over the given guilds members.

Will yield members starting at start_id until limit number of members guilds are observed, or the user has no further guilds. Setting limit to nil will have the paginator continue to make requests until all members are fetched.


[View source]
def raw_request(route_key : Symbol, major_parameter : Snowflake | UInt64 | Nil, method : String, path : String, headers : HTTP::Headers, body : String?) #

Like #request, but does not do error checking beyond 429.


[View source]
def remove_guild_ban(guild_id : UInt64 | Snowflake, user_id : UInt64 | Snowflake) #

Unbans a member from the guild. Requires the "Ban Members" permission.

API docs for this method


[View source]
def remove_guild_member(guild_id : UInt64 | Snowflake, user_id : UInt64 | Snowflake) #

Kicks a member from the server. Requires the "Kick Members" permission.

API docs for this method


[View source]
def remove_guild_member_role(guild_id : UInt64, user_id : UInt64, role_id : UInt64) #

Removes a role from a member. Requires the "Manage Roles" permission.

API docs for this method


[View source]
def request(route_key : Symbol, major_parameter : Snowflake | UInt64 | Nil, method : String, path : String, headers : HTTP::Headers, body : String?) #

Makes a REST request to Discord, with the given method to the given path, with the given headers set and with the given body being sent. The route_key should uniquely identify the route used, for rate limiting purposes. The major_parameter should be set to the guild or channel ID, if either of those appears as the first parameter in the route.

This method also does rate limit handling, so if a rate limit is encountered, it may take longer than usual. (In case you're worried, this won't block events from being processed.) It also performs other kinds of error checking, so if a request fails (with a status code that is not 429) you will be notified of that.


[View source]
def sync_guild_integration(guild_id : UInt64 | Snowflake, integration_id : UInt64 | Snowflake) #

Syncs an integration. Requires the "Manage Guild" permission.

API docs for this method


[View source]
def trigger_typing_indicator(channel_id : UInt64 | Snowflake) #

Causes the bot to appear as typing on the channel. This generally lasts 10 seconds, but should be refreshed every five seconds. Requires the "Send Messages" permission.

API docs for this method


[View source]
def upload_file(channel_id : UInt64 | Snowflake, content : String?, file : IO, filename : String? = nil) #

Uploads a file to a channel. Requires the "Send Messages" and "Attach Files" permissions.

If the specified file is a File object and no filename is specified, the file's filename will be used instead. If it is an IO without filename information, Discord will generate a placeholder filename.

API docs for this method (same as #create_message -- this method implements form data bodies while #create_message implements JSON bodies)


[View source]