Comprehensive collection of Discord, OpenAI, Anthropic, Spotify, YouTube, Twitter, Slack, Imgur, DropBox, Box and various Google API endpoint handlers
Discord is the only completed set of handlers, the rest are still in early development
Choose one of the following options to authenticate:
Option 1: Using Environment Variablese
If you are using OnSocket, use this file to get the valid keys but add them to OnSocket's environment variables on the website itself.
Rename the provided .env.example
file at the root of your project to .env
and fill in any tokens/keys you wish to use.
Option 2: Using Initialization Function
const mapih = require ( 'mapih' ) ;
// Minimum requirement if using this method
mapih . initialize ( { discord : 'bot_token' } ) ;
// All possible properties
mapih . initialize ( {
discord : 'bot_token' ,
openai : 'sk-1p7NKtCpA0sG7XLdT3L7EqW9GFefX' ,
spotify : {
client_id : 'cc4287d9Cm4692a9f681d07d9boqji83' ,
client_secret : '898Nb8f7b09tMnb2lkj3c55443ddmn0ze' ,
redirect_uri : 'http:localhost:8001/spotify' ,
scope : 'user-read-email user-read-private'
} ,
google : {
api_key : 'AISlkuhyA4q4L9m0c3I09maoOYTN0wuyWdA' ,
client_id : '2164170085-9r94msc46elo.apps.googleusercontent.com' ,
client_secret : 'GOSLPM-sPn88Kn6GWk90Nh0uk_MNim7698By4' ,
redirect_uri : 'http://localhost:8001/youtube'
} ,
slack : {
user : '6942854604069-6272480346098-6284925009575-6901309' ,
bot : '6942854604069-6262140883098-Vt6RKehxmTj4Luvvy' ,
client_id : '6942854604069.624286609478' ,
client_secret : '4e4998dh94rl846bdsdfegfb0f12' ,
redirect_uri : 'http:localhost:8001/slack' ,
user_scope : 'admin users:read.email' ,
bot_scope : 'users:read.email channels:read'
} ,
dropbox : {
basic_token : 'N09asdfGlzZzB9P63465efasNWxAvfpk3dQ' ,
access_token : 'sl.BsobToktTBbsdf235aiihH7j60T_4T' ,
client_id : '7cxvzmptyug7ymc9' ,
client_secret : 'easdf8980k6csdf5y7u' ,
redirect_uri : 'http:localhost:8001/dropbox'
} ,
box : {
client_id : '3sdfgi8j90fpl8q25809sd0' ,
client_secret : 'Jsdf6BB4UErgS2chrg4365sdfBXS' ,
redirect_uri : 'http:localhost:8001/box'
} ,
} ) ;
( async ( ) => {
await mapih . discord . channels . messages . create ( {
channel_id : '774133713733812275' ,
content : 'hello'
} ) ;
} ) ( ) ;
• Applications
  ◦ getMe
  ◦ updateMe
  ◦ appRoleConnectionMeta
  ◦ updateAppRoleConnectionMeta
  ◦ commands
    ‣ retrieve
    ‣ getAll
    ‣ create
    ‣ update
    ‣ destroy
    ‣ bulkOverwrite
    ‣ retrievePermissions
    ‣ getAllPermissions
    ‣ updatePermissions
  ◦ entitlements
    ‣ getAll
    ‣ create
    ‣ destroy
  ◦ skus
    ‣ getAll
• Audit Log
  ◦ retrieve
• Auto Moderation
  ◦ retrieveRule
  ◦ getAllRules
  ◦ createRule
  ◦ updateRule
  ◦ destroyRule
• Channels
  ◦ retrieve
  ◦ update
  ◦ destroy
  ◦ updatePermissions
  ◦ deletePermissions
  ◦ getinvites
  ◦ inviteCreate
  ◦ typingCreate
  ◦ followAnnouncementChannel
  ◦ groupDMadd
  ◦ groupDMremove
  ◦ messages
    ‣ retrieve
    ‣ getAll
    ‣ create
    ‣ update
    ‣ destroy
    ‣ bulkDelete
    ‣ crosspost
    ‣ pin
    ‣ unpin
    ‣ getPinned
  ◦ threads
    ‣ forumThreadCreate
    ‣ createFromMessage
    ‣ createWithoutMessage
    ‣ join
    ‣ leave
    ‣ addMember
    ‣ removeMember
    ‣ retrieveMember
    ‣ getAllMembers
    ‣ getAllPublicArchived
    ‣ getAllPrivateArchived
    ‣ getAllJoinedPrivateArchived
  ◦ reactions
    ‣ create
    ‣ deleteOwn
    ‣ deleteUser
    ‣ deleteAll
    ‣ deleteAllEmoji
    ‣ getUsers
• Guilds
  ◦ create
  ◦ update
  ◦ destroy
  ◦ retrieve
  ◦ destroy
  ◦ getPreview
  ◦ retrieve
  ◦ getAll
  ◦ create
  ◦ destroy
  ◦ getInvites
  ◦ updateMFAlevel
  ◦ getPruneCount
  ◦ beginPrune
  ◦ getVoiceRegions
  ◦ getAllIntegrations
  ◦ destroyIntegration
  ◦ retrieveWidget
  ◦ retrieveWidgetImage
  ◦ retrieveWidgetSettings
  ◦ updateWidget
  ◦ retrieveVanityURL
  ◦ retrieveWelcomeScreen
  ◦ updateWelcomeScreen
  ◦ retrieveOnboarding
  ◦ updateOnboarding
  ◦ newMemberWelcome
  ◦ channels
    ‣ getAll
    ‣ create
    ‣ updatePositions
  ◦ members
    ‣ retrieve
    ‣ getAll
    ‣ search
    ‣ remove
    ‣ update
    ‣ updateCurrent
    ‣ addRole
    ‣ removeRole
    ‣ getPermissionNames
    ‣ timeout
  ◦ roles
    ‣ retrieve
    ‣ getAll
    ‣ create
    ‣ update
    ‣ destroy
    ‣ updatePositions
  ◦ emojis
    ‣ retrieve
    ‣ getAll
    ‣ create
    ‣ update
    ‣ destroy
  ◦ stickers
    ‣ retrieve
    ‣ nitroPacks
    ‣ getAll
    ‣ retrieveGuild
    ‣ create
    ‣ update
    ‣ destroy
  ◦ events
    ‣ retrieve
    ‣ getAll
    ‣ getUsers
    ‣ create
    ‣ update
    ‣ destroy
  ◦ templates
    ‣ retrieve
    ‣ getAll
    ‣ create
    ‣ createGuild
    ‣ sync
    ‣ update
    ‣ destroy
• Interactions
  ◦ callback
    ‣ reply
    ‣ defer
    ‣ get_original
    ‣ update_original
    ‣ delete_original
    ‣ component_defer
    ‣ component_update
    ‣ autocomplete_reply
    ‣ modal_reply
    ‣ upgrade
  ◦ followup
    ‣ retrieve
    ‣ create
    ‣ update
    ‣ destroy
• Invites
  ◦ retrieve
  ◦ revoke
• OAuth 2
• Stage Instances
  ◦ retrieve
  ◦ create
  ◦ update
  ◦ destroy
• Users
  ◦ retrieve
  ◦ currentUser
  ◦ myGuilds
  ◦ currentMember
  ◦ updateCurrent
  ◦ connections
  ◦ appRoleConnection
  ◦ updateAppRoleConnection
  ◦ createDM
  ◦ createGroupDM
  ◦ leaveGuild
• Webhooks
  ◦ retrieve
  ◦ retrieveWithToken
  ◦ retrieveChannel
  ◦ retrieveGuild
  ◦ retrieveMessage
  ◦ updateMessage
  ◦ destroyMessage
  ◦ create
  ◦ update
  ◦ updateWithToken
  ◦ destroy
  ◦ destroyWithToken
  ◦ execute
• Objects/Types
  ◦ Guilds
  ◦ Users
  ◦ Channels
  ◦ Interactions
  ◦ Roles
  ◦ Emojis/Stickers
  ◦ Message Components
  ◦ Webhooks
  ◦ Invites
  ◦ Application
  ◦ Audit Log
  ◦ Auto Moderation
• Chat
  ◦ create
• Images
  ◦ create
• Speech
  ◦ create
• Embeddings
  ◦ create
Docs coming soon
• Users
  ◦ me
  ◦ topItems
  ◦ getProfile
• Search
  ◦ advanced
  ◦ artists
  ◦ songs
  ◦ albums
• Songs
  ◦ retrieve
  ◦ retrieveMany
  ◦ recommendations
  ◦ save
  ◦ unsave
  ◦ saved
  ◦ isSaved
  ◦ analyze
  ◦ audioFeatures
  ◦ audioFeaturesMany
• Artists
  ◦ retrieve
  ◦ retrieveMany
  ◦ recommendations
  ◦ albums
  ◦ related
  ◦ follow
  ◦ unfollow
  ◦ following
  ◦ isFollowing
• Albums
  ◦ retrieve
  ◦ retrieveMany
  ◦ songs
  ◦ new
  ◦ save
  ◦ unsave
  ◦ saved
  ◦ isSaved
• Playlists
  ◦ featured
  ◦ category
  ◦ create
  ◦ addSongs
  ◦ update
  ◦ updateSongs
  ◦ removeSongs
  ◦ retrieveSongs
  ◦ created
  ◦ following
  ◦ isFollowing
  ◦ follow
  ◦ unfollow
  ◦ user
  ◦ cover
  ◦ updateCover
• Playback
  ◦ state
  ◦ currentSong
  ◦ devices
  ◦ togglePlayback
  ◦ pause
  ◦ skip
  ◦ previous
  ◦ seek
  ◦ setVolume
  ◦ toggleShuffle
  ◦ toggleRepeat
  ◦ queue
  ◦ recent
  ◦ addToQueue
  ◦ transfer
• Storage
  ◦ get
  ◦ getMany
  ◦ set
  ◦ setMany
  ◦ delete
  ◦ deleteMany
  ◦ merge
  ◦ push
  ◦ export
  ◦ filter
  ◦ all
  ◦ has
  ◦ entries
  ◦ keys
  ◦ values
  ◦ size
  ◦ bytes
  ◦ toJson
  ◦ clear
  ◦ equals
  ◦ history
  ◦ clearHistory
All functions relating to Discord Guilds (servers)
Field
Type
Description
guild_id
snowflake
the id of the guild
with_counts?
boolean
Approcimate member and presence counts
await mapih . discord . guilds . retrieve ( {
guild_id : '0000000000'
} ) ;
This endpoint can be used only by bots in less than 10 servers.
Field
Type
Description
name
string
Name of the guild (2-100 characters)
icon?
string/buffer
Guild icon (url to image or image buffer)
roles?
array of Role objects
Roles to add to the guild
channels?
array of PartialChannel objects
Channels to add to the guild
verification_level?
number
The guild's verification level
default_message_notifications?
number
Default message notification level
explicit_content_filter?
number
Explicit content filter level
afk_channel_id?
snowflake
ID for afk channel
afk_timeout?
number
afk timeout in seconds, can be set to: 60, 300, 900, 1800, 3600
system_channel_id?
snowflake
The id of the channel where guild notices such as welcome messages and boost events are posted
system_channel_flags?
number
System channel flags
await mapih . discord . guilds . create ( {
name : "Eric's Server" ,
icon : 'https://imgurl.png' , // or buffer
default_message_notifications : 1 , // ONLY_MENTIONS
verification_level : 0 , // NONE
explicit_content_filter : 0 , // DISABLED
roles : [ {
name : 'Administrator' ,
permissions : 1 << 3 ,
hoist : 'true' ,
mentionable : 'false'
} ] ,
channels : [
{
name : 'my-category' ,
type : 4 , // GUILD_CATEGORY
id : 1
} ,
{
name : 'bot-testing' ,
type : 0 , // GUILD_TEXT
id : 2 ,
parent_id : 1 // 'my-category'
}
]
} ) ;
Field
Type
Description
name
string
Name of the guild (2-100 characters)
description
string
owner_id
snowflake
User id to transfer server ownership to
icon
url/buffer
splash
url/buffer
discovery_splash
url/buffer
banner
url/buffer
verification_level
number
The guild's verification level
default_message_notifications
number
Default message notification level
explicit_content_filter
number
Explicit content filter level
afk_channel_id
snowflake
id for afk channel
afk_timeout
number
afk timeout in seconds, can be set to: 60, 300, 900, 1800, 3600
system_channel_id
snowflake
The id of the channel where guild notices such as welcome messages and boost events are posted
system_channel_flags
number
System channel flags
rules_channel_id
snowflake
system_updates_channel_id
snowflake
premium_progress_bar_enabled
number
await mapih . discord . guilds . update ( {
name : "Eric's New Server" ,
// ...
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . destroy ( {
guild_id : '0000000000'
} ) ;
• If the user is not in the guild, then the guild must be lurkable.
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . getPreview ( {
guild_id : '0000000000'
} ) ;
• Returns a ban object for the given user or a 404 not found if the ban cannot be found.
• Requires the BAN_MEMBERS
permission.
Field
Type
Description
guild_id
snowflake
the id of the guild
user_id
snowflake
The ID of the user the ban was created for
await mapih . discord . guilds . retrieve ( {
guild_id : '0000000000' ,
user_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
limit?
number
Number of users to return (up to maximum 1000) (default 1000)
before?
snowflake
Consider only users before given user ID
after?
snowflake
Consider only users after given user ID
await mapih . discord . guilds . getAll ( {
guild_id : '0000000000' ,
limit : 50 ,
after : '0000000000'
} ) ;
• Requires the BAN_MEMBERS
permission.
Field
Type
Description
guild_id
snowflake
the id of the guild
user_id
snowflake
User ID of the user to ban
delete_message_seconds?
snowflake
Number of seconds to delete the banned user's messages for, between 0 and 604800 (7 days).
reason?
string
Reason for the ban
await mapih . discord . guilds . create ( {
guild_id : '0000000000' ,
user_id : '0000000000' ,
delete_message_seconds : 604800 ,
reason : 'not cool enough'
} ) ;
• Requires the BAN_MEMBERS
permission.
Field
Type
Description
guild_id
snowflake
the id of the guild
user_id
snowflake
User ID of the user to unban
reason?
string
Reason
await mapih . discord . guilds . destroy ( {
guild_id : '0000000000' ,
user_id : '0000000000' ,
reason : 'ok I guess you\'re alright'
} ) ;
• Requires guild ownership.
Field
Type
Description
guild_id
snowflake
the id of the guild
level
number
MFA level
await mapih . discord . guilds . updateMFAlevel ( {
guild_id : '0000000000' ,
level : 0
} ) ;
• By default, prune will not remove users with roles.
• You can optionally include specific roles in your prune by providing the include_roles
parameter.
• Any inactive user that has a subset of the provided role(s) will be counted in the prune and users with additional roles will not.
Field
Type
Description
guild_id
snowflake
the id of the guild
days
number
Number of days to count prune for (1-30) (Default 7)
include_roles?
string[]
An array of role IDs to include
await mapih . discord . guilds . getPruneCount ( {
guild_id : '0000000000' ,
days : 3 ,
include_roles : [
'0000000000'
]
} ) ;
• For large guilds it's recommended to set the compute_prune_count
option to false
, forcing pruned
to null
.
• By default, prune will not remove users with roles.
• You can optionally include specific roles in your prune by providing the include_roles
parameter.
• Any inactive user that has a subset of the provided role(s) will be counted in the prune and users with additional roles will not.
Field
Type
Description
guild_id
snowflake
the id of the guild
days
number
Number of days to count prune for (1-30) (default 7)
compute_prune_count
boolean
Whether pruned
is returned, discouraged for large guilds (default true)
include_roles?
snowflake[]
An array of role IDs to include
reason?
string
Reason
await mapih . discord . guilds . beginPrune ( {
guild_id : '0000000000' ,
days : 3 ,
compute_prune_count : true ,
include_roles : [
'0000000000'
]
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . getVoiceRegions ( {
guild_id : '0000000000'
} ) ;
This endpoint returns a maximum of 50 integrations.
If a guild has more integrations, they cannot be accessed.
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . getAllIntegrations ( {
guild_id : '0000000000'
} ) ;
• Deletes any associated webhooks and kicks the associated bot if there is one.
Field
Type
Description
guild_id
snowflake
the id of the guild
integration_id
snowflake
The ID of the integration to delete
await mapih . discord . guilds . destroyIntegration ( {
guild_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . retrieveWidget ( {
guild_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . retrieveWidgetSettings ( {
guild_id : '0000000000'
} ) ;
Value
Description
Example
shield
shield style widget with Discord icon and guild members online count
Example
banner1
large image with guild icon, name and online count. "POWERED BY DISCORD" as the footer of the widget
Example
banner2
smaller widget style with guild icon, name and online count. Split on the right with Discord logo
Example
banner3
large image with guild icon, name and online count. In the footer, Discord logo on the left and "Chat Now" on the right
Example
banner4
large Discord logo at the top of the widget. Guild icon, name and online count in the middle portion of the widget and a "JOIN MY SERVER" button at the bottom
Example
Field
Type
Description
guild_id
snowflake
the id of the guild
style
string
Widget style (see above)
await mapih . discord . guilds . retrieveWidgetImage ( {
guild_id : '0000000000' ,
style : 'banner3'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
channel_id?
snowflake
temp
enabled?
boolean
Whether the widget is enabled
await mapih . discord . guilds . updateWidget ( {
guild_id : '0000000000' ,
enabled : true
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . retrieveVanityURL ( {
guild_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . retrieveWelcomeScreen ( {
guild_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
description?
string
The server description to show in the welcome screen
enabled?
boolean
Whether the welcome screen is enabled.
welcome_channels?
array of welcome screen channel objects
Channels shown in the welcome screen, up to 5
await mapih . discord . guilds . updateWelcomeScreen ( {
guild_id : '0000000000' ,
enabled : true
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . retrieveOnboarding ( {
guild_id : '0000000000' ,
enabled : true
} ) ;
• Requires the MANAGE_GUILD
and MANAGE_ROLES
permissions.
• Onboarding enforces constraints when enabled. These constraints are that there must be at least 7 Default Channels and at least 5 of them must allow sending messages to the @everyone role. The mode field modifies what is considered when enforcing these constraints.**
Field
Type
Description
guild_id
snowflake
the id of the guild
prompts
array of onboarding prompt objects
Prompts shown during onboarding and in customize commutity
default_channel_ids
array of snowflakes
Channel IDs that members get opted into automatically
enabled
boolean
Whether onboarding is enabled in the guild
mode
onboarding mode
Current mode of onboarding
await mapih . discord . guilds . updateOnboarding ( {
guild_id : '0000000000' ,
prompts : [ {
id : '0000000000' ,
type : 0 ,
title : 'Prompt Title' ,
single_select : true ,
required : true ,
in_onboarding : true ,
options : [ {
title : 'Option Title' ,
description : 'Option description' ,
id : '0000000000' ,
channel_ids : [
'0000000000'
] ,
role_ids : [
'0000000000'
] ,
emoji : {
id : '0000000000' ,
name : 'emoji_name' ,
animated : false
}
} ]
} ]
} ) ;
Method
Description
getAll
Retrieve all channels in a guild.
create
Create a new guild channel.
updatePositions
Modify the positions of channels.
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . channels . getAll ( {
guild_id : '0000000000'
} ) ;
All parameters to this endpoint are optional and nullable excluding name
Field
Type
Description
Channel Type
name
string
channel name (1-100 characters)
All
type
number
the type of channel
All
topic
string
channel topic (0-1024 characters)
Text, Announcement, Forum, Media
bitrate
number
the bitrate (in bits) of the voice or stage channel; min 8000
Voice, Stage
user_limit
number
the user limit of the voice channel
Voice, Stage
rate_limit_per_user
number
amount of seconds a user has to wait before sending another message (0-21600); bots, as well as users with the permission manage_messages
or manage_channel
, are unaffected
Text, Voice, Stage, Forum, Media
position
number
sorting position of the channel
All
permission_overwrites
array of partial overwrite objects
the channel's permission overwrites
All
parent_id
snowflake
id of the parent category for a channel
Text, Voice, Announcement, Stage, Forum, Media
nsfw
boolean
whether the channel is nsfw
Text, Voice, Announcement, Stage, Forum
rtc_region
string
channel voice region id of the voice or stage channel, automatic when set to null
Voice, Stage
video_quality_mode
number
the camera video quality mode of the voice channel
Voice, Stage
default_auto_archive_duration
number
the default duration that the clients use (not the API) for newly created threads in the channel, in minutes, to automatically archive the thread after recent activity
Text, Announcement, Forum, Media
default_reaction_emoji
default reaction object
emoji to show in the add reaction button on a thread in a GUILD_FORUM
or a GUILD_MEDIA
channel
Forum, Media
available_tags
array of tag objects
set of tags that can be used in a GUILD_FORUM
or a GUILD_MEDIA
channel
Forum, Media
default_sort_order
number
the default sort order type used to order posts in GUILD_FORUM
and GUILD_MEDIA
channels
Forum, Media
default_forum_layout
number
the default forum layout view used to display posts in GUILD_FORUM
channels
Forum
default_thread_rate_limit_per_user
number
the initial rate_limit_per_user
to set on newly created threads in a channel. this field is copied to the thread at creation time and does not live update.
Text, Announcement, Forum, Media
await mapih . discord . guilds . channels . create ( {
guild_id : '0000000000' ,
name : 'my-new-channel' ,
type : 0 ,
topic : 'Cool people only' ,
position : 19
} ) ;
Only channels to be modified are required
Field
Type
Description
id
snowflake
channel id
position?
?number
sorting position of the channel
lock_permissions?
?boolean
syncs the permission overwrites with the new parent, if moving to a new category
parent_id?
?snowflake
the new parent ID for the channel that is moved
await mapih . discord . guilds . channels . updatePositions ( {
guild_id : '0000000000' ,
channels : [ {
id : '0000000000' ,
position : 3 ,
lock_permissions : true ,
parent_id : '0000000000'
} ]
} ) ;
Method
Description
retrieve
Returns information about a user
getAll
List all members of a guild
search
Search for guild members by name or nickname
remove
Remove a member from a guild
update
Modify attributes of a guild member
updateCurrent
Modify the current bot's nickname in the guild
addRole
Add a role to a guild member
removeRole
Remove a role from a guild member
getPermissionNames
Get a user's permission's names
timeout
Update a member's communication timeout
Field
Type
Description
guild_id
snowflake
the id of the guild
user_id
snowflake
The ID of the user
await mapih . discord . guilds . members . retrieve ( {
guild_id : '0000000000' ,
user_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
limit
number
Max number of members to return (1-1000) (default 1)
after
snowflake
The highest user id in the previous page (default 0)
await mapih . discord . guilds . members . getAll ( {
guild_id : '0000000000' ,
limit : 1000
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
query
string
Query string to match username(s) and nickname(s) against
limit
number
Max number of members to return (1-1000) (default 1)
await mapih . discord . guilds . members . search ( {
guild_id : '0000000000' ,
query : 'lostmyinfo' ,
limit : 1
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
user_id
snowflake
The ID of the user to remove
reason?
string
Reason for kick
await mapih . discord . guilds . members . remove ( {
guild_id : '0000000000' ,
user_id : '0000000000' ,
reason : 'not cool enough'
} ) ;
• If the channel_id is set to null, this will force the target user to be disconnected from voice.
All parameters to this endpoint are optional and nullable.
Field
Type
Description
Permission
guild_id
snowflake
the id of the guild
role_id
snowflake
the id of the role
nick
string
value to set user's nickname to
MANAGE_NICKNAMES
roles
array of snowflakes
array of role ids the member is assigned
MANAGE_ROLES
mute
boolean
whether the user is muted in voice channels
MUTE_MEMBERS
deaf
boolean
whether the user is deafened in voice channels
DEAFEN_MEMBERS
channel_id
snowflake
id of channel to move user to (if they are connected to voice)
MOVE_MEMBERS
communication_disabled_until
ISO8601 timestamp
when the user's timeout will expire (up to 28 days in the future)
MODERATE_MEMBERS
flags
number
guild member flags
MODERATE_MEMBERS
await mapih . discord . guilds . members . update ( {
guild_id : '0000000000' ,
nick : 'cool new nick'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
nick?
string
Value to set user's nickname to
await mapih . discord . guilds . members . updateCurrent ( {
guild_id : '0000000000' ,
nick : 'cool new nick'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
user_id
snowflake
The user ID of the user to assign the role to
role_id
snowflake
The role ID of the role to give the user
await mapih . discord . guilds . members . addRole ( {
guild_id : '0000000000' ,
user_id : '0000000000' ,
role_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
user_id
snowflake
The user ID of the user to remove the role from
role_id
snowflake
The role ID of the role to remove from the user
await mapih . discord . guilds . members . removeRole ( {
guild_id : '0000000000' ,
user_id : '0000000000' ,
role_id : '0000000000'
} ) ;
Get Member Permission Names
Type
Description
array of role IDs
Roles of a member
array of role objects
Roles of a guild
const x = params . member . roles ;
const y = params . guild . roles ;
const permNames = getPermissionNames ( x , y ) ;
• Sets/adjusts/clears a member's timeout
Field
Type
Description
guild_id
snowflake
the id of the guild
user_id
snowflake
The user ID of the user to remove the role from
duration
number
Duration in seconds to set timeout. Set to null
or omit to clear timeout.
reason?
string
Reason
// timeout a member for 5 minutes
await mapih . discord . guilds . members . timeout ( {
guild_id : '0000000000' ,
user_id : '0000000000' ,
duration : 300 // 5 minutes
} ) ;
// clear a member's timeout
await mapih . discord . guilds . members . timeout ( {
guild_id : '0000000000' ,
user_id : '0000000000'
} ) ;
Method
Description
retrieve
Retrieve a role by ID
getAll
List all roles in a guild
create
Create a new role in the guild
update
Modify properties of a guild role
destroy
Modify properties of a guild role
Field
Type
Description
guild_id
snowflake
the id of the guild
role_id
snowflake
the id of the role
await mapih . discord . guilds . roles . retrieve ( {
guild_id : '0000000000' ,
role_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . roles . getAll ( {
guild_id : '0000000000'
} ) ;
Field
Type
Description
Default
guild_id
snowflake
the id of the guild
role_id
snowflake
the id of the role
name
string
name of the role, max 100 characters
"new role"
permissions
string
bitwise value of the enabled/disabled permissions
@everyone
color
number
RGB color value
0
hoist
boolean
whether the role should be displayed separately in the sidebar
false
icon
url/buffer
the role's icon image (if the guild has the ROLE_ICONS
feature)
null
unicode_emoji
?string
the role's unicode emoji as a standard emoji (if guild has the ROLE_ICONS
feature)
null
mentionable
boolean
whether the role should be mentionable
false
await mapih . discord . guilds . roles . create ( {
guild_id : '0000000000' ,
name : 'cool kids' ,
hoist : true ,
mentionable : true ,
icon : 'https://www.picofcoolkid.png'
} ) ;
All parameters to this endpoint are optional and nullable.
Field
Type
Description
guild_id
snowflake
the id of the guild
role_id
snowflake
the id of the role
name
string
name of the role, max 100 characters
permissions
string
bitwise value of the enabled/disabled permissions
color
number
RGB color value
hoist
boolean
whether the role should be displayed separately in the sidebar
icon
url/buffer
the role's icon image (if the guild has the ROLE_ICONS
feature)
unicode_emoji
?string
the role's unicode emoji as a standard emoji (if guild has the ROLE_ICONS
feature)
mentionable
boolean
whether the role should be mentionable
await mapih . discord . guilds . roles . update ( {
guild_id : '0000000000' ,
role_id : '0000000000' ,
name : 'new role name' ,
hoist : false ,
mentionable : false ,
icon : 'https://www.newimage.png'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
role_id
snowflake
the id of the role
reason?
string
reason
await mapih . discord . guilds . roles . destroy ( {
guild_id : '0000000000' ,
role_id : '0000000000'
} ) ;
Modify Guild Role Positions
Field
Type
Description
guild_id
snowflake
the id of the guild
roles
array of partial channel objects
the ids and new positions of the channels to modify
await mapih . discord . guilds . roles . retrieve ( {
guild_id : '0000000000' ,
roles : [
{ id : '0000000000' , position : 3 } ,
{ id : '0000000000' , position : 8 }
]
} ) ;
Method
Description
retrieve
Get a specific emoji from a guild
getAll
List all emojis in a guild
create
Create a new emoji in the guild
update
Modify a guild emoji
destroy
Delete a guild emoji
Field
Type
Description
guild_id
snowflake
the id of the guild
emoji_id
snowflake
The id of the emoji
await mapih . discord . guilds . emojis . retrieve ( {
guild_id : '0000000000' ,
emoji_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . emojis . getAll ( {
guild_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
name
string
name of the emoji
image
url/buffer
the 128x128 emoji image
roles
array of snowflakes
roles allowed to use this emoji
await mapih . discord . guilds . emojis . create ( {
guild_id : '0000000000' ,
name : 'goodsie' ,
image : 'https://picofgoodsie.png'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
emoji_id
snowflake
the id of the emoji
name
string
name of the emoji
roles
array of snowflakes
roles allowed to use this emoji
await mapih . discord . guilds . emojis . update ( {
guild_id : '0000000000' ,
emoji_id : '0000000000' ,
name : 'newemojiname'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
emoji_id
snowflake
The id of the emoji
await mapih . discord . guilds . emojis . destroy ( {
guild_id : '0000000000' ,
emoji_id : '0000000000'
} ) ;
Field
Type
Description
sticker_id
snowflake
The id of the sticker
await mapih . discord . guilds . stickers . retrieve ( {
sticker_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
sticker_id
snowflake
The id of the sticker
await mapih . discord . guilds . stickers . retrieveGuild ( {
guild_id : '0000000000' ,
sticker_id : '0000000000'
} ) ;
await mapih . discord . guilds . stickers . retrieve ( ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . stickers . getAll ( {
guild_id : '0000000000'
} ) ;
This endpoint may take time. It goes through multiple functions before returning the sticker.
Field
Type
Description
guild_id
snowflake
the id of the guild
name
string
name of the sticker (2-30 characters)
description
string
description of the sticker (empty or 2-100 characters)
tags
string
autocomplete/suggestion tags for the sticker (max 200 characters)
file
url/buffer
the sticker file to upload
await mapih . discord . guilds . stickers . create ( {
guild_id : '0000000000' ,
name : 'mynewsticker' ,
description : 'cool description' ,
tags : 'uhhh' ,
file : 'https://uhhh.gif'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
name
string
name of the sticker (2-30 characters)
description
string
description of the sticker (empty or 2-100 characters)
tags
string
autocomplete/suggestion tags for the sticker (max 200 characters)
await mapih . discord . guilds . stickers . update ( {
guild_id : '0000000000' ,
name : 'mynewnewsticker' ,
description : 'new cool description' ,
tags : 'new uhhh' ,
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
sticker_id
string
the id of the sticker
await mapih . discord . guilds . stickers . destroy ( {
guild_id : '0000000000' ,
sticker_id : '0000000000' ,
} ) ;
Method
Description
retrieve
Get a specific scheduled event in the guild
getAll
List all scheduled events for the guild
getUsers
Get users subscribed to a scheduled event
create
Create a new scheduled event in the guild
update
Modify a guild scheduled event
destroy
Delete a guild scheduled event
Field
Type
Description
guild_id
snowflake
the id of the guild
guild_scheduled_event_id
snowflake
the id of the event
with_user_count?
boolean
include number of users subscribed to each event
await mapih . discord . guilds . events . retrieve ( {
guild_id : '0000000000' ,
guild_scheduled_event_id : '0000000000' ,
with_user_count : true
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
with_user_count?
boolean
include number of users subscribed to each event
await mapih . discord . guilds . events . getAll ( {
guild_id : '0000000000' ,
with_user_count : true
} ) ;
Field
Type
Description
Default
guild_id
snowflake
the id of the guild
guild_scheduled_event_id
snowflake
the id of the event
limit?
number
number of users to return (up to maximum 100)
100
with_member?
boolean
include guild member data if it exists
false
before? *
snowflake
consider only users before given user id
null
after? *
snowflake
consider only users after given user id
null
* Provide a user id to before
and after
for pagination. Users will always be returned in ascending order by user_id
.
If both before
and after
are provided, only before
is respected. Fetching users in-between before
and after
is not supported.**
await mapih . discord . guilds . events . getUsers ( {
guild_id : '0000000000' ,
guild_scheduled_event_id : '0000000000' ,
limit : 10 ,
with_member : true
} ) ;
Field
Type
Description
guild_id
snowflake
channel_id? *
?snowflake
Set to null
if changing entity type to EXTERNAL
entity_metadata? **
entity metadata
The entity metadata of the scheduled event
name
string
The name of the scheduled event
privacy_level
privacy level
The privacy level of the scheduled event
scheduled_start_time
ISO8601 timestamp
The time to schedule the scheduled event
scheduled_end_time? **
ISO8601 timestamp
The time when the scheduled event is scheduled to end
description?
string
The description of the scheduled event
entity_type
event entity type
The entity type of the scheduled event
image?
url/buffer
The cover image of the scheduled event
* Optional for events with 'entity_type': EXTERNAL
** Required for events with 'entity_type': EXTERNAL
await mapih . discord . guilds . events . create ( {
guild_id : '0000000000' ,
name : 'Cool Event Name' ,
privacy_level : 2 ,
scheduled_start_time : '2023-04-04T11:00:00' ,
entity_type : 2 ,
channel_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
channel_id? *
?snowflake
Set to null
if changing entity type to EXTERNAL
entity_metadata?
?entity metadata
The entity metadata of the scheduled event
name?
string
The name of the scheduled event
privacy_level?
privacy level
The privacy level of the scheduled event
scheduled_start_time?
ISO8601 timestamp
The time to schedule the scheduled event
scheduled_end_time? *
ISO8601 timestamp
The time when the scheduled event is scheduled to end
description?
?string
The description of the scheduled event
entity_type? *
event entity type
The entity type of the scheduled event
status?
event status
The status of the scheduled event
image?
url/buffer
The cover image of the scheduled event
* If updating entity_type
to EXTERNAL
:
channel_id
is required and must be set to null
entity_metadata
with a location
field must be provided
scheduled_end_time
must be provided
await mapih . discord . guilds . events . update ( {
guild_id : '0000000000' ,
guild_scheduled_event_id : '0000000000'
name : 'Edited Event Name' ,
status : 2 // ACTIVE
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . guilds . events . destroy ( {
guild_id : '0000000000'
} ) ;
Method
Description
retrieve
Get a guild template by its code
getAll
List all templates for a guild
create
Create a new template for the guild
createGuild
Create a new guild from a template
sync
Sync a guild template with the guild's current state
update
Modify a guild template
destroy
Delete a guild template
Field
Type
Description
template_code
snowflake
the template's code
await mapih . discord . guilds . templates . retrieve ( {
template_code : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the guild id
await mapih . discord . guilds . templates . getAll ( {
guild_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the guild's id
name
string
name of the template (1-100 characters)
description?
?string
description for the template (0-120 characters)
await mapih . discord . guilds . templates . create ( {
guild_id : '0000000000' ,
name : 'fancy template'
} ) ;
Field
Type
Description
guild_id
snowflake
the guild's id
template_code
snowflake
the template's code
name?
string
name of the template (1-100 characters)
description?
?string
description for the template (0-120 characters)
await mapih . discord . guilds . templates . update ( {
guild_id : '0000000000' ,
template_code : '0000000000' ,
name : 'new fancy template name'
} ) ;
Field
Type
Description
guild_id
snowflake
the guild id
template_code
snowflake
the template's code
await mapih . discord . guilds . templates . destroy ( {
guild_id : '0000000000' ,
template_code : '0000000000'
} ) ;
This endpoint can be used only by bots in less than 10 guilds.
Field
Type
Description
guild_id
snowflake
the guild's id
template_code
snowflake
the template's code
name
string
name of the template (1-100 characters)
icon?
url/buffer
image url or image buffer for the guild's icon
await mapih . discord . guilds . templates . createGuild ( {
template_code : '0000000000' ,
name : 'Eric\'s cool server template' ,
icon : 'https://templateGuildIcon.png'
} ) ;
Field
Type
Description
guild_id
snowflake
the guild id
template_code
snowflake
the template's code
await mapih . discord . guilds . templates . sync ( {
guild_id : '0000000000' ,
template_code : '0000000000'
} ) ;
All functions relating to Discord Channels
Field
Type
Description
channel_id
snowflake
the id of the channel
await mapih . discord . channels . retrieve ( {
channel_id : '0000000000'
} ) ;
Field
Type
Description
Channel Type
channel_id
snowflake
the id of the channel
name
string
1-100 character channel name
All
type
number
the type of channel ; only conversion between text and announcement is supported and only in guilds with the "NEWS" feature
Text, Announcement
position
?number
the position of the channel in the left-hand listing
All
topic
?string
0-1024 character channel topic (0-4096 characters for GUILD_FORUM
and GUILD_MEDIA
channels)
Text, Announcement, Forum, Media
nsfw
?boolean
whether the channel is nsfw
Text, Voice, Announcement, Stage, Forum, Media
rate_limit_per_user
?number
amount of seconds a user has to wait before sending another message (0-21600); bots, as well as users with the permission manage_messages
or manage_channel
, are unaffected
Text, Voice, Stage, Forum, Media
bitrate*
?number
the bitrate (in bits) of the voice or stage channel; min 8000
Voice, Stage
user_limit
?number
the user limit of the voice or stage channel, max 99 for voice channels and 10,000 for stage channels (0 refers to no limit)
Voice, Stage
permission_overwrites**
?array of partial overwrite objects
channel or category-specific permissions
All
parent_id
?snowflake
id of the new parent category for a channel
Text, Voice, Announcement, Stage, Forum, Media
rtc_region
?string
channel voice region id, automatic when set to null
Voice, Stage
video_quality_mode
?number
the camera video quality mode of the voice channel
Voice, Stage
default_auto_archive_duration
?number
the default duration that the clients use (not the API) for newly created threads in the channel, in minutes, to automatically archive the thread after recent activity
Text, Announcement, Forum, Media
flags?
number
channel flags combined as a bitfield. Currently only REQUIRE_TAG
(1 << 4
) is supported by GUILD_FORUM
and GUILD_MEDIA
channels. HIDE_MEDIA_DOWNLOAD_OPTIONS
(1 << 15
) is supported only by GUILD_MEDIA
channels
Forum, Media
available_tags?
array of tag objects
the set of tags that can be used in a GUILD_FORUM
or a GUILD_MEDIA
channel; limited to 20
Forum, Media
default_reaction_emoji?
?default reaction object
the emoji to show in the add reaction button on a thread in a GUILD_FORUM
or a GUILD_MEDIA
channel
Forum, Media
default_thread_rate_limit_per_user?
number
the initial rate_limit_per_user
to set on newly created threads in a channel. this field is copied to the thread at creation time and does not live update.
Text, Forum, Media
default_sort_order?
?number
the default sort order type used to order posts in GUILD_FORUM
and GUILD_MEDIA
channels
Forum, Media
default_forum_layout?
number
the default forum layout type used to display posts in GUILD_FORUM
channels
Forum
* For voice channels, normal servers can set bitrate up to 96000, servers with Boost level 1 can set up to 128000, servers with Boost level 2 can set up to 256000, and servers with Boost level 3 or the VIP_REGIONS
guild feature can set up to 384000. For stage channels, bitrate can be set up to 64000.
** In each overwrite object, the allow
and deny
keys can be omitted or set to null
, which both default to "0"
.
• When setting archived
to false
, when locked
is also false
, only the SEND_MESSAGES
permission is required.
• Otherwise, requires the MANAGE_THREADS
permission.
Field
Type
Description
name
string
1-100 character channel name
archived
boolean
whether the thread is archived
auto_archive_duration
number
the thread will stop showing in the channel list after auto_archive_duration
minutes of inactivity, can be set to: 60, 1440, 4320, 10080
locked
boolean
whether the thread is locked; when a thread is locked, only users with MANAGE_THREADS can unarchive it
invitable
boolean
whether non-moderators can add other non-moderators to a thread; only available on private threads
rate_limit_per_user
?number
amount of seconds a user has to wait before sending another message (0-21600); bots, as well as users with the permission manage_messages
, manage_thread
, or manage_channel
, are unaffected
flags?
number
channel flags ; PINNED
can only be set for threads in forum and media channels
applied_tags?
array of snowflakes
the IDs of the set of tags that have been applied to a thread in a GUILD_FORUM
or a GUILD_MEDIA
channel; limited to 5
await mapih . discord . channels . update ( {
channel_id : '0000000000' ,
name : 'new-name'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
await mapih . discord . channels . destroy ( {
channel_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
allow?
string?
the bitwise value of all allowed permissions (default "0"
)
deny?
string?
the bitwise value of all disallowed permissions (default "0"
)
type
number
0 for a role or 1 for a member
await mapih . discord . channels . editPermissions ( {
channel_id : '0000000000' ,
overwrite_id : '0000000000' ,
type : 1 , // member
allow : '1024'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
await mapih . discord . channels . deletePermissions ( {
channel_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
await mapih . discord . channels . getInvites ( {
channel_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
uses
number
number of times this invite has been used
max_uses
number
max number of times this invite can be used
max_age
number
duration (in seconds) after which the invite expires
temporary
boolean
whether this invite only grants temporary membership
created_at
ISO8601 timestamp
when this invite was created
await mapih . discord . channels . inviteCreate ( {
channel_id : '0000000000' ,
max_age : 7200 ,
max_uses : 1
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
await mapih . discord . channels . typingCreate ( {
channel_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel to send announcements to
webhook_channel_id
snowflake
the id of the target channel
await mapih . discord . channels . followAnnouncementChannel ( {
channel_id : '0000000000' ,
webhook_channel_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel to send announcements to
user_id
snowflake
the id of the channel to send announcements to
access_token
string
access token of a user that has granted your app the gdm.join
scope
nick
string
nickname of the user being added
await mapih . discord . channels . groupDMadd ( {
channel_id : '0000000000' ,
user_id : '0000000000' ,
access_token : 'abcdef123456' ,
nick : 'userNickname'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel to send announcements to
user_id
snowflake
the id of the user to remove
await mapih . discord . channels . groupDMremove ( {
channel_id : '0000000000' ,
user_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
message_id
snowflake
the id of the message
await mapih . discord . channels . messages . retrieve ( {
channel_id : '0000000000' ,
message_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
around?
snowflake
Get messages around this message ID
before?
snowflake
Get messages before this message ID
after?
snowflake
Get messages after this message ID
limit?
number
Max number of messages to return (1-100) (default 50)
The before
, after
, and around
parameters are mutually exclusive, only one may be passed at a time.
await mapih . discord . channels . messages . getAll ( {
channel_id : '0000000000' ,
limit : 50
} ) ;
To create a message as a reply to another message, apps can include a message_reference with a message_id
.
• The channel_id
and guild_id
in the message_reference
are optional, but will be validated if provided.
Field
Type
Description
channel_id
snowflake
Channel id of the channel to send the message to
content?*
string
Message contents (up to 2000 characters)
tts?
boolean
true
if this is a TTS message
embeds?*
array of embed objects
Up to 10 rich
embeds (up to 6000 characters)
allowed_mentions?
allowed mention object
Allowed mentions for the message
message_reference?
message reference
Include to make your message a reply
components?*
array of message component objects
Components to include with the message
sticker_ids?*
array of snowflakes
IDs of up to 3 stickers in the server to send in the message
attachments?
array of partial attachment objects
Attachment objects with filename and description.
flags?
number
Message flags (only SUPPRESS_EMBEDS
and SUPPRESS_NOTIFICATIONS
can be set)
* At least one of content
, embeds
, sticker_ids
, components
, or files[n]
is required.
await mapih . discord . channels . messages . create ( {
channel_id : '0000000000' ,
content : 'sup'
} ) ;
await mapih . discord . channels . messages . create ( {
channel_id : '0000000000' ,
content : '' ,
embeds : [ {
title : 'embed title' ,
description : 'embed description'
} ] ,
components : [ {
type : 1 ,
components : [ {
type : 2 , // button
style : 1 ,
label : 'buttonLabel' ,
custom_id : 'asdfghjkl'
} ]
} ]
} ) ;
await mapih . discord . channels . messages . create ( {
channel_id : '0000000000' ,
content : 'this will surprese all mentions' ,
allowed_mentions : {
parse : [ ]
}
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel the message is in
message_id
snowflake
the id of the message to edit
content?
string
Message contents (up to 2000 characters)
embeds?
array of embed objects
Up to 10 rich
embeds (up to 6000 characters)
allowed_mentions?
allowed mention object
Allowed mentions for the message
message_reference?
message reference
Include to make your message a reply
components?
array of message component objects
Components to include with the message
attachments?
array of partial attachment objects
Attachment objects with filename and description.
flags?
number
Message flags (only SUPPRESS_EMBEDS
and SUPPRESS_NOTIFICATIONS
can be set)
• When the content field is edited, the mentions array in the message object will be reconstructed from scratch based on the new content.
• The allowed_mentions field of the edit request controls how this happens.
• If there is no explicit allowed_mentions in the edit request, the content will be parsed with default allowances, that is, without regard to whether or not an allowed_mentions was present in the request that originally created the message.
• The attachments array must contain all attachments that should be present after edit, including retained and new attachments.
await mapih . discord . channels . messages . update ( {
channel_id : '0000000000' ,
message_id : '0000000000' ,
content : 'new message'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
message_id
snowflake
the id of the message
await mapih . discord . channels . messages . destroy ( {
channel_id : '0000000000' ,
message_id : '0000000000'
} ) ;
• Any message IDs given that do not exist or are invalid will count towards the minimum and maximum message count (currently 2 and 100 respectively).
This endpoint will not delete messages older than 2 weeks.
Field
Type
Description
channel_id
snowflake
the id of the channel
messages
array of snowflakes
an array of message ids to delete (2-100)
await mapih . discord . channels . messages . bulkDelete ( {
channel_id : '0000000000' ,
messages : [
'0000000000' ,
'0000000000'
]
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
message_id
snowflake
the message id of the message to crosspost
await mapih . discord . channels . messages . crosspost ( {
channel_id : '0000000000' ,
message_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
message_id
snowflake
the message id of the message to pin
await mapih . discord . channels . messages . pin ( {
channel_id : '0000000000' ,
message_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
message_id
snowflake
the message id of the message to unpin
await mapih . discord . channels . messages . unpin ( {
channel_id : '0000000000' ,
message_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
await mapih . discord . channels . messages . getPinned ( {
channel_id : '0000000000'
} ) ;
All functions relating to Discord Threads
Field
Type
Description
channel_id
snowflake
the id of the channel
name
string
1-100 character channel name
auto_archive_duration?*
integer
duration in minutes to automatically archive the thread after recent activity, can be set to: 60, 1440, 4320, 10080
rate_limit_per_user?
?integer
amount of seconds a user has to wait before sending another message (0-21600)
message
forum thread message params object
contents of the first message in the forum/media thread
applied_tags?
array of snowflakes
the IDs of the set of tags that have been applied to a thread in a GUILD_FORUM
or a GUILD_MEDIA
channel
await mapih . discord . channels . threads . forumThreadCreate ( {
channel_id : '0000000000' ,
name : 'thread name' ,
message : {
content : 'new message' ,
embeds : [ {
title : 'example' ,
description : 'example'
} ]
} ,
auto_archive_duration : 4320
} ) ;
• When called on a GUILD_TEXT
channel, creates a PUBLIC_THREAD
.
• When called on a GUILD_ANNOUNCEMENT
channel, creates an ANNOUNCEMENT_THREAD
.
• Does not work on a GUILD_FORUM
channel.
• The ID of the created thread will be the same as the ID of the source message, and as such a message can only have a single thread created from it.
Field
Type
Description
channel_id
snowflake
the id of the channel
message_id
snowflake
the id of the message to create the thread from
name
string
1-100 character channel name
auto_archive_duration?
number
duration in minutes to automatically archive the thread after recent activity, can be set to: 60, 1440, 4320, 10080
rate_limit_per_user?
?number
amount of seconds a user has to wait before sending another message (0-21600)
await mapih . discord . channels . threads . createFromMessage ( {
channel_id : '0000000000' ,
message_id : '0000000000' ,
name : 'thread name' ,
auto_archive_duration : 10080
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
name
string
1-100 character channel name
type? *
number
the type of thread to create
invitable? *
boolean
whether non-moderators can add other non-moderators to a thread; only available when creating a private thread
rate_limit_per_user?
?number
amount of seconds a user has to wait before sending another message (0-21600)
* type
currently defaults to PRIVATE_THREAD
in order to match the behavior when thread documentation was first published.
await mapih . discord . channels . threads . createWithoutMessage ( {
channel_id : '0000000000' ,
type : 11 , // PUBLIC_THREAD
name : 'thread name' ,
auto_archive_duration : 10080 ,
invitable : true
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
await mapih . discord . channels . threads . join ( {
channel_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
await mapih . discord . channels . threads . leave ( {
channel_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
user_id
snowflake
the id of the user to add
await mapih . discord . channels . threads . addMember ( {
channel_id : '0000000000' ,
user_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
user_id
snowflake
the id of the user to add
await mapih . discord . channels . threads . removeMember ( {
channel_id : '0000000000' ,
user_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
user_id
snowflake
the id of the user to add
with_member?
boolean
whether to include a guild member object
await mapih . discord . channels . threads . retrieveMember ( {
channel_id : '0000000000' ,
user_id : '0000000000' ,
with_member : true
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
user_id
snowflake
the id of the user to add
with_member?
boolean
whether to include a guild member object
after?
snowflake
Get thread members after this user ID
limit?
integer
Max number of thread members to return (1-100). Defaults to 100.
await mapih . discord . channels . threads . getAllMembers ( {
channel_id : '0000000000' ,
with_member : true
} ) ;
• When called on a GUILD_TEXT
channel, returns threads of type PUBLIC_THREAD
.
• When called on a GUILD_ANNOUNCEMENT
channel, returns threads of type ANNOUNCEMENT_THREAD
.
• Threads are ordered by archive_timestamp
, in descending order.
Field
Type
Description
channel_id
snowflake
the id of the channel
before?
ISO8601 timestamp
returns threads archived before this timestamp
limit?
integer
optional maximum number of threads to return
await mapih . discord . channels . threads . getAllPublicArchived ( {
channel_id : '0000000000' ,
limit : 10
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
before?
ISO8601 timestamp
returns threads archived before this timestamp
limit?
integer
optional maximum number of threads to return
await mapih . discord . channels . threads . getAllPrivateArchived ( {
channel_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
before?
ISO8601 timestamp
returns threads archived before this timestamp
limit?
integer
optional maximum number of threads to return
await mapih . discord . channels . threads . getAllJoinedPrivateArchived ( {
channel_id : '0000000000'
} ) ;
Method
Description
create
Create a reaction for the message
createMany
Create multiple reactions to a message at once
deleteOwn
Delete a reaction the current user has made for the message
deleteUser
Deletes another user's reaction
deleteAll
Deletes all reactions on a message
deleteAllEmoji
Deletes all the reactions for a given emoji on a message
getUsers
Get a list of users that reacted with this emoji
| Field | Type | Description |
|------------------------|-------------------------|
| channel_id | snowflake | the id of the channel |
| message_id | snowflake | the id of the message |
| emoji | string | the emoji to react with |
await mapih . discord . channels . reactions . create ( {
channel_id : '0000000000' ,
message_id : '0000000000' ,
emoji : 'name:id'
} ) ;
| Field | Type | Description |
|------------------------|--------------------------------------------------------------------------------------------------|
| channel_id | snowflake | The id of the channel |
| message_id | snowflake | The id of the message |
| emojis | string[] | An array of emoji parameters |
| delay? | number | Amount of millseconds to wait between reactions. For use when getting rate-limited. Default 300. |
await mapih . discord . channels . reactions . createMany ( {
channel_id : '0000000000' ,
message_id : '0000000000' ,
emojis : [
'name:id:' ,
'name:id:' ,
'name:id:'
] ,
delay : 200
} ) ;
| Field | Type | Description |
|------------------------|-------------------------|
| channel_id | snowflake | the id of the channel |
| message_id | snowflake | the id of the message |
| emoji | string | the emoji to react with |
await mapih . discord . channels . reactions . deleteOwn ( {
channel_id : '0000000000' ,
message_id : '0000000000' ,
emoji : 'name:id'
} ) ;
| Field | Type | Description |
|------------------------|-----------------------------------------|
| channel_id | snowflake | the id of the channel |
| message_id | snowflake | the id of the message |
| user_id | snowflake | the id the user the reaction belongs to |
| emoji | string | the emoji to react with |
await mapih . discord . channels . reactions . deleteUser ( {
channel_id : '0000000000' ,
message_id : '0000000000' ,
user_id : '0000000000' ,
emoji : 'name:id'
} ) ;
| Field | Type | Description |
|------------------------|-------------------------|
| channel_id | snowflake | the id of the channel |
| message_id | snowflake | the id of the message |
await mapih . discord . channels . reactions . deleteAll ( {
channel_id : '0000000000' ,
message_id : '0000000000'
} ) ;
| Field | Type | Description |
|------------------------|-------------------------|
| channel_id | snowflake | the id of the channel |
| message_id | snowflake | the id of the message |
| emoji | string | the emoji to delete |
await mapih . discord . channels . reactions . deleteAllEmoji ( {
channel_id : '0000000000' ,
message_id : '0000000000' ,
emoji : ':name:id'
} ) ;
| Field | Type | Description |
|------------------------|----------------------------------------------------|
| channel_id | snowflake | the id of the channel |
| message_id | snowflake | the id of the message |
| emoji | string | the emoji to get users for |
| after? | snowflake | Get users after this user ID |
| limit? | integer | Max number of users to return (1-100) (default 25) |
await mapih . discord . channels . reactions . getUsers ( {
channel_id : '0000000000' ,
message_id : '0000000000' ,
emoji : ':name:id' ,
limit : 50
} ) ;
All functions relating to Discord Users
Field
Type
Description
user_id
snowflake
the id of the user
await mapih . discord . users . retrieve ( {
user_id : '0000000000'
} ) ;
await mapih . discord . users . currentUser ( ) ;
Field
Type
Description
before
snowflake
get guilds before this guild ID
after
snowflake
get guilds after this guild ID
limit
integer
max number of guilds to return (1-200) (default 200)
with_counts
boolean
include approximate member and presence counts in response
await mapih . discord . users . myGuilds ( ) ;
Field
Type
Description
guild_id
snowflake
id of the guild to get member object from
await mapih . discord . users . currentMember ( {
guild_id : '0000000000' ,
} ) ;
All parameters to this endpoint are optional.
Field
Type
Description
username
string
user's username
avatar
url/buffer
if passed, modifies the user's avatar
await mapih . discord . users . updateCurrent ( {
username : 'new username' ,
avatar : 'https://imageURL.png'
} ) ;
await mapih . discord . users . connections ( ) ;
Field
Type
Description
application_id?
snowflake
bot's application id
await mapih . discord . users . appRoleConnection ( ) ;
Requires an OAuth2 access token with role_connections.write
scope for the application specified in the path.
Field
Type
Description
platform_name?
string
the vanity name of the platform a bot has connected (max 50 characters)
platform_username?
string
the username on the platform a bot has connected (max 100 characters)
metadata?
object
object mapping application role connection metadata keys to their string
-ified value (max 100 characters) for the user on the platform a bot has connected
await mapih . discord . users . updateAppRoleConnection ( {
platform_name : 'OnSocket' ,
platform_username : 'goodsie'
} ) ;
Field
Type
Description
recipient_id
snowflake
the recipient to open a DM channel with
content?*
string
Message contents (up to 2000 characters)
tts?
boolean
true
if this is a TTS message
embeds?*
array of embed objects
Up to 10 rich
embeds (up to 6000 characters)
allowed_mentions?
allowed mention object
Allowed mentions for the message
message_reference?
message reference
Include to make your message a reply
components?*
array of message component objects
Components to include with the message
sticker_ids?*
array of snowflakes
IDs of up to 3 stickers in the server to send in the message
attachments?
array of partial attachment objects
Attachment objects with filename and description.
flags?
integer
Message flags (only SUPPRESS_EMBEDS
and SUPPRESS_NOTIFICATIONS
can be set)
* At least one of content
, embeds
, sticker_ids
, components
, or files[n]
is required.
await mapih . discord . users . createDM ( {
recipient_id : '0000000000' ,
content : '<super cool message here>'
} ) ;
Field
Type
Description
access_tokens
array of strings
access tokens of users that have granted your app the gdm.join
scope
nicks
dict
a dictionary of user ids to their respective nicknames
content?*
string
Message contents (up to 2000 characters)
tts?
boolean
true
if this is a TTS message
embeds?*
array of embed objects
Up to 10 rich
embeds (up to 6000 characters)
allowed_mentions?
allowed mention object
Allowed mentions for the message
message_reference?
message reference
Include to make your message a reply
components?*
array of message component objects
Components to include with the message
sticker_ids?*
array of snowflakes
IDs of up to 3 stickers in the server to send in the message
attachments?
array of partial attachment objects
Attachment objects with filename and description.
flags?
integer
Message flags (only SUPPRESS_EMBEDS
and SUPPRESS_NOTIFICATIONS
can be set)
* At least one of content
, embeds
, sticker_ids
, components
, or files[n]
is required.
await mapih . discord . users . createGroupDM ( {
access_tokens : [
'0000000000' ,
'0000000000'
] ,
nicks : {
'user_id' : 'nickname'
} ,
content : 'boo' ,
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild to leave
await mapih . discord . users . leaveGuild ( {
guild_id : '0000000000'
} ) ;
| Namespace |
| Callback |
| Followup |
Method
Description
reply
Create a response to an Interaction
defer
Send "thinking" state and edit response later
get_original
Get the initial Interaction response
update_original
Edit the initial Interaction response
delete_original
Delete the initial Interaction response
component_defer
*
Acknowledge an interaction and edit response later
component_update
*
Edit the message the component was attached to
autocomplete_reply
Respond to an autocomplete interaction with suggested choices
modal_reply
**
Respond to an interaction with a popup modal
upgrade
***
Respond to an interaction with an upgrade button
* Only valid for component-based interactions.
** Not available for MODAL_SUBMIT
and PING
interactions.
*** Only available for apps with monetization enabled.
Field
Type
Description
params
object
The interaction payload
ephemeral?
boolean
Whether the message should be visible to only the user
content?*
string
Message contents (up to 2000 characters)
tts?
boolean
true
if this is a TTS message
embeds?*
array of embed objects
Up to 10 rich
embeds (up to 6000 characters)
allowed_mentions?
allowed mention object
Allowed mentions for the message
components?*
array of message component objects
Components to include with the message
attachments?
array of partial attachment objects
Attachment objects with filename and description
* At least one of content
, embeds
, sticker_ids
, components
, or files[n]
is required.
await mapih . discord . interactions . callback . reply ( params , {
ephemeral : true ,
content : 'This will respond to an interaction immediately'
} ) ;
Defer Interaction Response
Field
Type
Description
params
object
The interaction payload
ephemeral?
boolean
Whether the message should be visible to only the user
await mapih . discord . interactions . callback . defer ( params , {
ephemeral : true
} ) ;
await mapih . discord . interactions . callback . defer ( params )
Field
Type
Description
params
object
The interaction payload
await mapih . discord . interactions . callback . get_original ( params ) ;
Field
Type
Description
params
object
The interaction payload
content?*
string
Message contents (up to 2000 characters)
embeds?*
array of embed objects
Up to 10 rich
embeds (up to 6000 characters)
allowed_mentions?
allowed mention object
Allowed mentions for the message
components?*
array of message component objects
Components to include with the message
attachments?
array of partial attachment objects
Attachment objects with filename and description
await mapih . discord . interactions . callback . update_original ( params , {
content : 'This will update the original interaction response'
} ) ;
Field
Type
Description
params
object
The interaction payload
await mapih . discord . interactions . callback . delete_original ( params ) ;
Field
Type
Description
params
object
The interaction payload
await mapih . discord . interactions . callback . component_defer ( params ) ;
Field
Type
Description
params
object
The interaction payload
content?*
string
Message contents (up to 2000 characters)
embeds?*
array of embed objects
Up to 10 rich
embeds (up to 6000 characters)
allowed_mentions?
allowed mention object
Allowed mentions for the message
components?*
array of message component objects
Components to include with the message
attachments?
array of partial attachment objects
Attachment objects with filename and description
await mapih . discord . interactions . callback . component_update ( params , {
content : 'new stuff!'
} ) ;
Field
Type
Description
params
object
The interaction payload
choices
array of choices
Autocomplete Choices (max of 25 choices)
await mapih . discord . interactions . callback . autocomplete_reply ( params , {
choices : [
{
name : 'this might be wrong' ,
value : 'let me know'
}
]
} ) ;
Field
Type
Description
custom_id
string
a developer-defined identifier for the modal, max 100 characters
title
string
the title of the popup modal, max 45 characters
components
array of components
between 1 and 5 (inclusive) components that make up the modal
await callback . modal_reply ( params , {
custom_id : 'modal_id' ,
title : 'Title goes here' ,
components : [
{
type : 4 ,
custom_id : 'id_1' ,
label : 'this is a label' ,
style : 1 , // short
placeholder : 'this is a placeholder' ,
required : true
} ,
{
type : 4 ,
custom_id : 'id_2' ,
label : 'This is another label' ,
style : 1 , // paragraph
value : 'this is a pre-filled value' ,
required : false
}
]
} ) ;
Method
Description
retrieve
Get a followupmessage for an interaction
create
Create a followup message for an interaction
update
Edit a followup message for an interaction
destroy
Delete a followup message for an interaction
Field
Type
Description
params
object
The interaction payload
message_id
snowflake
The message id of the message to retrieve
await mapih . discord . interactions . followup . retrieve ( params , {
message_id : '0000000000'
} ) ;
Field
Type
Description
params
object
The interaction payload
ephemeral?
boolean
Whether the message should be visible to only the user
content?*
string
Message contents (up to 2000 characters)
embeds?*
array of embed objects
Up to 10 rich
embeds (up to 6000 characters)
allowed_mentions?
allowed mention object
Allowed mentions for the message
components?*
array of message component objects
Components to include with the message
attachments?
array of partial attachment objects
Attachment objects with filename and description
* At least one of content
, embeds
, sticker_ids
, components
, or files[n]
is required.
await mapih . discord . interactions . followup . create ( params , {
ephemeral : true ,
content : 'followup message' ,
embeds : [ {
title : 'hello' ,
description : 'this is a description'
} ]
} ) ;
Field
Type
Description
params
object
The interaction payload
message_id
snowflake
The id of the message to update
content?*
string
Message contents (up to 2000 characters)
embeds?*
array of embed objects
Up to 10 rich
embeds (up to 6000 characters)
allowed_mentions?
allowed mention object
Allowed mentions for the message
components?*
array of message component objects
Components to include with the message
attachments?
array of partial attachment objects
Attachment objects with filename and description
* At least one of content
, embeds
, sticker_ids
, components
, or files[n]
is required.
await mapih . discord . interactions . followup . update ( params , {
message_id : '0000000000' ,
content : 'followup message' ,
embeds : [ {
title : 'hello' ,
description : 'this is a description'
} ]
} ) ;
Field
Type
Description
params
object
The interaction payload
message_id
snowflake
The message id of the message to retrieve
await mapih . discord . interactions . followup . destroy ( params , {
message_id : '0000000000'
} ) ;
All functions relating to Discord Webhooks
Field
Type
Description
webhook_id
snowflake
the id of the webhook
await mapih . discord . webhooks . retrieve ( {
webhook_id : '0000000000'
} ) ;
This call does not require authentication and returns no user in the webhook object.
Field
Type
Description
webhook_id
snowflake
the id of the webhook
webhook_token
string
the webhook's token
await mapih . discord . webhooks . retrieveWithToken ( {
webhook_id : '0000000000' ,
webhook_token : 'abcdef123456'
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel
await mapih . discord . webhooks . retrieveChannel ( {
webhook_id : '0000000000'
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . webhooks . retrieveGuild ( {
guild_id : '0000000000'
} ) ;
Field
Type
Description
webhook_id
snowflake
the id of the webhook
webhook_token
snowflake
the webhook's token
message_id
snowflake
the id of the message
thread_id
snowflake
id of the thread the message is in
await mapih . discord . webhooks . retrieveMessage ( {
webhook_id : '0000000000' ,
webhook_token : 'abcdef123456' ,
message_id : '0000000000'
} ) ;
Field
Type
Description
webhook_id
snowflake
the id of the webhook
webhook_token
snowflake
the webhook's token
message_id
snowflake
the id of the message
thread_id
snowflake
id of the thread the message is in
content?
string
Message contents (up to 2000 characters)
embeds?
array of embed objects
Up to 10 rich
embeds (up to 6000 characters)
allowed_mentions?
allowed mention object
Allowed mentions for the message
components?
array of message component objects
Components to include with the message
attachments?
array of partial attachment objects
Attachment objects with filename and description
await mapih . discord . webhooks . updateMessage ( {
webhook_id : '0000000000' ,
webhook_token : 'abcdef123456' ,
message_id : '0000000000' ,
content : 'hello'
} ) ;
Field
Type
Description
webhook_id
snowflake
the id of the webhook
webhook_token
snowflake
the webhook's token
message_id
snowflake
the id of the message
thread_id
snowflake
id of the thread the message is in
await mapih . discord . webhooks . destroyMessage ( {
webhook_id : '0000000000' ,
webhook_token : 'abcdef123456' ,
message_id : '0000000000'
} ) ;
Field
Type
Description
channel_id?
snowflake
the channel id of the channel to create webhook for
name?
string
name of the webhook (1-80 characters)
avatar?
?url/buffer
image for the default webhook avatar
await mapih . discord . webhooks . create ( {
channel_id : '0000000000' ,
name : 'myNewWebhook'
} ) ;
Field
Type
Description
webhook_id
snowflake
the webhook id of the webhook to edit
channel_id
snowflake
the channel id of the channel to create webhook for
name
string
name of the webhook (1-80 characters)
avatar?
?url/buffer
image for the default webhook avatar
await mapih . discord . webhooks . update ( {
webhook_id : '0000000000' ,
channel_id : '0000000000' ,
name : 'myNewNewWebhook'
} ) ;
Field
Type
Description
webhook_id
snowflake
the webhook id of the webhook to edit
webhook_token
string
the token of the webhook to edit
name?
string
name of the webhook (1-80 characters)
avatar?
?url/buffer
image for the default webhook avatar
await mapih . discord . webhooks . updateWithToken ( {
webhook_id : '0000000000' ,
webhook_token : 'abcd1234' ,
name : 'myNewNewWebhook'
} ) ;
Field
Type
Description
webhook_id
snowflake
the id of the webhook
await mapih . discord . webhooks . destroy ( {
webhook_id : '0000000000'
} ) ;
Field
Type
Description
webhook_id
snowflake
the id of the webhook
webhook_token
string
the webhook's token
await mapih . discord . webhooks . destroyWithToken ( {
webhook_id : '0000000000' ,
webhook_token : 'abcdef123456'
} ) ;
Field
Type
Description
webhook_id
snowflake
the id of the webhook
webhook_token
snowflake
the webhook's token
username
string
override the default username of the webhook
avatar_url
string
override the default avatar of the webhook
thread_id
snowflake
id of the thread the message is in
content
string
Message contents (up to 2000 characters)
embeds
array of embed objects
Up to 10 rich
embeds (up to 6000 characters)
allowed_mentions
allowed mention object
Allowed mentions for the message
components
array of message component objects
Components to include with the message
attachments
array of partial attachment objects
Attachment objects with filename and description
thread_name
string
name of thread to create (requires the webhook channel to be a forum or media channel)
applied_tags
array of snowflakes
array of tag ids to apply to the thread (requires the webhook channel to be a forum or media channel)
wait
boolean
Waits for server confirmation of message send before response, and returns the created message body
await mapih . discord . webhooks . execute ( {
webhook_id : '0000000000' ,
webhook_token : 'abcdef123456' ,
content : 'message contents here' ,
username : 'webhook usernrame' ,
avatar_url : 'https://imgurl.png' ,
embeds : [ {
title : 'example' ,
description : 'example'
} ]
} ) ;
All functions relating to Discord Invites
Method
Description
retrieve
Get information about a specific invite
revoke
Revoke an invite
Field
Type
Description
invite_code
string
the invite's code
with_counts?
boolean
whether the invite should contain approximate member counts
with_expiration?
boolean
whether the invite should contain the expiration date
guild_scheduled_event_id?
snowflake
the guild scheduled event to include with the invite
await mapih . discord . invites . retrieve ( {
invite_code : '0vCdhLbwjZZTWZLD' ,
with_counts : true ,
with_expiration : true
} ) ;
| Field | Type | Description |
| invite_code | string | the invite's code |
await mapih . discord . invites . revoke ( {
invite_code : '0vCdhLbwjZZTWZLD'
} ) ;
All Discord API endpoints relating to applications, commands, entitlements and SKUs
Method
Description
getMe
Get inforation on the current application
updateMe
Edit properties of the app associated with the requesting bot user
appRoleConnectionMeta
Get the applications role connection metadata information
updateAppRoleConnectionMeta
Updates the application role connection metadata for the given application
Field
Type
Description
application_id?
snowflake
the id of the application
await mapih . discord . applications . getMe ( ) ;
Field
Type
Description
application_id?
snowflake
the id of the application
custom_install_url
string
Default custom authorization URL for the app, if enabled
description
string
Description of the app
role_connections_verification_url
string
Role connection verification URL for the app
install_params
install params object
Settings for the app's default in-app authorization link, if enabled
flags *
number
App's public flags
icon
url/buffer
Icon for the app
cover_image
url/buffer
Default rich presence invite cover image for the app
interactions_endpoint_url **
string
Interactions endpoint URL for the app
tags
array of strings
List of tags describing the content and functionality of the app (max of 20 characters per tag). Max of 5 tags.
* Only limited intent flags (GATEWAY_PRESENCE_LIMITED
, GATEWAY_GUILD_MEMBERS_LIMITED
, and GATEWAY_MESSAGE_CONTENT_LIMITED
) can be updated via the mapih.
await mapih . discord . applications . updateMe ( {
description : 'new description' ,
icon : 'https://url_to_image.png' // or buffer,
install_params : {
scopes : [
'identify' ,
'bot' ,
'applications.commands'
] ,
permissions : '8'
}
} ) ;
Field
Type
Description
application_id?
snowflake
the id of the application
await mapih . discord . applications . appRoleConnectionMeta ( ) ;
Field
Type
Description
application_id?
snowflake
the id of the application
await mapih . discord . applications . updateAppRoleConnectionMeta ( ) ;
This is to be used for both global and guild commands.
Provide a guild_id field if using for a guild command.
Field
Type
Description
command_id
snowflake
the id of the command
application_id?
snowflake
the id of the application
guild_id?
snowflake
the id of the guild
await mapih . discord . applications . commands . retrieve ( {
command_id : '0000000000' ,
guild_id : '0000000000'
} )
This is to be used for both global and guild commands.
Provide a guild_id field if using for a guild command.
Field
Type
Description
application_id?
snowflake
the id of the application
guild_id?
snowflake
the id of the guild
with_localizations?
boolean
Whether to include full localization dictionaries (name_localizations
and description_localizations
) in the returned objects, instead of the name_localized
and description_localized
fields.
await mapih . discord . applications . commands . getAll ( ) ;
await mapih . discord . applications . commands . getAll ( {
guild_id : '0000000000'
} )
This is to be used for both global and guild commands.
Provide a guild_id field if using for a guild command.
Field
Type
Description
application_id?
snowflake
the id of the application
guild_id?
snowflake
the id of the guild
name
string
Name of command, 1-32 characters
name_localizations?
?dictionary with keys in available locales
Localization dictionary for the name
field. Values follow the same restrictions as name
description?
string
1-100 character description for CHAT_INPUT
commands
description_localizations?
?dictionary with keys in available locales
Localization dictionary for the description
field. Values follow the same restrictions as description
options?
array of application command option
the parameters for the command
default_member_permissions?
?string
Set of permissions represented as a bit set
dm_permission?
?boolean
Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible.
type?
one of application command type
Type of command, defaults 1
if not set
nsfw?
boolean
Indicates whether the command is age-restricted
await mapih . discord . applications . commands . create ( {
name : 'slashcommand' ,
description : 'Command description' ,
guild_id : '0000000000' , // optional
options : [ {
type : 1 , // SUB_COMMAND
name : 'subCommand' ,
options : [
{
type : 3 , // STRING
name : 'content' ,
description : 'Enter content here' ,
required : true
} ,
{
type : 6 , // USER
name : 'user' ,
description : 'Select a user'
}
]
} ]
} )
This is to be used for both global and guild commands.
Provide a guild_id field if using for a guild command.
Field
Type
Description
application_id?
snowflake
the id of the application
guild_id?
snowflake
the id of the guild
name
string
Name of command, 1-32 characters
name_localizations?
?dictionary with keys in available locales
Localization dictionary for the name
field. Values follow the same restrictions as name
description?
string
1-100 character description for CHAT_INPUT
commands
description_localizations?
?dictionary with keys in available locales
Localization dictionary for the description
field. Values follow the same restrictions as description
options?
array of application command option
the parameters for the command
default_member_permissions?
?string
Set of permissions represented as a bit set
dm_permission?
?boolean
Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible.
nsfw?
boolean
Indicates whether the command is age-restricted
await mapih . discord . applications . commands . update ( {
name : 'slashcommand' ,
description : 'Command description' ,
guild_id : '0000000000' , // optional
options : [ {
type : 1 , // SUB_COMMAND
name : 'subCommand' ,
options : [
{
type : 3 , // STRING
name : 'content' ,
description : 'Enter content here' ,
required : true
} ,
{
type : 6 , // USER
name : 'user' ,
description : 'Select a user'
}
]
} ]
} )
This is to be used for both global and guild commands.
Provide a guild_id field if using for a guild command.
Field
Type
Description
command_id
snowflake
the id of the command
application_id?
snowflake
the id of the application
guild_id?
snowflake
the id of the guild
await mapih . discord . applications . commands . destroy ( {
command_id : '0000000000' ,
guild_id : '0000000000'
} )
This is to be used for both global and guild commands.
Provide a guild_id field if using for a guild command.
• Takes a list of application commands, overwriting the existing global command list for this application.
Field
Type
Description
application_id?
snowflake
the id of the application
guild_id?
snowflake
the id of the guild
commands
array of application commands
Commands to overwrite the existing commands with
await mapih . discord . applications . commands . bulkOverwrite ( {
command_id : '0000000000' ,
guild_id : '0000000000' ,
commands : [ commands ]
} )
• Fetches permissions for a specific command for your application in a guild.
Field
Type
Description
command_id
snowflake
the id of the command
application_id?
snowflake
the id of the application
guild_id
snowflake
the id of the guild
await mapih . discord . applications . commands . retrievePermissions ( {
command_id : '0000000000' ,
guild_id : '0000000000'
} )
• Fetches permissions for all commands for your application in a guild.
Field
Type
Description
application_id?
snowflake
the id of the application
guild_id
snowflake
the id of the guild
await mapih . discord . applications . commands . getAllPermissions ( {
guild_id : '0000000000'
} )
• Edits command permissions for a specific command for your application in a guild.
Field
Type
Description
application_id?
snowflake
the id of the application
guild_id
snowflake
the id of the guild
permissions
array of application command permissions
Permissions for the command in the guild
await mapih . discord . applications . commands . updatePermissions ( {
guild_id : '0000000000' ,
permissions : [ {
id : '0000000000' ,
type : 2 ,
'true'
} ]
} )
Method
Description
getAll
Get all entitlements for a given app
create
Creates a test entitlement to a given SKU for a given guild or user
destroy
Deletes a currently-active test entitlement
• Returns all entitlements for a given app, active and expired.
Field
Type
Description
application_id?
snowflake
the id of the application
user_id?
snowflake
User ID to look up entitlements for
sku_ids?
comma-delimited set of snowflakes
Optional list of SKU IDs to check entitlements for
before?
snowflake
Retrieve entitlements before this entitlement ID
after?
snowflake
Retrieve entitlements after this entitlement ID
limit?
number
Number of entitlements to return, 1-100, default 100
guild_id?
snowflake
Guild ID to look up entitlements for
exclude_ended?
boolean
Whether or not ended entitlements should be omitted
await mapih . discord . applications . entitlements . retrieve ( {
user_id : '0000000000' ,
before : '0000000000' ,
after : '0000000000' ,
limit : 2
} )
• Creates a test entitlement to a given SKU for a given guild or user. Discord will act as though that user or guild has entitlement to your premium offering.
• This endpoint returns a partial entitlement object. It will not contain subscription_id
, starts_at
, or ends_at
, as it's valid in perpetuity.
• After creating a test entitlement, you'll need to reload your Discord client. After doing so, you'll see that your server or user now has premium access.
Field
Type
Description
application_id?
snowflake
the id of the application
sku_id
string
ID of the SKU to grant the entitlement to
owner_id
string
ID of the guild or user to grant the entitlement to
owner_type
number
1
for a guild subscription, 2
for a user subscription
await mapih . discord . applications . entitlements . create ( {
sku_id : '0000000000' ,
owner_id : '0000000000' ,
owner_type : 1
} )
• Deletes a currently-active test entitlement. Discord will act as though that user or guild no longer has entitlement to your premium offering.
Field
Type
Description
application_id?
snowflake
the id of the application
await mapih . discord . applications . entitlements . delete ( )
Method
Description
getAll
Get all SKUs for a given application
• Because of how our SKU and subscription systems work, you will see two SKUs for your premium offering. For integration and testing entitlements, you should use the SKU with type: 5
.
Field
Type
Description
application_id?
snowflake
the id of the application
await mapih . discord . applications . SKUs . getAll ( ) ;
Method
Description
retrieve
Get the audit logs for the guild
The returned list of audit log entries is ordered based on whether you use before
or after
.
When using before
, the list is ordered by the audit log entry ID descending (newer entries first).
If after
is used, the list is reversed and appears in ascending order (older entries first).
Omitting both before
and after
defaults to before
the current timestamp and will show the most recent entries in descending order by ID, the opposite can be achieved using after=0
(showing oldest entries).
Field
Type
Description
guild_id
snowflake
the id of the application
user_id?
snowflake
Entries from a specific user ID
action_type?
number
Entries for a specific audit log event
before?
snowflake
Entries with ID less than a specific audit log entry ID
after?
snowflake
Entries with ID greater than a specific audit log entry ID
limit?
number
Maximum number of entries (between 1-100) to return, defaults to 50
await mapih . discord . auditlog . retrieve ( {
guild_id : '0000000000' ,
user_id : '0000000000' ,
limit : 10 // default 50
} ) ;
Field
Type
Description
guild_id
snowflake
the id of the guild
auto_moderation_rule_id
snowflake
the id of the automod rule
await mapih . discord . automod . retrieveRule ( {
auto_moderation_rule_id : '0000000000' ,
guild_id : '0000000000'
} )
Field
Type
Description
guild_id
snowflake
the id of the guild
await mapih . discord . automod . getAll ( {
guild_id : '0000000000'
} )
Field
Type
Description
guild_id
snowflake
the id of the guild
name
string
the rule name
event_type
integer
the event type
trigger_type
integer
the trigger type
trigger_metadata? *
object
the trigger metadata
actions
array of action objects
the actions which will execute when the rule is triggered
enabled?
boolean
whether the rule is enabled (False by default)
exempt_roles?
array of snowflakes
the role ids that should not be affected by the rule (Max 20)
exempt_channels?
array of snowflakes
the channel ids that should not be affected by the rule (Max 50)
await mapih . discord . automod . createRule ( {
guild_id : '0000000000' ,
name : 'EricsAutoModRule' ,
event_type : 1 // MESSAGE_SEND
trigger_type : 3 // SPAM
actions : [ {
type : 2 , // SEND_ALERT_MESSAGE
metadata : { channel_id : '0000000000' }
} ] ,
enabled : true ,
exempt_roles : [ '0000000000' ] ,
exempt_channels : [ '0000000000' ]
} )
Field
Type
Description
guild_id
snowflake
the id of the guild
name
string
the rule name
event_type
integer
the event type
trigger_metadata? *
object
the trigger metadata
actions
array of action objects
the actions which will execute when the rule is triggered
enabled?
boolean
whether the rule is enabled (False by default)
exempt_roles?
array of snowflakes
the role ids that should not be affected by the rule (Max 20)
exempt_channels?
array of snowflakes
the channel ids that should not be affected by the rule (Max 50)
await mapih . discord . automod . updateRule ( {
guild_id : '0000000000' ,
auto_moderation_rule_id : '00000' ,
name : 'EricsAutoModRule' ,
event_type : 1 // MESSAGE_SEND
actions : [ {
type : 1 , // BLOCK_MESSAGE
metadata : { custom_message : 'GO AWAY' }
} ] ,
trigger_metadata : {
keyword_filter : [ 'cat*' , '*dog' ] ,
regex_patterns : [ '^(?:[0-9]{1,3}\\.){3}[0-9]{1,3}$' ]
} ,
enabled : true
} )
Field
Type
Description
guild_id
snowflake
the id of the guild
auto_moderation_rule_id
snowflake
the id of the automod rule
await mapih . discord . automod . destroyRule ( {
auto_moderation_rule_id : '0000000000' ,
guild_id : '0000000000'
} )
A Stage Instance holds information about a live stage.
Method
Description
retrieve
Gets the stage instance associated with the Stage channel
create
Creates a new Stage instance associated to a Stage channel
update
Updates fields of an existing Stage instance
destroy
Deletes the Stage instance
Field
Type
Description
channel_id
snowflake
the id of the channel that the stage instance is in
await mapih . discord . stageInstance . retrieve ( {
channel_id : '0000000000'
} ) ;
Field
Type
Description
channel_id
snowflake
The id of the Stage channel
topic
string
The topic of the Stage instance (1-120 characters)
privacy_level?
integer
The privacy level of the Stage instance (default GUILD_ONLY)
send_start_notification? *
boolean
Notify @everyone that a Stage instance has started
guild_scheduled_event_id?
snowflake
The guild scheduled event associated with this Stage instance
* The stage moderator must have the MENTION_EVERYONE
permission for this notification to be sent.
await mapih . discord . stageInstance . create ( {
channel_id : '0000000000' ,
topic : 'My super cool stage' ,
send_start_notification : true
} ) ;
Field
Type
Description
channel_id
snowflake
The id of the Stage channel
topic?
string
The topic of the Stage instance (1-120 characters)
privacy_level?
integer
The privacy level of the Stage instance (default GUILD_ONLY)
await mapih . discord . stageInstance . update ( {
channel_id : '0000000000' ,
topic : 'My super duper cool stage' ,
} ) ;
Field
Type
Description
channel_id
snowflake
the id of the channel that the stage instance is in
await mapih . discord . stageInstance . destroy ( {
channel_id : '0000000000'
} ) ;
Method
Description
create
Creat a chat completion
Field
Type
Description
model
string
ID of the model to use
messages
ChatCompletionMessage []
A list of messages comprising the conversation so far
max_tokens?
number
The maximum number of tokens that can be generated in the chat completion
temperature?
number
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
top_p?
number
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
frequency_penalty?
number
Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
presence_penalty?
number
Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
n?
number
How many chat completion choices to generate for each input message
response_format?
string
An object specifying the format that the model must output. Setting to { "type": "json_object" } enables JSON mode, which guarantees the message the model generates is valid JSON.
seed?
number
This feature is in Beta. If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result.
stop?
string
Up to 4 sequences where the API will stop generating further tokens
logit_bias?
Object
Modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100.
logprobs?
boolean
Whether to return log probabilities of the output tokens or not
top_logprobs?
number
An integer between 0 and 5 specifying the number of most likely tokens to return at each token position, each with an associated log probability
stream?
boolean
If set, partial message deltas will be sent, like in ChatGPT.
tools?
ToolCalls []
A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for.
tool_choice?
ToolChoice
Controls which (if any) function is called by the model. See tool_choice
user?
string
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse
await mapih . openai . chat . create ( {
model : 'gpt-4' ,
messages : [
{
role : 'system' ,
content : 'You are a chatbot'
} ,
{
role : 'user' ,
content : 'hello!'
}
] ,
max_tokens : 1024 ,
temperature : 0.7
} ) ;
Many of the Spotify endpoints are designed for the input of a specific Spotify ID.
However, I have also incorporated the functionality to accept names.
Each endpoint includes options for both the ID* and the name**.
Utilizing a specific ID ensures the retrieval of the correct item.
On the other hand, providing a name might result in incorrect items depending on the uniqueness of the name.
* song_id(s)
, artist_id(s)
, album_id(s)
, playlist_id(s)
** song_name(s)
, artist_name(s)
, album_name(s)
, playlist_name(s)
Method
Description
me
Get detailed profile information about the current user
topItems
Get the current user's top artists or tracks
getProfile
Get public profile information about a Spotify user
await mapih . spotify . users . me ( ) ;
Field
Type
Description
type
string
The type of entity to return (artists
or tracks
)
time_range? *
string
Over what time frame the affinities are computed (default medium_term
)
limit?
number
The maximum number of results to return
offset?
number
The index of the first result to return. Use with limit to get the next page of search results.
* Valid values for time_range
:
long_term
: calculated from several years of data and including all new data as it becomes available
medium_term
: approximately last 6 months
short_term
: approximately last 4 weeks
await mapih . spotify . users . topItems ( {
type : 'tracks' ,
time_range : 'long_term' ,
limit : 10
} ) ;
Field
Type
Description
user_id
string
The user's Spotify user ID
await mapih . spotify . users . getProfile ( {
user_id : 'smedjan'
} ) ;
Method
Description
advanced
Extensive search for songs, artists, albums
artists
Search for artists
songs
Search for songs
albums
Search for albums
Field
Type
Description
song? *
string
Song name to search for
artist? *
string
Artist name to search for
album? *
string
Album name to search for
include?
string[]
Type of results to include. One or more of songs
, artists
, albums
.
limit?
number
The maximum number of results to return
offset?
number
The index of the first result to return. Use with limit to get the next page of search results.
sort?
string
Sort results by: popularity
, followers
, or duration_seconds
year?
string
Filter on a single year or a range (e.g. 1955-1960)
genre?
string
Filter on a single genre
* At least one of song
, artist
, album
is required.
await mapih . spotify . search . advanced ( {
song : 'oops i did it again' ,
year : '1990-1995' ,
limit : 1
} ) ;
await mapih . spotify . search . advanced ( {
song : 'some popular song name' ,
limit : 10 ,
sort : 'popularity'
} ) ;
await mapih . spotify . search . advanced ( {
album : 'your favorite album name' ,
include : [ 'albums' ] ,
} ) ;
Field
Type
Description
artist
string
Artist name to search for
limit?
number
The maximum number of results to return
offset?
number
The index of the first result to return. Use with limit to get the next page of search results.
sort?
string
Sort results by: popularity
or followers
await mapih . spotify . search . artists ( 'artist name' ) ;
await mapih . spotify . search . artists ( 'artist name' , {
limit : 10 ,
sort : 'popularity'
} ) ;
Field
Type
Description
song
string
Song name to search for
limit?
number
The maximum number of results to return
offset?
number
The index of the first result to return. Use with limit to get the next page of search results.
sort?
string
Sort results by: popularity
, followers
, or duration_seconds
await mapih . spotify . search . songs ( 'song name' ) ;
await mapih . spotify . search . songs ( 'song name' , {
limit : 10 ,
sort : 'popularity'
} ) ;
Method
Description
retrieve
Get Spotify catalog information for a single song
retrieveMany
Get Spotify catalog information for multiple songs
recommendations
Get song recommendations
save
Save one or more songs to the current user's 'Your Music' library
unsave
Remove one or more songs from the current user's 'Your Music' library
saved
Get a list of the songs saved in the current Spotify user's 'Your Music' library
isSaved
Check if one or more tracks is already saved in the current Spotify user's 'Your Music' library
analyze
Get a low-level audio analysis for a song in the Spotify catalog
audioFeatures
Get audio feature information for a single song
audioFeaturesMany
Get audio feature information for multiple songs
Field
Type
Description
song_id?
string
The id of the song to retrieve
song_name?
string
The name of the song to search for
await mapih . spotify . songs . retrieve ( {
song_name : 'Satellites'
// song_id: '4B9El4lQqztivDlRUCxbZB''
} ) ;
Field
Type
Description
song_ids?
string[]
The ids of the songs to retrieve
song_names?
string[]
The names of the songs to search for
sort?
string
Sort results by: popularity
, followers
, or duration_seconds
await mapih . spotify . songs . retrieveMany ( {
song_names : [ 'song 1' , 'song 2' ] ,
// song_ids: ['id 1', 'id 2']
} ) ;
Field
Type
Description
songs? *
string
Song name to search for
artists? *
string
Artist name to search for
genres?
string
Genres to include
limit?
number
The maximum number of results to return
min_acousticness?
number
max_acousticness?
number
target_acousticness?
number
min_danceability?
number
max_danceability?
number
target_danceability?
number
min_duration_ms?
number
max_duration_ms?
number
target_duration_ms?
number
min_energy?
number
target_energy?
number
min_instrumentalness?
number
max_instrumentalness?
number
target_instrumentalness?
number
min_key?
number
max_key?
number
target_key?
number
min_liveness?
number
max_livenessc?
number
target_liveness?
number
min_loudness?
number
max_loudness?
number
target_loudness?
number
min_mode?
number
max_mode?
number
target_mode?
number
min_popularity?
number
max_popularity?
number
target_popularity?
number
min_speechiness?
number
max_speechiness?
number
target_speechiness?
number
min_tempo?
number
max_tempo?
number
target_tempo?
number
min_time_signature?
number
max_time_signature?
number
target_time_signature?
number
min_valence?
number
max_valence?
number
target_valence?
number
await mapih . spotify . songs . recommendations ( {
artists : [ 'artist name' , 'another name' ] ,
songs : [ 'song name' ] ,
limit : 5 ,
min_duration_ms : 5000
} ) ;
Field
Type
Description
song_names?
string[]
Song names to search and save to your library
song_ids?
string[]
Song IDs of songs to save to your library
await mapih . spotify . songs . save ( {
song_names : [
'song name' ,
'another song name'
]
// song_ids: ['id 1', 'id 2']
} ) ;
Field
Type
Description
song_names?
string[]
Song names to search and remove from your library
song_ids?
string[]
Song IDs of songs to remove from your library
await mapih . spotify . songs . unsave ( {
song_names : [
'song name' ,
'another song name'
]
// song_ids: ['id 1', 'id 2']
} ) ;
Field
Type
Description
limit?
number
The maximum number of results to return
offset?
number
The index of the first result to return. Use with limit to get the next page of search results.
sort?
string
Sort results by: popularity
, followers
, or duration_seconds
await mapih . spotify . songs . saved ( ) ;
Field
Type
Description
song_names?
string[]
Song names to search and check if user follows
song_ids?
string[]
Song IDs of songs to check if user follows
await mapih . spotify . songs . isSaved ( {
song_names : [
'song name' ,
'another song name'
]
// song_ids: ['id 1', 'id 2']
} ) ;
Field
Type
Description
song_name?
string
Song name to search and analyze
song_id?
string
Song ID of song to analyze
await mapih . spotify . songs . analyze ( {
song_name : 'song name'
// song_id: 'id 1'
} ) ;
Field
Type
Description
song_name?
string
Song name to search and retrieve features for
song_id?
string
Song ID of song to retrieve features for
await mapih . spotify . songs . audioFeatures ( {
song_name : 'song name'
// song_id: 'id 1'
} ) ;
Field
Type
Description
song_names?
string[]
Song names to search and retrieve features for
song_ids?
string[]
Song IDs of songs to retrieve features for
await mapih . spotify . songs . audioFeaturesMany ( {
song_names : [
'song name' ,
'another song name'
]
// song_ids: ['id 1', 'id 2']
} ) ;
Method
Description
retrieve
Get Spotify catalog information for a single artist
retrieveMany
Get Spotify catalog information for multiple artists
topSongs
Get Spotify catalog information about an artist's top songs
albums
Get Spotify catalog information about an artist's albums
related
Get Spotify catalog information about artists similar to a given artist
follow
Add the current user as a follower of one or more artists or other Spotify users
unfollow
Remove the current user as a follower of one or more artists or other Spotify users
following
Get the current user's followed artists
isFollowing
Check to see if the current user is following one or more artists or other Spotify users
Field
Type
Description
artist_id?
string
The id of the song to retrieve
artist_name?
string
The name of the song to search for
await mapih . spotify . artists . retrieve ( {
artist_name : 'artist name'
// artist_id: '0uZ8zQLHru4BiNTL2PQY91'
} ) ;
Field
Type
Description
artist_ids?
string[]
The ids of the artists to retrieve
artist_names?
string[]
The names of the artists to search for
sort?
string
Sort results by: popularity
or followers
await mapih . spotify . artists . retrieveMany ( {
artist_names : [ 'artist 1' , 'artist 2' ] ,
// artists_ids: ['id 1', 'id 2']
} ) ;
Field
Type
Description
artist_id?
string
The id of the artist to retrieve top songs for
artist_name?
string
The name of the artist to search for
limit?
number
The maximum number of results to return
await mapih . spotify . artists . topSongs ( {
artist_name : 'artist name' ,
// artists_id: 'artist id',
limit : 5
} ) ;
Field
Type
Description
artist_id?
string
The id of the artist to retrieve albums for
artist_name?
string
The name of the artist to search for
limit?
number
The maximum number of results to return
offset?
number
The index of the first result to return. Use with limit to get the next page of search results.
include_groups? *
string[]
One or more keywords that will be used to filter the response
* Valid values: album
, single
, appears_on
, compilation
await mapih . spotify . artists . albums ( {
artist_name : 'artist name' ,
// artists_id: 'artist id',
limit : 5 ,
include_groups : [ 'single' , 'appears_on' ]
} ) ;
Field
Type
Description
artist_id?
string
The id of the artist to get related artists for
artist_name?
string
The name of the artist to search for
await mapih . spotify . artists . related ( {
artist_name : 'artist name' ,
// artists_id: 'artist id',
} ) ;
Field
Type
Description
artist_ids?
string[]
The ids of the artists or users to follow
artist_names?
string[]
The names of the artists or users to search for and follow
type?
string
Either artist
or user
(default artist
)
await mapih . spotify . artists . follow ( {
type : 'artist' ,
artist_names : [
'artist name' ,
'another artist name'
]
// artist_ids: ['id 1', 'id 2']
} ) ;
Field
Type
Description
artist_ids?
string[]
The ids of the artists or users to unfollow
artist_names?
string[]
The names of the artists or users to search for and unfollow
type?
string
Either artist
or user
(default artist
)
await mapih . spotify . artists . unfollow ( {
type : 'artist' ,
artist_names : [
'artist name' ,
'another artist name'
]
// artist_ids: ['id 1', 'id 2']
} ) ;
Field
Type
Description
after?
string
The last artist ID retrieved from the previous request
limit?
number
The maximum number of results to return (default 20)
sort?
string
Sort results by: popularity
or followers
await mapih . spotify . artists . following ( ) ;
Field
Type
Description
artist_ids?
string[]
The ids of the artists or users to unfollow
artist_names?
string[]
The names of the artists or users to search for and unfollow
type?
string
Either artist
or user
(default artist
)
await mapih . spotify . artists . isFollowing ( {
type : 'artist' ,
artist_names : [
'artist name' ,
'another artist name'
]
// artist_ids: ['id 1', 'id 2']
} ) ;
Method
Description
retrieve
Get Spotify catalog information for a single album
retrieveMany
Get Spotify catalog information for multiple albums
songs
Get Spotify catalog information about an album’s tracks
new
Get a list of new album releases featured in Spotify
save
Save one or more albums to the current user's 'Your Music' library
unsave
Remove one or more albums from the current user's 'Your Music' library
saved
Get a list of the albums saved in the current Spotify user's 'Your Music' library
isSaved
Check if one or more albums is already saved in the current Spotify user's 'Your Music' library
Field
Type
Description
album_id?
string
The id of the album to retrieve
album_name?
string
The name of the album to search for
await mapih . spotify . albums . retrieve ( {
album_name : 'album name'
// album_id: '0uZ8zQLHru4BiNTL2PQY91'
} ) ;
Field
Type
Description
album_ids?
string[]
The ids of the albums to retrieve
album_names?
string[]
The names of the albums to search for
sort?
string
Sort results by: popularity
, or followers
await mapih . spotify . albums . retrieveMany ( {
album_names : [ 'album 1' , 'album 2' ] ,
// album_ids: ['id 1', 'id 2']
} ) ;
Field
Type
Description
album_id?
string
The id of the album to retrieve
album_name?
string
The name of the album to search for
limit?
number
The maximum number of results to return
offset?
number
The index of the first result to return. Use with limit to get the next page of search results.
await mapih . spotify . albums . songs ( {
album_name : 'album name'
// album_id: '0uZ8zQLHru4BiNTL2PQY91'
} ) ;
Field
Type
Description
limit?
number
The maximum number of results to return
offset?
number
The index of the first result to return. Use with limit to get the next page of search results.
await mapih . spotify . albums . new ( ) ;
await mapih . spotify . albums . new ( {
limit : 5
} ) ;
Field
Type
Description
album_names?
string[]
Album names to search and save to your library
album_ids?
string[]
Album IDs of songs to save to your library
await mapih . spotify . albums . save ( {
album_names : [
'album name' ,
'another album name'
]
// album_ids: ['id 1', 'id 2']
} ) ;
Field
Type
Description
album_names?
string[]
Album names to search and remove from your library
album_ids?
string[]
Album IDs of albums to remove from your library
await mapih . spotify . albums . unsave ( {
album_names : [
'album name' ,
'another album name'
]
// album_ids: ['id 1', 'id 2']
} ) ;
Field
Type
Description
limit?
number
The maximum number of results to return
offset?
number
The index of the first result to return. Use with limit to get the next page of search results.
sort?
string
Sort results by: popularity
or followers
await mapih . spotify . albums . saved ( ) ;
Field
Type
Description
album_names?
string[]
Album names to search and check if user follows
album_ids?
string[]
Album IDs of albums to check if user follows
await mapih . spotify . albums . isSaved ( {
album_names : [
'album name' ,
'another album name'
]
// album_ids: ['id 1', 'id 2']
} ) ;
Method
Description
featured
Get a list of Spotify featured playlists
category
Get a list of Spotify playlists tagged with a particular category
create
Create a playlist for a Spotify user
update
Change a playlist's name and public/private state
addSongs
Add one or more items to a user's playlist
updateSongs
Either reorder or replace items in a playlist depending on the request's parameters
removeSongs
Remove one or more items from a user's playlist
retrieveSongs
Get full details of the items of a playlist owned by a Spotify user
created
Get a list of Spotify playlists that the user has created
following
Get a list of the playlists owned or followed by the current Spotify user
user
Get a list of the playlists owned or followed by a Spotify user
isFollowing
Check to see if one or more Spotify users are following a specified playlist
follow
Add the current user as a follower of a playlist
unfollow
Remove the current user as a follower of a playlist
getCover
Get the current image associated with a specific playlist
updateCover
Replace the image used to represent a specific playlist
Field
Type
Description
limit?
number
The maximum number of results to return
offset?
number
The index of the first result to return. Use with limit to get the next page of search results.
await mapih . spotify . playlists . featured ( ) ;
await mapih . spotify . playlists . featured ( {
limit : 5
} ) ;
Field
Type
Description
category
string
The category to get playlists for
limit?
number
The maximum number of results to return
offset?
number
The index of the first result to return. Use with limit to get the next page of search results.
await mapih . spotify . playlists . featured ( 'party' ) ;
await mapih . spotify . playlists . featured ( 'party' , {
limit : 5
} ) ;
Field
Type
Description
name
string
The name for the new playlist
description?
string
The description for the new playlist
public?
boolean
Whether or not the playlist should be public
collaborative?
boolean
Whether or not the playlist should be collaborative
await mapih . spotify . playlists . create ( {
name : 'My new playlist' ,
public : false
} ) ;
Field
Type
Description
playlist_id
string
The Spotify ID of the playlist
name?
string
The name for the new playlist
description?
string
The description for the new playlist
public?
boolean
Whether or not the playlist should be public
collaborative?
boolean
Whether or not the playlist should be collaborative
await mapih . spotify . playlists . update ( {
playlist_id : '3cEYpjA9oz9GiPac4AsH4n' ,
name : 'My new old playlist' ,
public : true
} ) ;
Field
Type
Description
playlist_id
string
The Spotify ID of the playlist
uris?
string[]
An array of Spotify URIs to add
position?
number
The position to insert the items, a zero-based index
await mapih . spotify . playlists . addSongs ( {
playlist_id : '3cEYpjA9oz9GiPac4AsH4n' ,
uris : [
'4iV5W9uYEdYUVa79Axb7Rh' ,
'1301WleyT98MSxVHPZCA6M'
]
} ) ;
Field
Type
Description
playlist_id
string
The Spotify ID of the playlist
uris?
string[]
An array of Spotify URIs to add
range_start?
number
The position of the first item to be reordered
range_length?
number
The amount of items to be reordered
insert_before?
number
The position where the items should be inserted
snapshot_id?
string
The playlist's snapshot ID against which you want to make the changes
await mapih . spotify . playlists . updateSongs ( {
playlist_id : '3cEYpjA9oz9GiPac4AsH4n' ,
uris : [
'4iV5W9uYEdYUVa79Axb7Rh' ,
'1301WleyT98MSxVHPZCA6M'
]
} ) ;
Field
Type
Description
playlist_id
string
The Spotify ID of the playlist
uris?
string[]
An array of Spotify URIs to remove
snapshot_id?
string
The playlist's snapshot ID against which you want to make the changes
await mapih . spotify . playlists . removeSongs ( {
playlist_id : '3cEYpjA9oz9GiPac4AsH4n' ,
uris : [
'4iV5W9uYEdYUVa79Axb7Rh' ,
'1301WleyT98MSxVHPZCA6M'
]
} ) ;
Field
Type
Description
playlist_id
string
The Spotify ID of the playlist
fields?
any[]
Filters for the query
limit?
number
The maximum number of results to return
offset?
number
The index of the first result to return. Use with limit to get the next page of search results.
// Get just the `name` and `description`
await mapih . spotify . playlists . retrieveSongs ( {
playlist_id : '3cEYpjA9oz9GiPac4AsH4n' ,
fields : [ 'name' , 'description' ]
} ) ;
// Get just the `added_at` field of the track
await mapih . spotify . playlists . retrieveSongs ( {
playlist_id : '3cEYpjA9oz9GiPac4AsH4n' ,
fields : {
tracks : {
items : [ 'added_at' ]
}
}
} ) ;
// Get the `name` and `id` of the track and the `name` and `artists` of the album that the track is on
await mapih . spotify . playlists . retrieveSongs ( {
playlist_id : '3cEYpjA9oz9GiPac4AsH4n' ,
fields : {
tracks : {
items : [ {
track : [ 'name' , 'id' , {
album : [ 'name' , 'artists' ]
} ]
} ]
}
}
} ) ;
This will only return playlists created by the current user.
Field
Type
Description
limit?
boolean
The maximum number of items to return (default 20, max 50)
offset?
boolean
The index of the first playlist to return
await mapih . spotify . playlists . created ( ) ;
await mapih . spotify . playlists . created ( {
limit : 5
} ) ;
This will return all playlists the current user follows.
Field
Type
Description
limit?
boolean
The maximum number of items to return (default 20, max 50)
offset?
boolean
The index of the first playlist to return
await mapih . spotify . playlists . following ( ) ;
await mapih . spotify . playlists . following ( {
limit : 5
} ) ;
This will return all playlists a specific user follows
Field
Type
Description
user_id
string
The user's Spotify user ID
limit?
boolean
The maximum number of items to return (default 20, max 50)
offset?
boolean
The index of the first playlist to return
await mapih . spotify . playlists . following ( {
user_id : 'smedjan' ,
limit : 5
} ) ;
Field
Type
Description
playlist_id
string
The Spotify ID of the playlist
user_ids
string[]
The user_ids of the users that you want to check to see if they follow the playlist
await mapih . spotify . playlists . isFollowing ( {
playlist_id : '3cEYpjA9oz9GiPac4AsH4n' ,
user_ids : [
'smedjan' ,
'jmperezperez'
]
} ) ;
Field
Type
Description
playlist_id
string
The Spotify ID of the playlist
public?
boolean
Whether the playlist will be included in user's public playlists (default true)
await mapih . spotify . playlists . follow ( {
playlist_id : '3cEYpjA9oz9GiPac4AsH4n' ,
public : false
} ) ;
Field
Type
Description
playlist_id
string
The Spotify ID of the playlist
await mapih . spotify . playlists . unfollow ( {
playlist_id : '3cEYpjA9oz9GiPac4AsH4n'
} ) ;
Field
Type
Description
playlist_id
string
The Spotify ID of the playlist
await mapih . spotify . playlists . getCover ( {
playlist_id : '3cEYpjA9oz9GiPac4AsH4n'
} ) ;
Field
Type
Description
playlist_id
string
The Spotify ID of the playlist
image
string
Base64 encoded JPEG image data
await mapih . spotify . playlists . updateCover ( {
playlist_id : '3cEYpjA9oz9GiPac4AsH4n' ,
image : 'image data'
} ) ;
Method
Description
state
Get information about the user’s current playback state
currentSong
Get the object currently being played on the user's Spotify account
devices
Get information about a user’s available Spotify Connect devices
togglePlayback
Start a new context or resume current playback on the user's active device
pause
Pause playback on the user's account
skip
Skips to next track in the user’s queue
previous
Skips to previous track in the user’s queue
seek
Seeks to the given position in the user’s currently playing track
setVolume
Set the volume for the user’s current playback device
toggleShuffle
Toggle shuffle on or off for user’s playback
toggleRepeat
Set the repeat mode for the user's playback
queue
Get the list of objects that make up the user's queue
addToQueue
Add an item to the end of the user's current playback queue
recent
Get tracks from the current user's recently played tracks
transfer
Transfer playback to a new device and optionally begin playback
await mapih . spotify . playback . state ( ) ;
await mapih . spotify . playback . currentSong ( ) ;
await mapih . spotify . playback . devices ( ) ;
Field
Type
Description
song_ids?
string[]
Array of Spotify track IDs to play
context_uri?
string
Spotify URI of the context to play. Valid contexts are albums, artists & playlists.
await mapih . spotify . playback . togglePlayback ( ) ;
await mapih . spotify . playback . togglePlayback ( {
song_ids : [ '1301WleyT98MSxVHPZCA6M' ]
} )
await mapih . spotify . playback . togglePlayback ( {
context_uri : 'spotify:album:1Je1IMUlBXcx1Fz0WE7oPT'
} )
await mapih . spotify . playback . pause ( ) ;
await mapih . spotify . playback . skip ( ) ;
await mapih . spotify . playback . previos ( ) ;
Field
Type
Description
position_ms
number
The position in milliseconds to seek to
await mapih . spotify . playback . seek ( {
position_ms : 25000
} ) ;
Field
Type
Description
volume_percent
number
The volume to set (0-100)
await mapih . spotify . playback . setVolume ( {
volume_percent : 100
} ) ;
* This endpoint takes a boolean (true
to turn shuffle on, false
to turn shuffle off)
await mapih . spotify . playback . toggleShuffle ( true ) ;
* This endpoint takes a string with the mode to set
Valid values:
track
: will repeat the current track
context
: will repeat the current context (album, playlist)
off
: will turn repeat off
await mapih . spotify . playback . toggleRepeat ( 'track' ) ;
await mapih . spotify . playback . queue ( ) ;
Field
Type
Description
song_id
string
The Spotify ID of the song to add to the queue
await mapih . spotify . playback . addToQueue ( {
song_id : '4iV5W9uYEdYUVa79Axb7Rh'
} ) ;
await mapih . spotify . playback . recent ( ) ;
Field
Type
Description
device_id
string
The Spotify ID of the song to add to the queue
play?
boolean
Whether playback starts on new device or if current state is kept
await mapih . spotify . playback . transfer ( {
device_id : '74ASZWbe4lXaubB36ztrGX' ,
play : 'false'
} ) ;
Simple key/value persistent storage
Method
Description
set
Creates an entry with a set value
setMany
Creates multiple entries at a time
get
Retrieves the value of a stored key
getMany
Retrieves a key-value pair of multiple entries
delete
Deletes an entry
deleteMany
Deletes multiple entries at a time
merge
Merge object into an existing value's object
push
Push values into an existing value's array
export
Export storage with mapped keys to values
filter
Filter storage with given predicate
all
Retrieve all stored items
has
Checks if storage has a specified key
entries
Get storage's entries
keys
Get storage's keys
values
Get storage's values
size
Get the amount of entries in storage
bytes
Get the total size (in bytes) of storage
keys
Export storage as a JSON string
clear
Clear all entries from storage
equals
Check if specified key's value equals specified value
history
Retrieve a keys previous values with timestamps
clearHistory
Clear one or all entries in a key's history
Field
Type
Description
key
string
The key to assign a value
value
any
The value to assign to a key
tts?
number
Amount of time in ms that this value will be stored
ttlCb?
function
A function to invoke upon expiration
allow_overwrite?
boolean
Whether to allow this key's value to be overwritten
await mapih . utils . storage . set ( {
key : 'password' ,
value : 'abcd1234'
} ) ;
await mapih . utils . storage . set ( {
key : 'password' ,
value : 'abcd1234' ,
ttl : 5000 , // 5 seconds
ttlCb : ( ) => console . log ( 'password expired' )
} ) ;
await mapih . utils . storage . set ( {
key : 'password' ,
value : 'abcd1234' ,
allow_overwrite : false
} ) ;
await mapih . utils . storage . set ( {
key : 'password' ,
value : 'newvalue' ,
} ) ; //=> error
Field
Type
Description
key
string
The key to retrieve the value for
value
any
The value to assign to a key
await mapih . utils . storage . setMany ( {
keyname1 : 'value1' ,
keyname2 : 'value2' ,
keyname3 : 'value3'
} )
Field
Type
Description
key
string
The key to assign the value
default?
boolean
Default value to assign a key if an entry doesn't exist
delete?
boolean
Whether to delete this entry after retrieving the value
await mapih . utils . storage . get ( 'password' ) ; //=> 'abcd1234'
// Set default value if value doesn't exist
await mapih . utils . storage . get ( 'password' , {
default : 'defaultValue'
} ) ; //=> 'defaultValue'
// Delete entry after retrieving the value
await mapih . utils . storage . get ( 'password' , {
delete : true
} ) ; //=> 'defaultValue'
await mapih . utils . storage . get ( 'password' ) ; //=> null
Field
Type
Description
keys
Array of strings
An array of keys to retrieve values for
await mapih . utils . storage . getMany ( [ 'password' , 'password2' , 'password3' ] )
//=> { password: 'abc123', password2: '123abc', password3: undefined }
Field
Type
Description
key
string
The key of the entry to delete
await mapih . utils . storage . delete ( 'password' ) ;
Field
Type
Description
keys
Array of strings
An array of keys to delete the entries for
await mapih . utils . storage . deleteMany ( [ 'password' , 'password2' , 'password3' ] )
//=> [true, true, false]
Field
Type
Description
key
string
The key of the entry to alter
value
Object
The properties to merge into existing object
* Value must be an object
await mapih . utils . storage . set ( {
key : 'example' ,
value : { a : 'b' }
} ) ;
await mapih . utils . storage . merge ( 'example' , { c : 'd' } ) ;
//=> new value: { a: 'b', c: 'd' }
await mapih . utils . storage . merge ( 'example' , { a : 'z' } ) ;
//=> new value: { a: 'z', c: 'd' }
Field
Type
Description
key
string
The key of the entry to alter
value
...any
Comma delimited set of values to push into the existing array
await mapih . utils . storage . set ( {
key : 'array' ,
value : [ 1 , 2 ]
} ) ;
await mapih . utils . storage . push ( 'array' , 3 , 4 ) ;
//=> new value: [1, 2, 3, 4]
await mapih . utils . storage . push ( 'array' , [ 5 , 6 ] , 7 ) ;
//=> new value: [ 1, 2, [ 5, 6 ], 7 ]
// keep duplicates
await mapih . utils . storage . push ( 'array' , 1 , 7 ) ;
//=> new value: [ 1, 2, [ 5, 6 ], 7, 1, 7 ]
// filter out duplicates
await mapih . utils . storage . push ( 'array' , 1 , 7 , {
unique : true
} ) ;
//=> new value: [ 1, 2, [ 5, 6 ], 7 ]
mapih . utils . storage . export ( ) ;
//=> {"password": {"value": "abcd1234"}}
Field
Type
Description
predicate
Callback
The callback to invoke
mapih . utils . storage . filter ( ( x ) => x . key . includes ( 'ass' ) ) ;
//=> [{ key: 'password', value: 'abc123' }]
mapih . utils . storage . all ( ) ;
//=>
// [
// { key: 'array', value: [ 1, 2, [Array], 7 ] },
// { key: 'password', value: 'abc123' }
// ]
Field
Type
Description
key
string
The key to check
mapih . utils . storage . has ( 'password' ) ;
mapih . utils . storage . entries ( ) ;
//=> [ [ 'password', 'abcd1234' ], [ 'test', '4321dcba' ] ]
mapih . utils . storage . keys ( ) ;
//=> ['password', 'stuff']
mapih . utils . storage . keys ( ) ;
//=> ['password', 'stuff']
mapih . utils . storage . size ( ) ; // 3
mapih . utils . storage . bytes ( ) ; // 23235 (bytes)
mapih . utils . storage . toJson ( ) ;
//=> [{"key":"array","value":[1,2,[5,6],7]},{"key":"password","value":"abc123"}]
await mapih . utils . storage . clear ( ) ; // undefined
Field
Type
Description
key
string
The key of the entry to check the value for
value
any
The value to compare
mapih . utils . storage . equals ( 'password' , 'abcd1234' ) ; // true
Field
Type
Description
key
string
The key of the entry to get the history of
mapih . utils . storage . history ( 'password' ) ;
//=>
// [
// { value: 'abcd1234', timestamp: 1703037628164 },
// { value: '4321dcba', timestamp: 1703037861827 },
// { value: '1234abcd', timestamp: 1703037890201 },
// ]
Field
Type
Description
key?
string
The key of the entry to delete, optional
// Clear history for a specific key
mapih . utils . storage . clearHistory ( 'password' ) ;
// Clear all entries in history
mapih . utils . storage . clearHistory ( ) ;
Discord Objects and Types
Field
Type
Description
id
snowflake
guild id
name
string
guild name (2-100 characters, excluding trailing and leading whitespace)
icon
?string
icon hash
icon_hash?
?string
icon hash, returned when in the template object
splash
?string
splash hash
discovery_splash
?string
discovery hash; Only present for guilds with the "DISCOVERABLE" feature
owner? *
boolean
true if the user is the owner of the guild
owner_id
snowflake
id of owner
permissions? *
string
total permissions for the user in the guild (excludes overwrites and implicit permissions)
afk_channel_id
?snowflake
id of afk channel
afk_timeout
integer
afk timeout in seconds
widget_enabled?
boolean
true if the server widget is enabled
widget_channel_id?
?snowflake
the channel id that the widget will generate an invite to, or null
if set to no invite
verification_level
integer
verification level required for the guild
default_message_notifications
integer
default message notifications level
explicit_content_filter
integer
explicit content filter level
roles
array of role objects
roles in the guild
emojis
array of emoji objects
custom guild emojis
features
array of guild feature strings
enabled guild features
mfa_level
integer
required MFA level for the guild
application_id
?snowflake
application id of the guild creator if it is bot-created
system_channel_id
?snowflake
the id of the channel where guild notices such as welcome messages and boost events are posted
system_channel_flags
integer
system channel flags
rules_channel_id
?snowflake
the id of the channel where Community guilds can display rules and/or guidelines
max_presences?
?integer
the maximum number of presences for the guild (null
is always returned, apart from the largest of guilds)
max_members?
integer
the maximum number of members for the guild
vanity_url_code
?string
the vanity url code for the guild
description
?string
the description of a guild
banner
?string
banner hash
premium_tier
integer
premium tier (Server Boost level)
premium_subscription_count?
integer
the number of boosts this guild currently has
preferred_locale
string
the preferred locale of a Community guild; used in server discovery and notices from Discord, and sent in interactions; defaults to "en-US"
public_updates_channel_id
?snowflake
the id of the channel where admins and moderators of Community guilds receive notices from Discord
max_video_channel_users?
integer
the maximum amount of users in a video channel
max_stage_video_channel_users?
integer
the maximum amount of users in a stage video channel
approximate_member_count?
integer
approximate number of members in this guild
approximate_presence_count?
integer
approximate number of non-offline members in this guild
welcome_screen?
welcome screen object
the welcome screen of a Community guild, shown to new members, returned in an Invite 's guild object
nsfw_level
integer
guild NSFW level
stickers?
array of sticker objects
custom guild stickers
premium_progress_bar_enabled
boolean
whether the guild has the boost progress bar enabled
safety_alerts_channel_id
?snowflake
the id of the channel where admins and moderators of Community guilds receive safety alerts from Discord
* These fields are only sent when using the GET Current User Guilds endpoint and are relative to the requested user
Default Message Notification Level
Key
Value
Description
All Messages
0
members will receive notifications for all messages by default
Only Mentions
1
members will receive notifications only for messages that @mention them by default
Explicit Content Filter Level
Level
Integer
Description
Disabled
0
media content will not be scanned
Members Without Roles
1
media content sent by members without roles will be scanned
All Members
2
media content sent by all members will be scanned
Level
Integer
Description
None
0
guild has no MFA/2FA requirement for moderation actions
Elevated
1
guild has a 2FA requirement for moderation actions
Level
Integer
Description
None
0
unrestricted
Low
1
must have verified email on account
Medium
2
must be registered on Discord for longer than 5 minutes
High
3
must be a member of the server for longer than 10 minutes
Very High
4
must have a verified phone number
Level
Value
Default
0
Explicit
1
Safe
2
Age Restricted
3
Level
Integer
Description
None
0
guild has not unlocked any Server Boost perks
Tier 1
1
guild has unlocked Server Boost level 1 perks
Tier 2
2
guild has unlocked Server Boost level 2 perks
Tier 3
3
guild has unlocked Server Boost level 3 perks
Flag
Value
Description
Suppress Join Notifications
1 << 0
Suppress member join notifications
Suppress Premium Subscriptions
1 << 1
Suppress server boost notifications
Suppress Guild Reminder Notifications
1 << 2
Suppress server setup tips
Suppress Join Notification Replies
1 << 3
Hide member join sticker reply buttons
Suppress Role Subscription Purchase Notifications
1 << 4
Suppress role subscription purchase and renewal notifications
Suppress Role Subscription Purchase Notification Replies
1 << 5
Hide role subscription sticker reply buttons
Feature -
Description
Animated Banner
guild has access to set an animated guild banner image
Animated Icon
guild has access to set an animated guild icon
Application Command Permissions V2
guild is using the old permissions configuration behavior
Auto Moderation
guild has set up auto moderation rules
Banner
guild has access to set a guild banner image
Community
guild can enable welcome screen, screening, stage channels, discovery, and receive community updates
Creator Monetizable Provisional
guild has enabled monetization
Creator Store Page
guild has enabled the role subscription promo page
Developer Support Server
guild has been set as a support server on the App Directory
Discoverable
guild is able to be discovered in the directory
Featurable
guild is able to be featured in the directory
Invites Disabled
guild has paused invites, preventing new users from joining
Invite Splash
guild has access to set an invite splash background
Member Verification Gate Enabled
guild has enabled Membership Screening
More Stickers
guild has increased custom sticker slots
News
guild has access to create announcement channels
Partnered
guild is partnered
Preview Enabled
guild can be previewed before joining via Membership Screening or the directory
Raid Alerts Disabled
guild has disabled alerts for join raids in the configured safety alerts channel
Role Icons
guild is able to set role icons
Role Subscriptions Available For Purchase
guild has role subscriptions that can be purchased
Role Subscriptions Enabled
guild has enabled role subscriptions
Ticketed Events Enabled
guild has enabled ticketed events
Vanity Url
guild has access to set a vanity URL
Verified
guild is verified
Vip Regions
guild has access to set 384kbps bitrate in voice (previously VIP voice servers)
Welcome Screen Enabled
guild has enabled the welcome screen
Features
Required Permissions
Effects
Community
Administrator
Enables Community Features in the guild
Discoverable
Administrator*
Enables discovery in the guild, making it publicly listed
Invites Disabled
Manage Guild
Pauses all invites/access to the server
Raid Alerts Disabled
Manage Guild
Disables alerts for join raids
Field
Type
Description
id
snowflake
guild id
name
string
guild name (2-100 characters)
icon
?string
icon hash
splash
?string
splash hash
discovery_splash
?string
discovery splash hash
emojis
array of emoji objects
custom guild emojis
features
array of guild feature strings
enabled guild features
approximate_member_count
number
approximate number of members in this guild
approximate_presence_count
number
approximate number of online members in this guild
description
?string
the description for the guild
stickers
array of sticker objects
custom guild stickers
Guild Widget Settings Structure
Field
Type
Description
enabled
boolean
whether the widget is enabled
channel_id
?snowflake
the widget channel id
Field
Type
Description
id
snowflake
guild id
name
string
guild name (2-100 characters)
instant_invite
?string
instant invite for the guilds specified widget invite channel
channels
array of partial channel objects
voice and stage channels which are accessible by @everyone
members
array of partial user objects
special widget user objects that includes users presence (Limit 100)
presence_count
number
number of online members in this guild
Field
Type
Description
user?
user object
the user this guild member represents
nick?
?string
this user's guild nickname
avatar?
?string
the member's guild avatar hash
roles
array of snowflakes
array of role object ids
joined_at
ISO8601 timestamp
when the user joined the guild
premium_since?
?ISO8601 timestamp
when the user started boosting the guild
deaf
boolean
whether the user is deafened in voice channels
mute
boolean
whether the user is muted in voice channels
flags
number
guild member flags represented as a bit set, defaults to 0
pending?
boolean
whether the user has passed the guild's Membership Screening requirements
permissions?
string
total permissions of the member in the channel, including overwrites, returned when in the interaction object
communication_disabled_until?
?ISO8601 timestamp
when the user's timeout will expire and the user will be able to communicate in the guild again
• The field user
won't be included in the member object attached to MESSAGE_CREATE
and MESSAGE_UPDATE
gateway events.
• In GUILD_
events, pending
will always be included as true or false. In non GUILD_
events which can only be triggered by non-pending
users, pending
will not be included.
Flag
Value
Description
Editable
Did Rejoin
1 << 0
Member has left and rejoined the guild
false
Completed Onboarding
1 << 1
Member has completed onboarding
false
Bypasses Verification
1 << 2
Member is exempt from guild verification requirements
true
Started Onboarding
1 << 3
Member has started onboarding
false
• BYPASSES_VERIFICATION allows a member who does not meet verification requirements to participate in a server.
Guild Scheduled Event Object
Field
Type
Description
id
snowflake
The ID of the scheduled event
guild_id
snowflake
The guild ID to which the scheduled event belongs
channel_id
?snowflake
The channel ID where the scheduled event will be hosted, or null
if the scheduled entity type is EXTERNAL
creator_id? *
?snowflake
The ID of the user who created the scheduled event
name
string
The name of the scheduled event (1-100 characters)
description?
?string
The description of the scheduled event (1-1000 characters)
scheduled_start_time
ISO8601 timestamp
The time the scheduled event will start
scheduled_end_time
?ISO8601 timestamp
The time the scheduled event will end, required if the entity type is EXTERNAL
privacy_level
privacy level
The privacy level of the scheduled event
status
event status
The status of the scheduled event
entity_type
scheduled entity type
The type of the scheduled event
entity_id
?snowflake
The ID of an entity associated with a guild scheduled event
entity_metadata
?entity metadata
Additional metadata for the guild scheduled event
creator?
user object
The user who created the scheduled event
user_count?
number
The number of users subscribed to the scheduled event
image?
?string
The cover image hash of the scheduled event
* creator_id
will be null and creator
will not be included for events created before October 25th, 2021, when the concept of creator_id
was introduced and tracked.
Guild Scheduled Event Privacy Level
Level
Value
Description
Guild Only
2
the scheduled event is only accessible to guild members
Guild Scheduled Event Entity Types
Type
Value
Stage Instance
1
Voice
2
External
3
Field Requirements By Entity Type
• The following table shows field requirements based on current entity type.
value
: This field is required to be a non-null value
null
: This field is required to be null
-
: No strict requirements
Entity Type
channel_id
entity_metadata
scheduled_end_time
Stage Instance
value
null
-
Voice
value
null
-
External
null
value *
value
* entity_metadata
with a non-null location
must be provided
Guild Scheduled Event Status
Type
Value
Scheduled
1
Active
2
Completed*
3
Canceled*
4
* Once status
is set to COMPLETED
or CANCELED
, the status
can no longer be updated
Valid Guild Scheduled Event Status Transitions
SCHEDULED --> ACTIVE
ACTIVE --------> COMPLETED
SCHEDULED --> CANCELED
Guild Scheduled Event Entity Metadata
Field
Type
Description
location?*
string
location of the event (1-100 characters)
* required for events with 'entity_type': EXTERNAL
Guild Scheduled Event User Object
Field
Type
Description
guild_scheduled_event_id
snowflake
the scheduled event id which the user subscribed to
user
user
user which subscribed to an event
member?
guild member
guild member data for this user for the guild which this event belongs to, if any
Field
Type
Description
code
string
the template code (unique ID)
name
string
template name
description
?string
the description for the template
usage_count
number
number of times this template has been used
creator_id
snowflake
the ID of the user who created the template
creator
user object
the user who created the template
created_at
ISO8601 timestamp
when this template was created
updated_at
ISO8601 timestamp
when this template was last synced to the source guild
source_guild_id
snowflake
the ID of the guild this template is based on
serialized_source_guild
partial guild object
the guild snapshot this template contains
is_dirty
?boolean
whether the template has unsynced changes
Example Guild Template Object
{
"code" : " hgM48av5Q69A" ,
"name" : " Friends & Family" ,
"description" : " " ,
"usage_count" : 49605 ,
"creator_id" : " 132837293881950208" ,
"creator" : {
"id" : " 132837293881950208" ,
"username" : " hoges" ,
"avatar" : " 79b0d9f8c340f2d43e1f78b09f175b62" ,
"discriminator" : " 0001" ,
"public_flags" : 129
},
"created_at" : " 2020-04-02T21:10:38+00:00" ,
"updated_at" : " 2020-05-01T17:57:38+00:00" ,
"source_guild_id" : " 678070694164299796" ,
"serialized_source_guild" : {
"name" : " Friends & Family" ,
"description" : null ,
"region" : " us-west" ,
"verification_level" : 0 ,
"default_message_notifications" : 0 ,
"explicit_content_filter" : 0 ,
"preferred_locale" : " en-US" ,
"afk_timeout" : 300 ,
"roles" : [
{
"id" : 0 ,
"name" : " @everyone" ,
"permissions" : 104324689 ,
"color" : 0 ,
"hoist" : false ,
"mentionable" : false
}
],
"channels" : [
{
"name" : " Text Channels" ,
"position" : 1 ,
"topic" : null ,
"bitrate" : 64000 ,
"user_limit" : 0 ,
"nsfw" : false ,
"rate_limit_per_user" : 0 ,
"parent_id" : null ,
"permission_overwrites" : [],
"id" : 1 ,
"type" : 4
},
{
"name" : " general" ,
"position" : 1 ,
"topic" : null ,
"bitrate" : 64000 ,
"user_limit" : 0 ,
"nsfw" : false ,
"rate_limit_per_user" : 0 ,
"parent_id" : 1 ,
"permission_overwrites" : [],
"id" : 2 ,
"type" : 0
}
],
"afk_channel_id" : null ,
"system_channel_id" : 2 ,
"system_channel_flags" : 0 ,
"icon_hash" : null
},
"is_dirty" : null
}
Field
Type
Description
id
snowflake
integration id
name
string
integration name
type
string
integration type (twitch, youtube, discord, or guild_subscription)
enabled
boolean
is this integration enabled
syncing?
boolean
is this integration syncing
role_id?
snowflake
id that this integration uses for "subscribers"
enable_emoticons?
boolean
whether emoticons should be synced for this integration (twitch only)
expire_behavior?
integration expire behavior
the behavior of expiring subscribers
expire_grace_period?
number
the grace period (in days) before expiring subscribers
user?
user object
user for this integration
account
account object
integration account information
synced_at?
ISO8601 timestamp
when this integration was last synced
subscriber_count?
number
how many subscribers this integration has
revoked?
boolean
has this integration been revoked
application?
application object
The bot/OAuth2 application for discord integrations
scopes?
array of OAuth2 scopes
the scopes the application has been authorized for
Integration Expire Behaviors
Value
Name
0
Remove role
1
Kick
Integration Account Object
Field
Type
Description
id
string
id of the account
name
string
name of the account
Integration Application Object
Field
Type
Description
id
snowflake
the id of the app
name
string
the name of the app
icon
?string
the icon hash of the app
description
string
the description of the app
bot?
user object
the bot associated with this application
Field
Type
Description
reason
?string
the reason for the ban
user
user object
the banned user
{
"reason" : " mentioning lostmyinfo" ,
"user" : {
"username" : " goodsie" ,
"id" : " 53908099506183680" ,
"avatar" : " a_bab14f271d565501444b2ca3be944b25" ,
"public_flags" : 131141
}
}
Field
Type
Description
description
?string
the server description shown in the welcome screen
welcome_channels
array of welcome screen channel objects
the channels shown in the welcome screen, up to 5
Welcome Screen Channel Object
Field
Type
Description
channel_id
snowflake
the channel's id
description
string
the description shown for the channel
emoji_id
?snowflake
the emoji id, if the emoji is custom
emoji_name
?string
the emoji name if custom, the unicode character if standard, or null
if no emoji is set
Field
Type
Description
guild_id
snowflake
ID of the guild this onboarding is part of
prompts
array of onboarding prompt objects
Prompts shown during onboarding and in customize community
default_channel_ids
array of snowflakes
Channel IDs that members get opted into automatically
enabled
boolean
Whether onboarding is enabled in the guild
mode
onboarding mode
Current mode of onboarding
Onboarding Prompt Structure
Field
Type
Description
id
snowflake
ID of the prompt
type
prompt type
Type of prompt
options
array of prompt option objects
Options available within the prompt
title
string
Title of the prompt
single_select
boolean
Indicates whether users are limited to selecting one option for the prompt
required
boolean
Indicates whether the prompt is required before a user completes onboarding flow
in_onboarding
boolean
Indicates whether the prompt is present in the onboarding flow. If false
, the prompt will only appear in the Channels & Roles tab
Field
Type
Description
id
snowflake
ID of the prompt option
channel_ids
array of snowflakes
IDs for channels a member is added to when the option is selected
role_ids
array of snowflakes
IDs for roles assigned to a member when the option is selected
emoji?
emoji object
Emoji of the option (see below)
emoji_id?
snowflake
Emoji ID of the option (see below)
emoji_name?
string
Emoji name of the option (see below)
emoji_animated?
boolean
Whether the emoji is animated (see below)
title
string
Title of the option
description
?string
Description of the option
• When creating or updating a prompt option, the emoji_id
, emoji_name
, and emoji_animated
fields must be used instead of the emoji object.
• Defines the criteria used to satisfy Onboarding constraints that are required for enabling.
Name
Value
Description
Onboarding Default
0
Counts only Default Channels towards constraints
Onboarding Advanced
1
Counts Default Channels and Questions towards constraints
Name
Value
Multiple Choice
0
Dropdown
1
{
"guild_id" : " 960007075288915998" ,
"prompts" : [
{
"id" : " 1067461047608422473" ,
"title" : " What do you want to do in this community?" ,
"options" : [
{
"id" : " 1067461047608422476" ,
"title" : " Chat with Friends" ,
"description" : " " ,
"emoji" : {
"id" : " 1070002302032826408" ,
"name" : " chat" ,
"animated" : false
},
"role_ids" : [],
"channel_ids" : [
" 962007075288916001"
]
},
{
"id" : " 1070004843541954678" ,
"title" : " Get Gud" ,
"description" : " We have excellent teachers!" ,
"emoji" : {
"id" : null ,
"name" : " 😀" ,
"animated" : false
},
"role_ids" : [
" 982014491980083211"
],
"channel_ids" : []
}
],
"single_select" : false ,
"required" : false ,
"in_onboarding" : true ,
"type" : 0
}
],
"default_channel_ids" : [
" 998678771706110023" ,
" 998678693058719784" ,
" 1070008122577518632" ,
" 998678764340912138" ,
" 998678704446263309" ,
" 998678683592171602" ,
" 998678699715067986"
],
"enabled" : true
}
Field
Type
Description
id
snowflake
the user's id
username
string
the user's username, not unique across the platform
discriminator
string
the user's Discord-tag
global_name
?string
the user's display name, if it is set. For bots, this is the application name
avatar
?string
the user's avatar hash
bot?
boolean
whether the user belongs to an OAuth2 application
system?
boolean
whether the user is an Official Discord System user (part of the urgent message system)
mfa_enabled?
boolean
whether the user has two factor enabled on their account
banner?
?string
the user's banner hash
accent_color?
?integer
the user's banner color encoded as an integer representation of hexadecimal color code
locale?
string
the user's chosen language option
verified?
boolean
whether the email on this account has been verified
email?
?string
the user's email
flags?
integer
the flags on a user's account
premium_type?
integer
the type of Nitro subscription on a user's account
public_flags?
integer
the public flags on a user's account
avatar_decoration?
?string
the user's avatar decoration hash
Value
Name
Description
1 << 0
Staff
Discord Employee
1 << 1
Partner
Partnered Server Owner
1 << 2
Hypesquad
HypeSquad Events Member
1 << 3
Bug Hunter Level 1
Bug Hunter Level 1
1 << 6
Hypesquad Online House 1
House Bravery Member
1 << 7
Hypesquad Online House 2
House Brilliance Member
1 << 8
Hypesquad Online House 3
House Balance Member
1 << 9
Premium Early Supporter
Early Nitro Supporter
1 << 10
Team Pseudo User
User is a team
1 << 14
Bug Hunter Level 2
Bug Hunter Level 2
1 << 16
Verified Bot
Verified Bot
1 << 17
Verified Developer
Early Verified Bot Developer
1 << 18
Certified Moderator
Moderator Programs Alumni
1 << 19
Bot Http Interactions
Bot uses only HTTP interactions and is shown in the online member list
1 << 22
Active Developer
User is an Active Developer
• Premium types denote the level of premium a user has.
Value
Name
0
None
1
Nitro Classic
2
Nitro
3
Nitro Basic
• The connection object that the user has attached.
Field
Type
Description
id
string
id of the connection account
name
string
the username of the connection account
type
string
the service of this connection
revoked?
boolean
whether the connection is revoked
integrations?
array
an array of partial server integrations
verified
boolean
whether the connection is verified
friend_sync
boolean
whether friend sync is enabled for this connection
show_activity
boolean
whether activities related to this connection will be shown in presence updates
two_way_link
boolean
whether this connection has a corresponding third party OAuth2 token
visibility
integer
visibility of this connection
Value
Name
battlenet
Battle.net
ebay
eBay
epicgames
Epic Games
facebook
Facebook
github
GitHub
instagram
Instagram
leagueoflegends
League of Legends
paypal
PayPal
playstation
PlayStation Network
reddit
Reddit
riotgames
Riot Games
spotify
Spotify
skype *
Skype
steam
Steam
tiktok
TikTok
twitch
Twitch
twitter
X (Twitter)
xbox
Xbox
youtube
YouTube
* Service can no longer be added by users
Value
Name
Description
0
None
invisible to everyone except the user themselves
1
Everyone
visible to everyone
Application Role Connection Object
The role connection object that an application has attached to a user.
Field
Type
Description
platform_name
?string
the vanity name of the platform a bot has connected (max 50 characters)
platform_username
?string
the username on the platform a bot has connected (max 100 characters)
metadata
object
object mapping application role connection metadata keys to their string
-ified value (max 100 characters) for the user on the platform a bot has connected
Application Role Connection Metadata Object
Field
Type
Description
type
ApplicationRoleConnectionMetadataType
type of metadata value
key
string
dictionary key for the metadata field (must be a-z
, 0-9
, or _
characters; 1-50 characters)
name
string
name of the metadata field (1-100 characters)
name_localizations?
dictionary with keys in available locales
translations of the name
description
string
description of the metadata field (1-200 characters)
description_localizations?
dictionary with keys in available locales
translations of the description
Application Role Connection Metadata Type
Type
Value
Description
INTEGER_LESS_THAN_OR_EQUAL
1
the metadata value (integer
) is less than or equal to the guild's configured value (integer
)
INTEGER_GREATER_THAN_OR_EQUAL
2
the metadata value (integer
) is greater than or equal to the guild's configured value (integer
)
INTEGER_EQUAL
3
the metadata value (integer
) is equal to the guild's configured value (integer
)
INTEGER_NOT_EQUAL
4
the metadata value (integer
) is not equal to the guild's configured value (integer
)
DATETIME_LESS_THAN_OR_EQUAL
5
the metadata value (ISO8601 string
) is less than or equal to the guild's configured value (integer
; days before current date
)
DATETIME_GREATER_THAN_OR_EQUAL
6
the metadata value (ISO8601 string
) is greater than or equal to the guild's configured value (integer
; days before current date
)
BOOLEAN_EQUAL
7
the metadata value (integer
) is equal to the guild's configured value (integer
; 1
)
BOOLEAN_NOT_EQUAL
8
the metadata value (integer
) is not equal to the guild's configured value (integer
; 1
)
Field
Type
Description
id
?snowflake
emoji id
name
?string (can be null only in reaction emoji objects)
emoji name
roles?
array of role object ids
roles allowed to use this emoji
user?
user object
user that created this emoji
require_colons?
boolean
whether this emoji must be wrapped in colons
managed?
boolean
whether this emoji is managed
animated?
boolean
whether this emoji is animated
available?
boolean
whether this emoji can be used, may be false due to loss of Server Boosts
{
"id" : " 41771983429993937" ,
"name" : " LUL" ,
"roles" : [" 41771983429993000" , " 41771983429993111" ],
"user" : {
"username" : " Luigi" ,
"discriminator" : " 0002" ,
"id" : " 96008815106887111" ,
"avatar" : " 5500909a3274e1812beb4e8de6631111" ,
"public_flags" : 131328
},
"require_colons" : true ,
"managed" : false ,
"animated" : false
}
{
"id" : null ,
"name" : " �"
}
{
"id" : " 41771983429993937" ,
"name" : " LUL" ,
"animated" : true
}
{
"id" : " 41771983429993937" ,
"name" : null
}
Field
Type
Description
id
snowflake
id of the sticker
pack_id?
snowflake
for standard stickers, id of the pack the sticker is from
name
string
name of the sticker
description
?string
description of the sticker
tags
string
autocomplete/suggestion tags for the sticker (max 200 characters)
type
number
type of sticker
format_type
number
type of sticker format
available?
boolean
whether this guild sticker can be used, may be false due to loss of Server Boosts
guild_id?
snowflake
id of the guild that owns this sticker
user?
user object
the user that uploaded the guild sticker
sort_value?
number
the standard sticker's sort order within its pack
Type
Value
Description
Standard
1
an official sticker in a pack
Guild
2
a sticker uploaded to a guild for the guild's members
Type
Value
PNG
1
APNG
2
LOTTIE
3
GIF
4
{
"id" : " 749054660769218631" ,
"name" : " Wave" ,
"tags" : " wumpus, hello, sup, hi, oi, heyo, heya, yo, greetings, greet, welcome, wave, :wave, :hello, :hi, :hey, hey, \ud83d\udc4b , \ud83d\udc4b\ud83c\udffb , \ud83d\udc4b\ud83c\udffc , \ud83d\udc4b\ud83c\udffd , \ud83d\udc4b\ud83c\udffe , \ud83d\udc4b\ud83c\udfff , goodbye, bye, see ya, later, laterz, cya" ,
"type" : 1 ,
"format_type" : 3 ,
"description" : " Wumpus waves hello" ,
"asset" : " " ,
"pack_id" : " 847199849233514549" ,
"sort_value" : 12
}
Field
Type
Description
id
snowflake
id of the sticker
name
string
name of the sticker
format_type
number
type of sticker format
Field
Type
Description
id
snowflake
id of the sticker pack
stickers
array of sticker objects
the stickers in the pack
name
string
name of the sticker pack
sku_id
snowflake
id of the pack's SKU
cover_sticker_id?
snowflake
id of a sticker in the pack which is shown as the pack's icon
description
string
description of the sticker pack
banner_asset_id?
snowflake
id of the sticker pack's banner image
{
"id" : " 847199849233514549" ,
"stickers" : [],
"name" : " Wumpus Beyond" ,
"sku_id" : " 847199849233514547" ,
"cover_sticker_id" : " 749053689419006003" ,
"description" : " Say hello to Wumpus!" ,
"banner_asset_id" : " 761773777976819732"
}
• Roles represent a set of permissions attached to a group of users.
• Roles have names, colors, and can be "pinned" to the side bar, causing their members to be listed separately. Roles can have separate permission profiles for the global context (guild) and channel context.
The @everyone
role has the same ID as the guild it belongs to.
Field
Type
Description
id
snowflake
role id
name
string
role name
color
integer
integer representation of hexadecimal color code
hoist
boolean
if this role is pinned in the user listing
icon?
?string
role icon hash
unicode_emoji?
?string
role unicode emoji
position
integer
position of this role
permissions
string
permission bit set
managed
boolean
whether this role is managed by an integration
mentionable
boolean
whether this role is mentionable
tags?
role tags object
the tags this role has
flags
integer
role flags combined as a bitfield
• Tags with type null
represent booleans.
• They will be present and set to null
if they are "true", and will be not present if they are "false".
Field
Type
Description
bot_id?
snowflake
the id of the bot this role belongs to
integration_id?
snowflake
the id of the integration this role belongs to
premium_subscriber?
null
whether this is the guild's Booster role
subscription_listing_id?
snowflake
the id of this role's subscription sku and listing
available_for_purchase?
null
whether this role is available for purchase
guild_connections?
null
whether this role is a guild's linked role
Flag
Value
Description
IN_PROMPT
1 << 0
role can be selected by members in an onboarding prompt
Field
Type
Description
id
snowflake
the id of this channel
type
integer
the type of channel
guild_id?
snowflake
the id of the guild (may be missing for some channel objects received over gateway guild dispatches)
position?
integer
sorting position of the channel
permission_overwrites?
array of overwrite objects
explicit permission overwrites for members and roles
name?
?string
the name of the channel (1-100 characters)
topic?
?string
the channel topic (0-4096 characters for GUILD_FORUM
and GUILD_MEDIA
channels, 0-1024 characters for all others)
nsfw?
boolean
whether the channel is nsfw
last_message_id?
?snowflake
the id of the last message sent in this channel (or thread for GUILD_FORUM
or GUILD_MEDIA
channels) (may not point to an existing or valid message or thread)
bitrate?
integer
the bitrate (in bits) of the voice channel
user_limit?
integer
the user limit of the voice channel
rate_limit_per_user?*
integer
amount of seconds a user has to wait before sending another message (0-21600); bots, as well as users with the permission manage_messages
or manage_channel
, are unaffected
recipients?
array of user objects
the recipients of the DM
icon?
?string
icon hash of the group DM
owner_id?
snowflake
id of the creator of the group DM or thread
application_id?
snowflake
application id of the group DM creator if it is bot-created
managed?
boolean
for group DM channels: whether the channel is managed by an application via the gdm.join
OAuth2 scope
parent_id?
?snowflake
for guild channels: id of the parent category for a channel (each parent category can contain up to 50 channels), for threads: id of the text channel this thread was created
last_pin_timestamp?
?ISO8601 timestamp
when the last pinned message was pinned. This may be null
in events such as GUILD_CREATE
when a message is not pinned.
rtc_region?
?string
voice region id for the voice channel, automatic when set to null
video_quality_mode?
integer
the camera video quality mode of the voice channel, 1 when not present
message_count?**
integer
number of messages (not including the initial message or deleted messages) in a thread.
member_count?
integer
an approximate count of users in a thread, stops counting at 50
thread_metadata?
thread metadata object
thread-specific fields not needed by other channels
member?
thread member object
thread member object for the current user, if they have joined the thread, only included on certain API endpoints
default_auto_archive_duration?
integer
default duration, copied onto newly created threads, in minutes, threads will stop showing in the channel list after the specified period of inactivity, can be set to: 60, 1440, 4320, 10080
permissions?
string
computed permissions for the invoking user in the channel, including overwrites, only included when part of the resolved
data received on a slash command interaction.
flags?
integer
channel flags combined as bitfield
total_message_sent?
integer
number of messages ever sent in a thread, it's similar to message_count
on message creation, but will not decrement the number when a message is deleted
available_tags?
array of tag objects
the set of tags that can be used in a GUILD_FORUM
or a GUILD_MEDIA
channel
applied_tags?
array of snowflakes
the IDs of the set of tags that have been applied to a thread in a GUILD_FORUM
or a GUILD_MEDIA
channel
default_reaction_emoji?
?default reaction object
the emoji to show in the add reaction button on a thread in a GUILD_FORUM
or a GUILD_MEDIA
channel
default_thread_rate_limit_per_user?
integer
the initial rate_limit_per_user
to set on newly created threads in a channel. this field is copied to the thread at creation time and does not live update.
default_sort_order?
?integer
the default sort order type used to order posts in GUILD_FORUM
and GUILD_MEDIA
channels. Defaults to null
, which indicates a preferred sort order hasn't been set by a channel admin
default_forum_layout?
integer
the default forum layout view used to display posts in GUILD_FORUM
channels. Defaults to 0
, which indicates a layout view has not been set by a channel admin
* rate_limit_per_user
also applies to thread creation. Users can send one message and create one thread during each rate_limit_per_user
interval.
** For threads created before July 1, 2022, the message count is inaccurate when it's greater than 50.
Type
ID
Description
Guild Text
0
a text channel within a server
Dm
1
a direct message between users
Guild Voice
2
a voice channel within a server
Group Dm
3
a direct message between multiple users
Guild Category
4
an organizational category that contains up to 50 channels
Guild Announcement
5
a channel that users can follow and crosspost into their own server (formerly news channels)
Announcement Thread
10
a temporary sub-channel within a GUILD_ANNOUNCEMENT channel
Public Thread
11
a temporary sub-channel within a GUILD_TEXT or GUILD_FORUM channel
Private Thread
12
a temporary sub-channel within a GUILD_TEXT channel that is only viewable by those invited and those with the MANAGE_THREADS permission
Guild Stage Voice
13
a voice channel for hosting events with an audience
Guild Directory
14
the channel in a hub containing the listed servers
Guild Forum
15
Channel that can only contain threads
Guild Media
16
Channel that can only contain threads, similar to GUILD_FORUM
channels
* The GUILD_MEDIA
channel type is still in active development. Avoid implementing any features that are not documented here, since they are subject to change without notice!
Field
Type
Description
id
snowflake
id of the channel
type
integer
the type of channel
name
string
the name of the channel
permissions
string
permission bit set
Mode
Value
Description
Auto
1
Discord chooses the quality for optimal performance
Full
2
720p
Flag
Value
Description
Pinned
1 << 1
this thread is pinned to the top of its parent GUILD_FORUM
or GUILD_MEDIA
channel
Require Tag
1 << 4
whether a tag is required to be specified when creating a thread in a GUILD_FORUM
or a GUILD_MEDIA
channel. Tags are specified in the applied_tags
field.
Hide Media Download Options
1 << 15
when set hides the embedded media download options. Available only for media channels
Flag
Value
Description
Latest Activity
0
Sort forum posts by activity
Creation Date
1
Sort forum posts by creation time (from most recent to oldest)
Flag
Value
Description
Not Set
0
No default has been set for forum channel
List View
1
Display posts as a list
Gallery View
2
Display posts as a collection of tiles
Example Guild Announcement Channel
{
"id" : " 41771983423143937" ,
"guild_id" : " 41771983423143937" ,
"name" : " important-news" ,
"type" : 5 ,
"position" : 6 ,
"permission_overwrites" : [],
"nsfw" : true ,
"topic" : " Rumors about Half Life 3" ,
"last_message_id" : " 155117677105512449" ,
"parent_id" : " 399942396007890945" ,
"default_auto_archive_duration" : 60
}
Example Guild Voice Channel
{
"id" : " 155101607195836416" ,
"last_message_id" : " 174629835082649376" ,
"type" : 2 ,
"name" : " ROCKET CHEESE" ,
"position" : 5 ,
"parent_id" : null ,
"bitrate" : 64000 ,
"user_limit" : 0 ,
"rtc_region" : null ,
"guild_id" : " 41771983423143937" ,
"permission_overwrites" : [],
"rate_limit_per_user" : 0 ,
"nsfw" : false ,
}
{
"last_message_id" : " 3343820033257021450" ,
"type" : 1 ,
"id" : " 319674150115610528" ,
"recipients" : [
{
"username" : " test" ,
"discriminator" : " 9999" ,
"id" : " 82198898841029460" ,
"avatar" : " 33ecab261d4681afa4d85a04691c4a01"
}
]
}
{
"name" : " Some test channel" ,
"icon" : null ,
"recipients" : [
{
"username" : " test" ,
"discriminator" : " 9999" ,
"id" : " 82198898841029460" ,
"avatar" : " 33ecab261d4681afa4d85a04691c4a01"
},
{
"username" : " test2" ,
"discriminator" : " 9999" ,
"id" : " 82198810841029460" ,
"avatar" : " 33ecab261d4681afa4d85a10691c4a01"
}
],
"last_message_id" : " 3343820033257021450" ,
"type" : 3 ,
"id" : " 319674150115710528" ,
"owner_id" : " 82198810841029460"
}
{
"permission_overwrites" : [],
"name" : " Test" ,
"parent_id" : null ,
"nsfw" : false ,
"position" : 0 ,
"guild_id" : " 290926798629997250" ,
"type" : 4 ,
"id" : " 399942396007890945"
}
{
"id" : " 41771983423143937" ,
"guild_id" : " 41771983423143937" ,
"parent_id" : " 41771983423143937" ,
"owner_id" : " 41771983423143937" ,
"name" : " don't buy dota-2" ,
"type" : 11 ,
"last_message_id" : " 155117677105512449" ,
"message_count" : 1 ,
"member_count" : 5 ,
"rate_limit_per_user" : 2 ,
"thread_metadata" : {
"archived" : false ,
"auto_archive_duration" : 1440 ,
"archive_timestamp" : " 2021-04-12T23:40:39.855793+00:00" ,
"locked" : false
},
"total_message_sent" : 1
}
Field
Type
Description
id
snowflake
id of the message
channel_id
snowflake
id of the channel the message was sent in
author*
user object
the author of this message
content**
string
contents of the message
timestamp
ISO8601 timestamp
when this message was sent
edited_timestamp
?ISO8601 timestamp
when this message was edited (or null if never)
tts
boolean
whether this was a TTS message
mention_everyone
boolean
whether this message mentions everyone
mentions
array of user objects
users specifically mentioned in the message
mention_roles
array of role object ids
roles specifically mentioned in this message
mention_channels?***
array of channel mention objects
channels specifically mentioned in this message
attachments**
array of attachment objects
any attached files
embeds**
array of embed objects
any embedded content
reactions?
array of reaction objects
reactions to the message
nonce?
integer or string
used for validating a message was sent
pinned
boolean
whether this message is pinned
webhook_id?
snowflake
if the message is generated by a webhook, this is the webhook's id
type
integer
type of message
activity?
message activity object
sent with Rich Presence-related chat embeds
application?
partial application object
sent with Rich Presence-related chat embeds
application_id?
snowflake
if the message is an Interaction or application-owned webhook, this is the id of the application
message_reference?
message reference object
data showing the source of a crosspost, channel follow add, pin, or reply message
flags?
integer
message flags combined as a bitfield
referenced_message?****
?message object
the message associated with the message_reference
interaction?
message interaction object
sent if the message is a response to an Interaction
thread?
channel object
the thread that was started from this message, includes thread member object
components?**
array of message components
sent if the message contains components like buttons, action rows, or other interactive components
sticker_items?
array of message sticker item objects
sent if the message contains stickers
position?
integer
A generally increasing integer (there may be gaps or duplicates) that represents the approximate position of the message in a thread, it can be used to estimate the relative position of the message in a thread in company with total_message_sent
on parent thread
role_subscription_data?
role subscription data object
data of the role subscription purchase or renewal that prompted this ROLE_SUBSCRIPTION_PURCHASE message
resolved?
resolved data
data for users, members, channels, and roles in the message's auto-populated select menus
* The author object follows the structure of the user object, but is only a valid user in the case where the message is generated by a user or bot user. If the message is generated by a webhook, the author object corresponds to the webhook's id, username, and avatar. You can tell if a message is generated by a webhook by checking for the webhook_id
on the message object.
** An app will receive empty values in the content
, embeds
, attachments
, and components
fields if they have not configured (or been approved for) the MESSAGE_CONTENT
privileged intent (1 << 15
).
*** Not all channel mentions in a message will appear in mention_channels
. Only textual channels that are visible to everyone in a lurkable guild will ever be included. Only crossposted messages (via Channel Following) currently include mention_channels
at all. If no mentions in the message meet these requirements, this field will not be sent.
**** This field is only returned for messages with a type
of 19
(REPLY) or 21
(THREAD_STARTER_MESSAGE). If the message is a reply but the referenced_message
field is not present, the backend did not attempt to fetch the message that was being replied to, so its state is unknown. If the field exists but is null, the referenced message was deleted.
Forum and Media Thread Message Params Object
Field
Type
Description
content?*
string
Message contents (up to 2000 characters)
embeds?*
array of embed objects
Up to 10 rich
embeds (up to 6000 characters)
allowed_mentions?
allowed mention object
Allowed mentions for the message
components?*
array of message component objects
Components to include with the message
sticker_ids?*
array of snowflakes
IDs of up to 3 stickers in the server to send in the message
attachments?
array of partial attachment objects
Attachment objects with filename
and description
flags?
integer
Message flags (only SUPPRESS_EMBEDS
and SUPPRESS_NOTIFICATIONS
can be set)
* At least one of content
, embeds
, sticker_ids
, components
, or files[n]
is required.
Type
Value
Deletable
Default
0
true
Recipient Add
1
false
Recipient Remove
2
false
Call
3
false
Channel Name Change
4
false
Channel Icon Change
5
false
Channel Pinned Message
6
true
User Join
7
true
Guild Boost
8
true
Guild Boost Tier 1
9
true
Guild Boost Tier 2
10
true
Guild Boost Tier 3
11
true
Channel Follow Add
12
true
Guild Discovery Disqualified
14
false
Guild Discovery Requalified
15
false
Guild Discovery Grace Period Initial Warning
16
false
Guild Discovery Grace Period Final Warning
17
false
Thread Created
18
true
Reply
19
true
Chat Input Command
20
true
Thread Starter Message
21
false
Guild Invite Reminder
22
true
Context Menu Command
23
true
Auto Moderation Action
24
true*
Role Subscription Purchase
25
true
Interaction Premium Upsell
26
true
Stage Start
27
true
Stage End
28
true
Stage Speaker
29
true
Stage Topic
31
true
Guild Application Premium Subscription
32
false
* Can only be deleted by members with MANAGE_MESSAGES
permission
Message Activity Structure
Type
Value
Join
1
Spectate
2
Listen
3
Join Request
5
Flag
Value
Description
Crossposted
1 << 0
this message has been published to subscribed channels (via Channel Following)
Is Crosspost
1 << 1
this message originated from a message in another channel (via Channel Following)
Suppress Embeds
1 << 2
do not include any embeds when serializing this message
Source Message Deleted
1 << 3
the source message for this crosspost has been deleted (via Channel Following)
Urgent
1 << 4
this message came from the urgent message system
Has Thread
1 << 5
this message has an associated thread, with the same id as the message
Ephemeral
1 << 6
this message is only visible to the user who invoked the Interaction
Loading
1 << 7
this message is an Interaction Response and the bot is "thinking"
Failed To Mention Some Roles In Thread
1 << 8
this message failed to mention some roles and add their members to the thread
Suppress Notifications
1 << 12
this message will not trigger push and desktop notifications
Is Voice Message
1 << 13
this message is a voice message
Field
Type
Description
message_id?
snowflake
id of the originating message
channel_id? *
snowflake
id of the originating message's channel
guild_id?
snowflake
id of the originating message's guild
fail_if_not_exists?
boolean
when sending, whether to error if the referenced message doesn't exist instead of sending as a normal (non-reply) message, default true
* channel_id
is optional when creating a reply, but will always be present when receiving an event/response that includes this data model.
Followed Channel Structure
Field
Type
Description
channel_id
snowflake
source channel id
webhook_id
snowflake
created target webhook id
Field
Type
Description
count
integer
Total number of times this emoji has been used to react (including super reacts)
count_details
object
Reaction count details object
me
boolean
Whether the current user reacted using this emoji
me_burst
boolean
Whether the current user super-reacted using this emoji
emoji
partial emoji object
emoji information
burst_colors
array
HEX colors used for super reaction
Reaction Count Details Object
Field
Type
Description
burst
integer
Count of super reactions
normal
integer
Count of normal reactions
Field
Type
Description
id
snowflake
role or user id
type
int
either 0 (role) or 1 (member)
allow
string
permission bit set
deny
string
permission bit set
Field
Type
Description
archived
boolean
whether the thread is archived
auto_archive_duration
integer
the thread will stop showing in the channel list after auto_archive_duration
minutes of inactivity, can be set to: 60, 1440, 4320, 10080
archive_timestamp
ISO8601 timestamp
timestamp when the thread's archive status was last changed, used for calculating recent activity
locked
boolean
whether the thread is locked; when a thread is locked, only users with MANAGE_THREADS can unarchive it
invitable?
boolean
whether non-moderators can add other non-moderators to a thread; only available on private threads
create_timestamp?
?ISO8601 timestamp
timestamp when the thread was created; only populated for threads created after 2022-01-09
Field
Type
Description
id? *
snowflake
ID of the thread
user_id? *
snowflake
ID of the user
join_timestamp
ISO8601 timestamp
Time the user last joined the thread
flags
integer
Any user-thread settings, currently only used for notifications
member? **
guild member object
Additional information about the user
* These fields are omitted on the member sent within each thread in the GUILD_CREATE event.
** The member
field is only present when with_member
is set to true
when calling List Thread Members or Get Thread Member .
Field
Type
Description
emoji_id
?snowflake
the id of a guild's custom emoji
emoji_name
?string
the unicode character of the emoji
Field
Type
Description
id
snowflake
the id of the tag
name
string
the name of the tag (0-20 characters)
moderated
boolean
whether this tag can only be added to or removed from threads by a member with the MANAGE_THREADS
permission
emoji_id
?snowflake
the id of a guild's custom emoji *
emoji_name
?string
the unicode character of the emoji *
* At most one of emoji_id
and emoji_name
may be set to a non-null value.
Field
Type
Description
title?
string
title of embed
type?
string
type of embed (always "rich" for webhook embeds)
description?
string
description of embed
url?
string
url of embed
timestamp?
ISO8601 timestamp
timestamp of embed content
color?
number
color code of the embed
footer?
embed footer object
footer information
image?
embed image object
image information
thumbnail?
embed thumbnail object
thumbnail information
video?
embed video object
video information
provider?
embed provider object
provider information
author?
embed author object
author information
fields?
array of embed field objects
fields information
Embed Thumbnail Structure
Field
Type
Description
url
string
source url of thumbnail (only supports http(s) and attachments)
proxy_url?
string
a proxied url of the thumbnail
height?
integer
height of thumbnail
width?
integer
width of thumbnail
Field
Type
Description
url?
string
source url of video
proxy_url?
string
a proxied url of the video
height?
integer
height of video
width?
integer
width of video
Field
Type
Description
url
string
source url of image (only supports http(s) and attachments)
proxy_url?
string
a proxied url of the image
height?
integer
height of image
width?
integer
width of image
Field
Type
Description
name?
string
name of provider
url?
string
url of provider
Field
Type
Description
name
string
name of author
url?
string
url of author (only supports http(s))
icon_url?
string
url of author icon (only supports http(s) and attachments)
proxy_icon_url?
string
a proxied url of author icon
Embed Footer Structure
Field
Type
Description
text
string
footer text
icon_url?
string
url of footer icon (only supports http(s) and attachments)
proxy_icon_url?
string
a proxied url of footer icon
Field
Type
Description
name
string
name of the field
value
string
value of the field
inline?
boolean
whether or not this field should display inline
• Additionally, the combined sum of characters in all title
, description
, field.name
, field.value
, footer.text
, and author.name
fields across all embeds attached to a message must not exceed 6000 characters.
• Violating any of these constraints will result in a Bad Request
response.
• Embeds are deduplicated by URL. If a message contains multiple embeds with the same URL, only the first is shown.
Field
Type
Description
id
snowflake
attachment id
filename
string
name of file attached
description?
string
description for the file (max 1024 characters)
content_type?
string
the attachment's media type
size
number
size of file in bytes
url
string
source url of file
proxy_url
string
a proxied url of file
height?
?number
height of file (if image)
width?
?number
width of file (if image)
ephemeral? *
boolean
whether this attachment is ephemeral
duration_secs?
float
the duration of the audio file (currently for voice messages)
waveform?
string
base64 encoded bytearray representing a sampled waveform (currently for voice messages)
flags?
number
attachment flags combined as a bitfield
* Ephemeral attachments will automatically be removed after a set period of time. Ephemeral attachments on messages are guaranteed to be available as long as the message itself exists.
Flag
Value
Description
Is Remix
1 << 2
this attachment has been edited using the remix feature on mobile
Field
Type
Description
id
snowflake
id of the channel
guild_id
snowflake
id of the guild containing the channel
type
integer
the type of channel
name
string
the name of the channel
Field
Type
Description
parse
array of allowed mention types
An array of allowed mention types to parse from the content.
roles
list of snowflakes
Array of role_ids to mention (Max size of 100)
users
list of snowflakes
Array of user_ids to mention (Max size of 100)
replied_user
boolean
For replies, whether to mention the author of the message being replied to (default false)
Type
Value
Description
Role Mentions
"roles"
Controls role mentions
User Mentions
"users"
Controls user mentions
Everyone Mentions
"everyone"
Controls @everyone and @here mentions
Allowed Mentions Reference
• If allowed_mentions
is not passed in (i.e. the key does not exist), the mentions will be parsed via the content. This corresponds with existing behavior.
In the example below we would ping @here (and also @role124 and @user123)
{
"content" : " @here Hi there from <@123>, cc <@&124>"
}
To suppress all mentions in a message use:
{
"content" : " @everyone hi there, <@&123>" ,
"allowed_mentions" : {
"parse" : []
}
}
This will suppress all mentions in the message (no @everyone or user mention).
• The parse
field is mutually exclusive with the other fields.
In the example below, we would ping users 123
and role 124
, but not @everyone.
Note that passing a Falsy
value ([], null) into the "users" field does not trigger a validation error.
{
"content" : " @everyone <@123> <@&124>" ,
"allowed_mentions" : {
"parse" : [" users" , " roles" ],
"users" : []
}
}
In the next example, we would ping @everyone, (and also users 123
and 124
if they suppressed @everyone mentions), but we would not ping any roles.
{
"content" : " @everyone <@123> <@124> <@125> <@&200>" ,
"allowed_mentions" : {
"parse" : [" everyone" ],
"users" : [" 123" , " 124" ]
}
}
Type
Name
Description
1
Action Row
Container for other components
2
Button
Button object
3
String Select
Select menu for picking from defined text options
4
Text Input
Text input object
5
User Select
Select menu for users
6
Role Select
Select menu for roles
7
Mentionable Select
Select menu for mentionables (users and roles)
8
Channel Select
Select menu for channels
Field
Type
Description
type
integer
2
for a button
style
integer
A button style
label?
string
Text that appears on the button; max 80 characters
emoji?
partial emoji
name
, id
, and animated
custom_id?
string
Developer-defined identifier for the button; max 100 characters
url?
string
URL for link-style buttons
disabled?
boolean
Whether the button is disabled (defaults to false
)
Name
Value
Color
Required Field
Primary
1
blurple
custom_id
Secondary
2
grey
custom_id
Success
3
green
custom_id
Danger
4
red
custom_id
Link
5
grey, navigates to a URL
url
Select Menu Object
Field
Type
Description
type
integer
Type of select menu component (text: 3
, user: 5
, role: 6
, mentionable: 7
, channels: 8
)
custom_id
string
ID for the select menu; max 100 characters
options?*
array of select options
Specified choices in a select menu (only required and available for string selects (type 3
)); max 25
channel_types?**
array of channel types
List of channel types to include in the channel select component (type 8
)
placeholder?
string
Placeholder text if nothing is selected; max 150 characters
default_values?***
array of default value objects
List of default values for auto-populated select menu components; number of default values must be in the range defined by min_values
and max_values
min_values?
integer
Minimum number of items that must be chosen (defaults to 1); min 0, max 25
max_values?
integer
Maximum number of items that can be chosen (defaults to 1); max 25
disabled?
boolean
Whether select menu is disabled (defaults to false
)
* options
is required for string select menus (component type 3
), and unavailable for all other select menu components.
** channel_types
can only be used for channel select menu components.
*** default_values
is only available for auto-populated select menu components, which include user (5
), role (6
), mentionable (7
), and channel (8
) components .
Field
Type
Description
label
string
User-facing name of the option; max 100 characters
value
string
Dev-defined value of the option; max 100 characters
description?
string
Additional description of the option; max 100 characters
emoji?
partial emoji object
id
, name
, and animated
default?
boolean
Will show this option as selected by default
Select Default Value Structure
Field
Type
Description
id
snowflake
ID of a user, role, or channel
type
string
Type of value that id
represents. Either "user"
, "role"
, or "channel"
Field
Type
Description
type
integer
4
for a text input
custom_id
string
Developer-defined identifier for the input; max 100 characters
style
integer
The Text Input Style
label
string
Label for this component; max 45 characters
min_length?
integer
Minimum input length for a text input; min 0, max 4000
max_length?
integer
Maximum input length for a text input; min 1, max 4000
required?
boolean
Whether this component is required to be filled (defaults to true
)
value?
string
Pre-filled value for this component; max 4000 characters
placeholder?
string
Custom placeholder text if the input is empty; max 100 characters
Name
Value
Description
Short
1
Single-line input
Paragraph
2
Multi-line input
Field
Type
Description
id
snowflake
the id of the webhook
type
integer
the type of the webhook
guild_id?
?snowflake
the guild id this webhook is for, if any
channel_id
?snowflake
the channel id this webhook is for, if any
user?
user object
the user this webhook was created by (not returned when getting a webhook by token)
name
?string
the default name of the webhook
avatar
?string
the default user avatar hash of the webhook
token?
string
the secure token of the webhook (returned for Incoming Webhooks)
application_id
?snowflake
the bot/OAuth2 application that created this webhook
source_guild? *
partial guild object
the guild of the channel that this webhook is following (returned for Channel Follower Webhooks)
source_channel? *
partial channel object
the channel that this webhook is following (returned for Channel Follower Webhooks)
url?
string
the url used for executing the webhook (returned by the webhooks OAuth2 flow)
* These fields will be absent if the webhook creator has since lost access to the guild where the followed channel resides
Value
Name
Description
1
Incoming
Incoming Webhooks can post messages to channels with a generated token
2
Channel Follower
Channel Follower Webhooks are internal webhooks used with Channel Following to post new messages into channels
3
Application
Application webhooks are webhooks used with Interactions
Field
Type
Description
id
snowflake
ID of the interaction
application_id
snowflake
ID of the application this interaction is for
type
interaction type
Type of interaction
data?*
interaction data
Interaction data payload
guild_id?
snowflake
Guild that the interaction was sent from
channel?
partial channel object
Channel that the interaction was sent from
channel_id?
snowflake
Channel that the interaction was sent from
member?**
guild member object
Guild member data for the invoking user, including permissions
user?
user object
User object for the invoking user, if invoked in a DM
token
string
Continuation token for responding to the interaction
version
integer
Read-only property, always 1
message?
message object
For components, the message they were attached to
app_permissions?
string
Bitwise set of permissions the app or bot has within the channel the interaction was sent from
locale?***
string
Selected language of the invoking user
guild_locale?
string
Guild's preferred locale , if invoked in a guild
entitlements
array of entitlement objects
For monetized apps, any entitlements for the invoking user, representing access to premium SKUs
* This is always present on application command, message component, and modal submit interaction types.
** member
is sent when the interaction is invoked in a guild, and user
is sent when invoked in a DM
*** This is available on all interaction types except PING
Name
Value
Ping
1
Application Command
2
Message Component
3
Application Command Autocomplete
4
Modal Submit
5
Application Command Data Structure
Field
Type
Description
id
snowflake
the ID
of the invoked command
name
string
the name
of the invoked command
type
integer
the type
of the invoked command
resolved?
resolved data
converted users + roles + channels + attachments
options?*
array of application command interaction data option
the params + values from the user
guild_id?
snowflake
the id of the guild the command is registered to
target_id?
snowflake
id of the user or message targeted by a user or message command
* This can be partial when in response to APPLICATION_COMMAND_AUTOCOMPLETE
Message Component Data Structure
* This is always present for select menu components
Modal Submit Data Structure
Field
Type
Description
custom_id
string
the custom_id
of the modal
components
array of message components
the values submitted by the user
Field
Type
Description
users?
Map of Snowflakes to user objects
the ids and User objects
members?*
Map of Snowflakes to partial member objects
the ids and partial Member objects
roles?
Map of Snowflakes to role objects
the ids and Role objects
channels?**
Map of Snowflakes to partial channel objects
the ids and partial Channel objects
messages?
Map of Snowflakes to partial messages objects
the ids and partial Message objects
attachments?
Map of Snowflakes to attachment objects
the ids and attachment objects
* Partial Member
objects are missing user
, deaf
and mute
fields
** Partial Channel
objects only have id
, name
, type
and permissions
fields. Threads will also have thread_metadata
and parent_id
fields.
Application Command Interaction Data Option Structure
Field
Type
Description
name
string
Name of the parameter
type
integer
Value of application command option type
value?
string, integer, double, or boolean
Value of the option resulting from user input
options?
array of application command interaction data option
Present if this option is a group or subcommand
focused?
boolean
true
if this option is the currently focused option for autocomplete
Message Interaction Structure
Field
Type
Description
id
snowflake
ID of the interaction
type
interaction type
Type of interaction
name
string
Name of the application command , including subcommands and subcommand groups
user
user object
User who invoked the interaction
member?
partial member object
Member who invoked the interaction in the guild
Interaction Response Structure
Interaction Callback Type
Name
Value
Description
Pong
1
ACK a Ping
Channel Message With Source
4
respond to an interaction with a message
Deferred Channel Message With Source
5
ACK an interaction and edit a response later, the user sees a loading state
Deferred Update Message*
6
for components, ACK an interaction and edit the original message later; the user does not see a loading state
Update Message*
7
for components, edit the message the component was attached to
Application Command Autocomplete Result
8
respond to an autocomplete interaction with suggested choices
Modal**
9
respond to an interaction with a popup modal
Premium Required***
10
respond to an interaction with an upgrade button, only available for apps with monetization enabled
* Only valid for component-based interactions.
** Not available for MODAL_SUBMIT
and PING
interactions.
*** Not available for APPLICATION_COMMAND_AUTOCOMPLETE
and PING
interactions.
Interaction Callback Data Structure
Field
Type
Description
tts?
boolean
is the response TTS
content?
string
message content
embeds?
array of embeds
supports up to 10 embeds
allowed_mentions?
allowed mentions
allowed mentions object
flags?
integer
message flags combined as a bitfield (only SUPPRESS_EMBEDS
and EPHEMERAL
can be set)
components?
array of components
message components
attachments? *
array of partial attachment objects
attachment objects with filename and description
Field
Type
Description
choices
array of choices
autocomplete choices (max of 25 choices)
Field
Type
Description
custom_id
string
a developer-defined identifier for the modal, max 100 characters
title
string
the title of the popup modal, max 45 characters
components
array of components
between 1 and 5 (inclusive) components that make up the modal
Field
Type
Description
code
string
the invite code (unique ID)
guild?
partial guild object
the guild this invite is for
channel
?partial channel object
the channel this invite is for
inviter?
user object
the user who created the invite
target_type?
number
the type of target for this voice channel invite
target_user?
user object
the user whose stream to display for this voice channel stream invite
target_application?
partial application object
the embedded application to open for this voice channel embedded application invite
approximate_presence_count?
number
approximate count of online members, when with_counts
is true
approximate_member_count?
number
approximate count of total members, when with_counts
is true
expires_at?
?ISO8601 timestamp
the expiration date of this invite, when with_expiration
is true
guild_scheduled_event?
guild scheduled event object
guild scheduled event data, only included if guild_scheduled_event_id
contains a valid guild scheduled event id
Type
Value
STREAM
1
EMBEDDED_APPLICATION
2
Field
Type
Description
uses
number
number of times this invite has been used
max_uses
number
max number of times this invite can be used
max_age
number
duration (in seconds) after which the invite expires
temporary
boolean
whether this invite only grants temporary membership
created_at
ISO8601 timestamp
when this invite was created
Field
Type
Description
id
snowflake
ID of the app
name
string
Name of the app
icon
?string
Icon hash of the app
description
string
Description of the app
rpc_origins?
array of strings
List of RPC origin URLs, if RPC is enabled
bot_public
boolean
When false
, only the app owner can add the app to guilds
bot_require_code_grant
boolean
When true
, the app's bot will only join upon completion of the full OAuth2 code grant flow
bot?
partial user object
Partial user object for the bot user associated with the app
terms_of_service_url?
string
URL of the app's Terms of Service
privacy_policy_url?
string
URL of the app's Privacy Policy
owner?
partial user object
Partial user object for the owner of the app
verify_key
string
Hex encoded key for verification in interactions and the GameSDK's GetTicket
team
?team object
If the app belongs to a team, this will be a list of the members of that team
guild_id?
snowflake
Guild associated with the app. For example, a developer support server.
guild?
partial guild object
Partial object of the associated guild
primary_sku_id?
snowflake
If this app is a game sold on Discord, this field will be the id of the "Game SKU" that is created, if exists
slug?
string
If this app is a game sold on Discord, this field will be the URL slug that links to the store page
cover_image?
string
App's default rich presence invite cover image hash
flags?
number
App's public flags
approximate_guild_count?
number
Approximate count of guilds the app has been added to
redirect_uris?
array of strings
Array of redirect URIs for the app
interactions_endpoint_url?
string
Interactions endpoint URL for the app
role_connections_verification_url?
string
Role connection verification URL for the app
tags?
array of strings
List of tags describing the content and functionality of the app. Max of 5 tags
install_params?
install params object
Settings for the app's default in-app authorization link, if enabled
custom_install_url?
string
Default custom authorization URL for the app, if enabled
Example Application Object
{
"bot_public" : true ,
"bot_require_code_grant" : false ,
"cover_image" : " 31deabb7e45b6c8ecfef77d2f99c81a5" ,
"description" : " Test" ,
"guild_id" : " 290926798626357260" ,
"icon" : null ,
"id" : " 172150183260323840" ,
"name" : " Baba O-Riley" ,
"owner" : {
"avatar" : null ,
"discriminator" : " 1738" ,
"flags" : 1024 ,
"id" : " 172150183260323840" ,
"username" : " i own a bot"
},
"primary_sku_id" : " 172150183260323840" ,
"slug" : " test" ,
"summary" : " " ,
"team" : {
"icon" : " dd9b7dcfdf5351b9c3de0fe167bacbe1" ,
"id" : " 531992624043786253" ,
"members" : [
{
"membership_state" : 2 ,
"permissions" : [" *" ],
"team_id" : " 531992624043786253" ,
"user" : {
"avatar" : " d9e261cd35999608eb7e3de1fae3688b" ,
"discriminator" : " 0001" ,
"id" : " 511972282709709995" ,
"username" : " Mr Owner"
}
}
]
},
"verify_key" : " 1e0a356058d627ca38a5c8c9648818061d49e49bd9da9e3ab17d98ad4d6bg2u8"
}
Value
Name
Description
1 << 6
Application Auto Moderation Rule Create Badge
Indicates if an app uses the Auto Moderation API
1 << 12
Gateway Presence
Intent required for bots in 100 or more servers to receive presence_update
events
1 << 13
Gateway Presence Limited
Intent required for bots in under 100 servers to receive presence_update
events, found on the Bot page in your app's settings
1 << 14
Gateway Guild Members
Intent required for bots in 100 or more servers to receive member-related events like guild_member_add
.
1 << 15
Gateway Guild Members Limited
Intent required for bots in under 100 servers to receive member-related events like guild_member_add
, found on the Bot page in your app's settings.
1 << 16
Verification Pending Guild Limit
Indicates unusual growth of an app that prevents verification
1 << 17
Embedded
Indicates if an app is embedded within the Discord client (currently unavailable publicly)
1 << 18
Gateway Message Content
Intent required for bots in 100 or more servers to receive message content
1 << 19
Gateway Message Content Limited
Intent required for bots in under 100 servers to receive message content, found on the Bot page in your app's settings
1 << 23
Application Command Badge
Indicates if an app has registered global application commands
Field
Type
Description
scopes
array of strings
Scopes to add the application to the server with
permissions
string
Permissions to request for the bot role
Name
Description
activities.read
allows your app to fetch data from a user's "Now Playing/Recently Played" list — not currently available for apps
activities.write
allows your app to update a user's activity - not currently available for apps (NOT REQUIRED FOR GAMESDK ACTIVITY MANAGER)
applications.builds.read
allows your app to read build data for a user's applications
applications.builds.upload
allows your app to upload/update builds for a user's applications - requires Discord approval
applications.commands
allows your app to add commands to a guild - included by default with the bot
scope
applications.commands.update
allows your app to update its commands using a Bearer token - client credentials grant only
applications.commands.permissions.update
allows your app to update permissions for its commands in a guild a user has permissions to
applications.entitlements
allows your app to read entitlements for a user's applications
applications.store.update
allows your app to read and update store data (SKUs, store listings, achievements, etc.) for a user's applications
bot
for oauth2 bots, this puts the bot in the user's selected guild by default
connections
allows /users/@me/connections to return linked third-party accounts
dm_channels.read
allows your app to see information about the user's DMs and group DMs - requires Discord approval
email
enables /users/@me to return an email
gdm.join
allows your app to join users to a group dm
guilds
allows /users/@me/guilds to return basic information about all of a user's guilds
guilds.join
allows /guilds/{guild.id}/members/{user.id} to be used for joining users to a guild
guilds.members.read
allows /users/@me/guilds/{guild.id}/member to return a user's member information in a guild
identify
allows /users/@me without email
messages.read
for local rpc server api access, this allows you to read messages from all client channels (otherwise restricted to channels/guilds your app creates)
relationships.read
allows your app to know a user's friends and implicit relationships - requires Discord approval
role_connections.write
allows your app to update a user's connection and metadata for the app
rpc
for local rpc server access, this allows you to control a user's local Discord client - requires Discord approval
rpc.activities.write
for local rpc server access, this allows you to update a user's activity - requires Discord approval
rpc.notifications.read
for local rpc server access, this allows you to receive notifications pushed out to the user - requires Discord approval
rpc.voice.read
for local rpc server access, this allows you to read a user's voice settings and listen for voice events - requires Discord approval
rpc.voice.write
for local rpc server access, this allows you to update a user's voice settings - requires Discord approval
voice
allows your app to connect to voice on user's behalf and see all the voice members - requires Discord approval
webhook.incoming
this generates a webhook that is returned in the oauth token response for authorization code grants
Application Command Object
Field
Type
Description
Valid Types
id
snowflake
Unique ID of command
all
type?
number
Type of command , defaults to 1
all
application_id
snowflake
ID of the parent application
all
guild_id?
snowflake
Guild ID of the command, if not global
all
name
string
Name of command, 1-32 characters
all
name_localizations?
?dictionary with keys in available locales
Localization dictionary for name
field. Values follow the same restrictions as name
all
description
string
Description for CHAT_INPUT
commands, 1-100 characters. Empty string for USER
and MESSAGE
commands
all
description_localizations?
?dictionary with keys in available locales
Localization dictionary for description
field. Values follow the same restrictions as description
all
options?
array of application command option
Parameters for the command, max of 25
CHAT_INPUT
default_member_permissions
?string
Set of permissions represented as a bit set
all
dm_permission?
boolean
Indicates whether the command is available in DMs with the app, only for globally-scoped commands
all
nsfw?
boolean
Indicates whether the command is age-restricted, defaults to false
all
version
snowflake
Autoincrementing version identifier updated during substantial record changes
all
Set default_member_permissions
to "0"
to disable the command for everyone except admins by default, and/or set dm_permission
to false
to disable globally-scoped commands inside of DMs with your app
Application Command Types
Name
Type
Description
Chat Input
1
Slash commands; a text-based command that shows up when a user types /
User
2
A UI-based command that shows up when you right click or tap on a user
Message
3
A UI-based command that shows up when you right click or tap on a message
Application Command Option Structure
Required options
must be listed before optional options
Field
Type
Description
type
one of application command option type
Type of option
name
string
1-32 character name
name_localizations?
?dictionary with keys in available locales
Localization dictionary for the name
field. Values follow the same restrictions as name
description
string
1-100 character description
description_localizations?
?dictionary with keys in available locales
Localization dictionary for the description
field. Values follow the same restrictions as description
required?
boolean
If the parameter is required or optional--default false
choices?
array of application command option choice
Choices for STRING
, INTEGER
, and NUMBER
types for the user to pick from, max 25
options?
array of application command option
If the option is a subcommand or subcommand group type, these nested options will be the parameters
channel_types?
array of channel types
If the option is a channel type, the channels shown will be restricted to these types
min_value?
number for INTEGER
options, double for NUMBER
options
If the option is an INTEGER
or NUMBER
type, the minimum value permitted
max_value?
number for INTEGER
options, double for NUMBER
options
If the option is an INTEGER
or NUMBER
type, the maximum value permitted
min_length?
number
For option type STRING
, the minimum allowed length (minimum of 0
, maximum of 6000
)
max_length?
number
For option type STRING
, the maximum allowed length (minimum of 1
, maximum of 6000
)
autocomplete? *
boolean
If autocomplete interactions are enabled for this STRING
, INTEGER
, or NUMBER
type option
* autocomplete
may not be set to true if choices
are present.
• Options using autocomplete
are not confined to only use choices given by the application.
Application Command Option Type
Name
Value
Note
Sub Command
1
Sub Command Group
2
String
3
Integer
4
Any integer between -2^53 and 2^53
Boolean
5
User
6
Channel
7
Includes all channel types + categories
Role
8
Mentionable
9
Includes users and roles
Number
10
Any double between -2^53 and 2^53
Attachment
11
attachment object
Application Command Option Choice Structure
• If you specify choices
for an option, they are the only valid values for a user to pick
Field
Type
Description
name
string
1-100 character choice name
name_localizations?
?dictionary with keys in available locales
Localization dictionary for the name
field. Values follow the same restrictions as name
value
string, integer, or double *
Value for the choice, up to 100 characters if string
* Type of value
depends on the option type that the choice belongs to.
Application Command Permissions Object
• Returned when fetching the permissions for an app's command(s) in a guild.
Field
Type
Description
id
snowflake
ID of the command or the application ID
application_id
snowflake
ID of the application the command belongs to
guild_id
snowflake
ID of the guild
permissions
array of application command permissions
Permissions for the command in the guild, max of 100
• When the id
field is the application ID instead of a command ID, the permissions apply to all commands that do not contain explicit overwrites.
Application Command Permissions Structure
• Application command permissions allow you to enable or disable commands for specific users, roles, or channels within a guild.
Application Command Permissions Constants
• The following constants can be used in the id
field for command permissions payloads.
Permission
Value
Type
Description
@everyone
guild_id
snowflake
All members in a guild
All Channels
guild_id - 1
snowflake
All channels in a guild
Application Command Permission Type
Name
Value
Role
1
User
2
Channel
3
Role Subscription Data Object
Field
Type
Description
role_subscription_listing_id
snowflake
the id of the sku and listing that the user is subscribed to
tier_name
string
the name of the tier that the user is subscribed to
total_months_subscribed
integer
the cumulative number of months that the user has been subscribed for
is_renewal
boolean
whether this notification is for a renewal rather than a new purchase
Field
Type
Description
id
snowflake
ID of the entitlement
sku_id
snowflake
ID of the SKU
application_id
snowflake
ID of the parent application
user_id?
snowflake
ID of the user that is granted access to the entitlement's sku
type
number
Type of entitlement
deleted
boolean
Entitlement was deleted
starts_at?
ISO8601 timestamp
Start date at which the entitlement is valid. Not present when using test entitlements.
ends_at?
ISO8601 timestamp
Date at which the entitlement is no longer valid. Not present when using test entitlements.
guild_id?
snowflake
ID of the guild that is granted access to the entitlement's sku
{
"id" : " 1019653849998299136" ,
"sku_id" : " 1019475255913222144" ,
"application_id" : " 1019370614521200640" ,
"user_id" : " 771129655544643584" ,
"promotion_id" : null ,
"type" : 8 ,
"deleted" : false ,
"gift_code_flags" : 0 ,
"consumed" : false ,
"starts_at" : " 2022-09-14T17:00:18.704163+00:00" ,
"ends_at" : " 2022-10-14T17:00:18.704163+00:00" ,
"guild_id" : " 1015034326372454400" ,
"subscription_id" : " 1019653835926409216"
}
Type
Value
Description
Application Subscription
8
Entitlement was purchased as an app subscription
Field
Type
Description
id
snowflake
ID of SKU
type
number
Type of SKU
application_id
snowflake
ID of the parent application
name
string
Customer-facing name of your premium offering
slug
string
System-generated URL slug based on the SKU's name
flags
number
SKU flags combined as a bitfield
{
"id" : " 1088510058284990888" ,
"type" : 5 ,
"dependent_sku_id" : null ,
"application_id" : " 788708323867885999" ,
"manifest_labels" : null ,
"access_type" : 1 ,
"name" : " Test Premium" ,
"features" : [],
"release_date" : null ,
"premium" : false ,
"slug" : " test-premium" ,
"flags" : 128 ,
"show_age_gate" : false
}
• For subscriptions, SKUs will have a type of either SUBSCRIPTION
represented by type: 5
or SUBSCRIPTION_GROUP
represented by type:6
.
• For any current implementations, you will want to use the SKU defined by type: 5
.
• A SUBSCRIPTION_GROUP
is automatically created for each SUBSCRIPTION
SKU and are not used at this time.
Type
Value
Description
Subscription
5
Represents a recurring subscription
Subscription Group
6
System-generated group for each SUBSCRIPTION SKU created
• For subscriptions, there are two types of access levels you can offer to users:
Guild Subscriptions : A subscription purchased by a user and applied to a single server. Everyone in that server gets your premium benefits.
User Subscriptions : A subscription purchased by a user for themselves. They get access to your premium benefits in every server.
• The flags
field can be used to differentiate user and server subscriptions with a bitwise &&
operator.
Type
Value
Description
Available
1 << 2
SKU is available for purchase
Guild Subscription
1 << 7
Recurring SKU that can be purchased by a user and applied to a single server. Grants access to every user in that server.
User Subscription
1 << 8
Recurring SKU purchased by a user for themselves. Grants access to the purchasing user in every server.
Field
Type
Description
application_commands
array of application commands objects
List of application commands referenced in the audit log
audit_log_entries
array of audit log entry objects
List of audit log entries, sorted from most to least recent
auto_moderation_rules
array of auto moderation rule objects
List of auto moderation rules referenced in the audit log
guild_scheduled_events
array of guild scheduled event objects
List of guild scheduled events referenced in the audit log
integrations
array of partial integration objects
List of partial integration objects
threads
array of thread-specific channel objects
List of threads referenced in the audit log*
users
array of user objects
List of users referenced in the audit log
webhooks
array of webhook objects
List of webhooks referenced in the audit log
* Threads referenced in THREAD_CREATE
and THREAD_UPDATE
events are included in the threads map since archived threads might not be kept in memory by clients.
Example Partial Integration Object
{
"id" : " 33590653072239123" ,
"name" : " A Name" ,
"type" : " twitch" ,
"account" : {
"name" : " twitchusername" ,
"id" : " 1234567"
},
"application_id" : " 94651234501213162"
}
Field
Type
Description
target_id
?string
ID of the affected entity (webhook, user, role, etc.)
changes?
array of audit log change objects
Changes made to the target_id
user_id
?snowflake
User or app that made the changes
id
snowflake
ID of the entry
action_type
audit log event
Type of action that occurred
options?
optional audit entry info
Additional info for certain event types
reason?
string
Reason for the change (1-512 characters)
• For APPLICATION_COMMAND_PERMISSION_UPDATE
events, the target_id
is the command ID or the app ID since the changes
array represents the entire permissions
property on the guild permissions object.
• The table below lists audit log events and values (the action_type
field) that your app may receive.
• The Object Changed column notes which object's values may be included in the entry.
• Though there are exceptions, possible keys in the changes
array typically correspond to the object's fields.
• The descriptions and types for those fields can be found in the linked documentation for the object.
• If no object is noted, there won't be a changes
array in the entry, though other fields like the target_id
still exist and many have fields in the options
array .
Event
Value
Description
Object Changed
Guild Update
1
Server settings were updated
Guild
Channel Create
10
Channel was created
Channel
Channel Update
11
Channel settings were updated
Channel
Channel Delete
12
Channel was deleted
Channel
Channel Overwrite Create
13
Permission overwrite was added to a channel
Channel Overwrite
Channel Overwrite Update
14
Permission overwrite was updated for a channel
Channel Overwrite
Channel Overwrite Delete
15
Permission overwrite was deleted from a channel
Channel Overwrite
Member Kick
20
Member was removed from server
Member Prune
21
Members were pruned from server
Member Ban Add
22
Member was banned from server
Member Ban Remove
23
Server ban was lifted for a member
Member Update
24
Member was updated in server
Member
Member Role Update
25
Member was added or removed from a role
Partial Role *
Member Move
26
Member was moved to a different voice channel
Member Disconnect
27
Member was disconnected from a voice channel
Bot Add
28
Bot user was added to server
Role Create
30
Role was created
Role
Role Update
31
Role was edited
Role
Role Delete
32
Role was deleted
Role
Invite Create
40
Server invite was created
Invite and Invite Metadata *
Invite Update
41
Server invite was updated
Invite and Invite Metadata *
Invite Delete
42
Server invite was deleted
Invite and Invite Metadata *
Webhook Create
50
Webhook was created
Webhook *
Webhook Update
51
Webhook properties or channel were updated
Webhook *
Webhook Delete
52
Webhook was deleted
Webhook *
Emoji Create
60
Emoji was created
Emoji
Emoji Update
61
Emoji name was updated
Emoji
Emoji Delete
62
Emoji was deleted
Emoji
Message Delete
72
Single message was deleted
Message Bulk Delete
73
Multiple messages were deleted
Message Pin
74
Message was pinned to a channel
Message Unpin
75
Message was unpinned from a channel
Integration Create
80
App was added to server
Integration
Integration Update
81
App was updated (as an example, its scopes were updated)
Integration
Integration Delete
82
App was removed from server
Integration
Stage Instance Create
83
Stage instance was created (stage channel becomes live)
Stage Instance
Stage Instance Update
84
Stage instance details were updated
Stage Instance
Stage Instance Delete
85
Stage instance was deleted (stage channel no longer live)
Stage Instance
Sticker Create
90
Sticker was created
Sticker
Sticker Update
91
Sticker details were updated
Sticker
Sticker Delete
92
Sticker was deleted
Sticker
Guild Scheduled Event Create
100
Event was created
Guild Scheduled Event
Guild Scheduled Event Update
101
Event was updated
Guild Scheduled Event
Guild Scheduled Event Delete
102
Event was cancelled
Guild Scheduled Event
Thread Create
110
Thread was created in a channel
Thread
Thread Update
111
Thread was updated
Thread
Thread Delete
112
Thread was deleted
Thread
Application Command Permission Update
121
Permissions were updated for a command
Command Permission *
Auto Moderation Rule Create
140
Auto Moderation rule was created
Auto Moderation Rule
Auto Moderation Rule Update
141
Auto Moderation rule was updated
Auto Moderation Rule
Auto Moderation Rule Delete
142
Auto Moderation rule was deleted
Auto Moderation Rule
Auto Moderation Block Message
143
Message was blocked by Auto Moderation
Auto Moderation Flag To Channel
144
Message was flagged by Auto Moderation
Auto Moderation User Communication Disabled
145
Member was timed out by Auto Moderation
Creator Monetization Request Created
150
Creator monetization request was created
Creator Monetization Terms Accepted
151
Creator monetization terms were accepted
* Object has exception(s) to available keys. See the exceptions section below for details.
Optional Audit Entry Info
Field
Type
Description
Event Types
application_id
snowflake
ID of the app whose permissions were targeted
APPLICATION_COMMAND_PERMISSION_UPDATE
auto_moderation_rule_name
string
Name of the Auto Moderation rule that was triggered
AUTO_MODERATION_BLOCK_MESSAGE & AUTO_MODERATION_FLAG_TO_CHANNEL & AUTO_MODERATION_USER_COMMUNICATION_DISABLED
auto_moderation_rule_trigger_type
string
Trigger type of the Auto Moderation rule that was triggered
AUTO_MODERATION_BLOCK_MESSAGE & AUTO_MODERATION_FLAG_TO_CHANNEL & AUTO_MODERATION_USER_COMMUNICATION_DISABLED
channel_id
snowflake
Channel in which the entities were targeted
MEMBER_MOVE & MESSAGE_PIN & MESSAGE_UNPIN & MESSAGE_DELETE & STAGE_INSTANCE_CREATE & STAGE_INSTANCE_UPDATE & STAGE_INSTANCE_DELETE & AUTO_MODERATION_BLOCK_MESSAGE & AUTO_MODERATION_FLAG_TO_CHANNEL & AUTO_MODERATION_USER_COMMUNICATION_DISABLED
count
string
Number of entities that were targeted
MESSAGE_DELETE & MESSAGE_BULK_DELETE & MEMBER_DISCONNECT & MEMBER_MOVE
delete_member_days
string
Number of days after which inactive members were kicked
MEMBER_PRUNE
id
snowflake
ID of the overwritten entity
CHANNEL_OVERWRITE_CREATE & CHANNEL_OVERWRITE_UPDATE & CHANNEL_OVERWRITE_DELETE
members_removed
string
Number of members removed by the prune
MEMBER_PRUNE
message_id
snowflake
ID of the message that was targeted
MESSAGE_PIN & MESSAGE_UNPIN
role_name
string
Name of the role if type is "0"
(not present if type is "1"
)
CHANNEL_OVERWRITE_CREATE & CHANNEL_OVERWRITE_UPDATE & CHANNEL_OVERWRITE_DELETE
type
string
Type of overwritten entity - role ("0"
) or member ("1"
)
CHANNEL_OVERWRITE_CREATE & CHANNEL_OVERWRITE_UPDATE & CHANNEL_OVERWRITE_DELETE
integration_type
string
The type of integration which performed the action
MEMBER_KICK & MEMBER_ROLE_UPDATE
• Many audit log events include a changes
array in their entry object .
• The structure for the individual changes varies based on the event type and its changed objects, so apps shouldn't depend on a single pattern of handling audit log events.
Audit Log Change Structure
• Some events don't follow the same pattern as other audit log events.
If new_value
is not present in the change object while old_value
is, it indicates that the property has been reset or set to null
.
If old_value
isn't included, it indicated that the property was previously null
.
Field
Type
Description
new_value?
mixed (matches object field's type)
New value of the key
old_value?
mixed (matches object field's type)
Old value of the key
key
string
Name of the changed entity, with a few exceptions
Audit Log Change Exceptions
• For most objects, the change keys may be any field on the changed object. The following table details the exceptions to this pattern.
Object Changed
Change Key Exceptions
Change Object Exceptions
Command Permission
snowflake as key
The changes
array contains objects with a key
field representing the entity whose command was affected (role, channel, or user ID), a previous permissions object (with an old_value
key), and an updated permissions object (with a new_value
key)
Invite and Invite Metadata
Additional channel_id
key (instead of object's channel.id
)
Partial Role
$add
and $remove
as keys
new_value
is an array of objects that contain the role id
and name
Webhook
avatar_hash
key (instead of avatar
)
Auto Moderation Rule Structure
Field
Type
Description
id
snowflake
the id of this rule
guild_id
snowflake
the id of the guild which this rule belongs to
name
string
the rule name
creator_id
snowflake
the user which first created this rule
event_type
integer
the rule event type
trigger_type
integer
the rule trigger type
trigger_metadata
object
the rule trigger metadata
actions
array of action objects
the actions which will execute when the rule is triggered
enabled
boolean
whether the rule is enabled
exempt_roles
array of snowflakes
the role ids that should not be affected by the rule (Maximum of 20)
exempt_channels
array of snowflakes
the channel ids that should not be affected by the rule (Maximum of 50)
Example Auto Moderation Rule
{
"id" : " 969707018069872670" ,
"guild_id" : " 613425648685547541" ,
"name" : " Keyword Filter 1" ,
"creator_id" : " 423457898095789043" ,
"trigger_type" : 1 ,
"event_type" : 1 ,
"actions" : [
{
"type" : 1 ,
"metadata" : { "custom_message" : " Please keep financial discussions limited to the #finance channel" }
},
{
"type" : 2 ,
"metadata" : { "channel_id" : " 123456789123456789" }
},
{
"type" : 3 ,
"metadata" : { "duration_seconds" : 60 }
}
],
"trigger_metadata" : {
"keyword_filter" : [" cat*" , " *dog" , " *ana*" , " i like c++" ],
"regex_patterns" : [" (b|c)at" , " ^(?:[0-9]{1,3}\\ .){3}[0-9]{1,3}$" ]
},
"enabled" : true ,
"exempt_roles" : [" 323456789123456789" , " 423456789123456789" ],
"exempt_channels" : [" 523456789123456789" ]
}
• Characterizes the type of content which can trigger the rule.
Trigger Type
Value
Description
Max per Guild
Keyword
1
check if content contains words from a user defined list of keywords
6
Spam
3
check if content represents generic spam
1
Keyword Preset
4
check if content contains words from internal pre-defined wordsets
1
Mention Spam
5
check if content contains more unique mentions than allowed
1
• Additional data used to determine whether a rule should be triggered.
• Different fields are relevant based on the value of trigger_type .
Field
Type
Associated Trigger Types
Description
keyword_filter
array of strings *
KEYWORD
substrings which will be searched for in content (Maximum of 1000)
regex_patterns
array of strings **
KEYWORD
regular expression patterns which will be matched against content (Maximum of 10)
presets
array of keyword preset types
KEYWORD_PRESET
the internally pre-defined wordsets which will be searched for in content
allow_list
array of strings ***
KEYWORD, KEYWORD_PRESET
substrings which should not trigger the rule (Maximum of 100 or 1000)
mention_total_limit
integer
MENTION_SPAM
total number of unique role and user mentions allowed per message (Maximum of 50)
mention_raid_protection_enabled
boolean
MENTION_SPAM
whether to automatically detect mention raids
* A keyword can be a phrase which contains multiple words. Wildcard symbols can be used to customize how each keyword will be matched. Each keyword must be 60 characters or less.
** Only Rust flavored regex is currently supported, which can be tested in online editors such as Rustexp. Each regex pattern must be 260 characters or less.
*** Each allow_list
keyword can be a phrase which contains multiple words. Wildcard symbols can be used to customize how each keyword will be matched. Rules with KEYWORD
trigger_type accept a maximum of 100 keywords. Rules with KEYWORD_PRESET
trigger_type accept a maximum of 1000 keywords.
Trigger Metadata Field Limits
Field
Trigger Type
MAX ARRAY LENGTH
MAX CHARACTERS PER STRING
keyword_filter
KEYWORD
1000
60
regex_patterns
KEYWORD
10
260
allow_list
KEYWORD
100
60
allow_list
KEYWORD_PRESET
1000
60
Preset Type
Value
Description
Profanity
1
words that may be considered forms of swearing or cursing
Sexual Content
2
words that refer to sexually explicit behavior or activity
Slurs
3
personal insults or words that may be considered hate speech
• Indicates in what event context a rule should be checked.
Event Type
Value
Description
Message Send
1
when a member sends or edits a message in the guild
Keyword Matching Strategies
• Use the wildcard symbol (*
) at the beginning or end of a keyword to define how it should be matched. All keywords are case insensitive.
Prefix - word must start with the keyword
| Keyword | Matches