├── .gitignore ├── CONTRIBUTING.md ├── README.md ├── docs ├── Change_Log.md ├── Intro.md ├── Legal.md ├── Reference.md ├── resources │ ├── Audit_Log.md │ ├── Channel.md │ ├── Guild.md │ ├── Invite.md │ ├── User.md │ ├── Voice.md │ └── Webhook.md └── topics │ ├── GameBridge.md │ ├── Gateway.md │ ├── Libraries.md │ ├── OAuth2.md │ ├── Permissions.md │ ├── RPC.md │ ├── Rate_Limits.md │ ├── Response_Codes.md │ ├── Rich_Presence.md │ └── Voice_Connections.md ├── images ├── API_center.gif └── rp-profile-view.png ├── index.js └── package.json /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | ## Wanted Changes 2 | 3 | 1. Fixes to incorrect statements or inaccuracies within the documentation. 4 | 2. Rewording or extending documentation to clarify unclear wording or complicated explanations. 5 | 3. Additions that fill gaps or missing pieces in the current documentation. 6 | 4. Fixing of spelling and grammatical errors in the documentation. 7 | 8 | ## Unwanted Changes 9 | 10 | 1. Whitespace or formatting changes. 11 | 2. Modifications to the overall structure and format of the API docs. 12 | 3. Additions that replicate or needlessly restructure current documentation. 13 | 14 | By submitting pull requests to this repository, you waive any rights or ownership of the included contents to Discord. Contributions to this repository must conform to the [Discord App TOS](https://discordapp.com/tos). 15 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Discord Official API Documentation 2 | 3 | This repo contains the official Discord API documentation, which can be viewed online [HERE](https://discordapp.com/developers/docs/intro). Before submitting pull-requests, please remember to _fully_ read the [Contributing](CONTRIBUTING.md) guidelines. 4 | 5 | ## Markdown Syntax 6 | 7 | This repository uses special markdown syntax that helps style the resulting web version of the documentation. 8 | 9 | ### H6 Headings 10 | H6 headings should be used above tables and code blocks to properly label them. 11 | 12 | ### Linking 13 | Links between docs can be achieved by using a hash symbol (#), plus the markdown file name, plus a slash, and finally the dash-separated anchor. For instance, to link to the above H6 heading section: 14 | 15 | ```md 16 | [Links to README.md H6](#README/h6-headings) 17 | ``` 18 | 19 | ### Alert Boxes 20 | Alert boxes are achieved by using a block quote that has one of 'warn', 'danger' or 'info' on the first line. 21 | 22 | ## Join the Unofficial Discord API Server 23 | The Unofficial Discord API server is a common hangout for library and bot developers alike. It's a great starting point for those looking to dive in and learn bot-creation with the Discord API. 24 | 25 | [![](https://discordapp.com/api/guilds/81384788765712384/embed.png?style=banner1)](https://discord.gg/discord-api) 26 | -------------------------------------------------------------------------------- /docs/Change_Log.md: -------------------------------------------------------------------------------- 1 | # Change Log 2 | 3 | >danger 4 | >API and Gateway versions below v6 will be discontinued on October 16, 2017, after which they will be non-functioning. 5 | 6 | ## August 3, 2017 - Breaking Change 7 | 8 | After today, we are changing how default channels function. The "default" channel for a given user is now the channel with the highest position that their permissions allow them to see. New guilds will no longer have a default channel with the same id as the guild. Existing guilds will not have their #general channel id changed. It is possible, if permissions are set in such a way, that a user will not have a default channel in a guild. 9 | 10 | We saw a use case in many servers where the previously-default #general channel was being repurposed as an announcement-only, non-writable channel for new members by using bots to clear the entire message history. Now, that channel can simply be deleted and re-created with the desired permissions. This change also allows dynamic default channels for users based on permissions. 11 | 12 | We are also rolling out a change in conjunction that will allow Discord to remember your last-visited channel in a guild across sessions. Newly-joined users will be directed to the guild's default channel on first join; existing members will return to whichever channel they last visited. 13 | 14 | ## July 24, 2017 15 | 16 | Audit logs are here! Well, they've been here all along, but now we've got [documentation](#DOCS_AUDIT_LOG/audit-logs) about them. Check it out, but remember: with great power comes great responsibility. 17 | 18 | ## July 19, 2017 — Version 6 Breaking Changes 19 | 20 | * [Channel](#DOCS_CHANNEL/channel-object) Object 21 | * `is_private` removed 22 | * [`type`](#DOCS_CHANNEL/channel-object-channel-types) is now an integer 23 | * `recipient` is now `recipients`, an array of [user](#DOCS_USER/user-object) objects 24 | * [Message](#DOCS_CHANNEL/message-object) Object 25 | * [`type`](#DOCS_CHANNEL/message-object-message-types) added to support system messages 26 | * [Status Update](#DOCS_GATEWAY/gateway-status-update-gateway-status-update-structure) Object 27 | * `idle_since` renamed to `since` 28 | -------------------------------------------------------------------------------- /docs/Intro.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | These developer pages document how to use Discord's API to empower your applications and create awesome bots for your 4 | communities. All of our [documentation is on GitHub](https://github.com/hammerandchisel/discord-api-docs) and we would 5 | <3 corrections and improvements! 6 | 7 | ![Bot related things](API_center.gif) 8 | 9 | 10 | ## Applications (aka Apps) 11 | 12 | Making an app on Discord opens up many possibilities for deeper integrations with your other services and platforms. 13 | Here are some examples to whet your appetite: 14 | 15 | * Using your Discord account to safely login to your guild's website 16 | * Display who’s online or in-game on your website or forum 17 | * Automatically join private Discord servers or gain new roles based on external website permissions 18 | * Other neat things. 19 | 20 | Head over to our new [applications page](#MY_APPLICATIONS/top) to dive into creating your own custom juice. 21 | 22 | 23 | ### Airhorn Solutions - Bot #0 24 | 25 | On April 1st we launched [Airhorn Solutions](https://airhorn.solutions) to bring chaos upon this meek world. 26 | 27 | Now that the noise has subsided, we’ve [open-sourced the source code for Airhorn Solutions](https://github.com/hammerandchisel/airhornbot). It’s the first fully-functional bot built with our initial API launch. If you’re looking for a working example of our API, we highly suggest digging in. 28 | 29 | 30 | ## Games (aka Games) 31 | 32 | GameBridge is a free SDK that lets you power your desktop game's social features with Discord. Check out some of the 33 | tasty flavors GameBridge offers: 34 | 35 | * Add low latency voice and text chat to your game. 36 | * Let your players share fancy moments including screenshots and links. 37 | * Show chat from your game's Discord community directly on your main menu. 38 | * Use servers for your game's guild chat extending it into the Discord experience. 39 | 40 | For now GameBridge is in private beta. If you're interested in trying out Discord to power your game please [sign up over here](https://discordapp.com/gamebridge). 41 | 42 | There is also an [active unofficial community-driven Discord Server for devs](https://discord.gg/discord-api). Come hang out if you wanna chat with other devs and see what’s being cranked out. 43 | 44 | We look forward to seeing what you make! 45 | 46 | -- Discord Dev Team 47 | -------------------------------------------------------------------------------- /docs/Legal.md: -------------------------------------------------------------------------------- 1 | # Discord Developer Terms of Service 2 | 3 | ## Effective Date: August 20, 2017 4 | 5 | This Discord Developer Terms of Service (“Agreement”) is between Discord Inc. (“Discord” or 6 | “us”) and you (“you” or “Licensee”). 7 | 8 | Discord has developed an Application Programming Interface (“API”) and Software 9 | Development Kit (“SDK”) in connection with our Discord online and mobile chat platform (the 10 | “Platform”). By using the API, SDK and/or its accompanying instructions, manuals, guidelines, 11 | samples and examples (the “Documentation”), you agree to be bound by this Agreement. End 12 | users using the Platform in connection with Licensee’s Applications (“End Users”) must be 13 | bound by the Discord Terms of Service, currently located at [https://discordapp.com/tos](https://discordapp.com/tos) (the 14 | “TOS”). Please note that the TOS includes Discord’s Privacy Policy, currently located at 15 | [https://discordapp.com/privacy](https://discordapp.com/privacy) (“Privacy Policy”). 16 | 17 | **By downloading, accessing or using the API or SDK or Documentation in any way, 18 | Licensee affirms that Licensee has read this Agreement, understands it, and agrees to be 19 | bound by it.** 20 | 21 | ### 1\. API AND SDK 22 | 23 | 1.1 __API and SDK.__ The API and SDK consists of specific programmatic application 24 | programming interfaces, interface definitions, generated code libraries and associated tools. The 25 | API is an interface that facilitates interaction with the Platform’s servers. The SDK is software 26 | code that is designed to be integrated into and to ship bundle with your applications 27 | (“Applications”). 28 | 29 | 1.2 __API or SDK Modifications.__ Discord reserves the right to modify the API or SDK, and to 30 | release subsequent versions. You may be required to use the most recent version of the API or 31 | SDK in order to obtain certain functionality. 32 | 33 | 1.3 __Support.__ Discord has no obligation to provide you or any users of your Applications with 34 | support, software upgrades, enhancements or modifications to the API or SDK. If Discord makes 35 | available updated versions of the API or SDK, you will use reasonable efforts to use only the 36 | then-current version as soon as possible and will use only the then-current version within 30 days 37 | of the date the then-current version becomes available. You understand and agree that you are 38 | solely responsible for providing user support and any other technical assistance for your 39 | Applications and other products and/or services. 40 | 41 | ### 2\. LICENSE, ACCOUNTS AND RESTRICTIONS 42 | 43 | 2.1 __API or SDK License.__ Subject to the terms and conditions of this Agreement, Discord grants 44 | you a limited, non-exclusive, revocable, non-transferable license to access and use the API or 45 | SDK solely to as necessary to (i) develop, test, display and execute your Applications with the 46 | API or SDK functionality included; and (ii) distribute to third parties, or permit third parties to 47 | access, the API or SDK as integrated into your Applications. 48 | 49 | 2.2 __Restrictions.__ You shall not, and shall not permit any person, directly or indirectly, to (i) 50 | reverse engineer, disassemble, reconstruct, decompile, translate, modify or copy the API or SDK, 51 | other than as explicitly permitted hereunder (except to the extent the foregoing restriction is 52 | expressly prohibited by applicable law notwithstanding this limitation), (ii) create derivative 53 | works of the API or SDK or any aspect or portion thereof, including without limitation, source 54 | code and algorithms, (iii) distribute or otherwise disseminate the API or SDK by any means or in 55 | any form, except as an integral part of your Applications; (iv) use the API or SDK in connection 56 | with any Applications that include any malware or other harmful code or that facilitate 57 | spamming in any way; (v) circumvent any limits or any privacy or access controls (or attempt to 58 | do so); or (vi) include any advertisements or other promotions within the functionality enabled 59 | by the API or SDK. Except as expressly set forth in this Agreement, Discord reserves all rights 60 | in or the API and SDK. 61 | 62 | 2.3 __Trademark License and Branding.__ Subject to the terms of this Agreement, Discord grants you 63 | a limited, non-exclusive, revocable, non-transferable license to display the Discord trademark 64 | solely for the purpose of attributing the source of the API or SDK and indicating that you used 65 | the API or SDK in creating your Applications. In doing so, you shall adhere to Discord’s brand 66 | guidelines, currently located at [https://discordapp.com/branding](https://discordapp.com/branding). In addition, all use of the SDK 67 | must be in compliance with Discord’s in-game brand guidelines. All use by you of the Discord 68 | trademark (including any goodwill associated therewith) shall inure to the benefit of Discord. At 69 | no time during or after the term of this Agreement shall you challenge or assist others to 70 | challenge the Discord trademark or the registration thereof by Discord, nor shall you attempt to 71 | register the Discord trademark or brand identifiers (including domain names) that are 72 | confusingly similar in any way (including but not limited to, sound, appearance and spelling) to 73 | the Discord trademark. You shall include in your Applications, website and other relevant 74 | locations a disclaimer stating that your Applications, website or any services is or are not 75 | endorsed or created by Discord. 76 | 77 | 2.4 __End User Data.__ “End User Data” means all data associated with the content within the 78 | functionality enabled by the API or SDK, including but not limited to message content, message 79 | metadata, voice data and voice metadata. You acknowledge and agree that Discord and its end 80 | users, as applicable, retain all worldwide right, title and interest in and to the End User Data. If 81 | you have access to End User Data, you shall ensure that your Applications do not collect, use 82 | and/or disclose End User Data except (a) as necessary to exercise your rights under this 83 | Agreement, (b) as expressly permitted by the End Users, and (c) in accordance with Discord’s 84 | Privacy Policy. You shall not sell, license or otherwise commercialize any End User Data. You 85 | may not use End User Data to target End Users for marketing or advertising purposes. You may 86 | not disclose End User Data to any ad network, data broker or other advertising or monetization related 87 | service. You shall permanently delete all End User Data upon Discord’s or the End 88 | User’s request and within seven (7) days following the End User’s termination of the End User’s 89 | account. You may only retain chat logs as necessary for the operation of your Applications. 90 | Discord’s offering of an API or SDK that allows you to reproduce or display End User 91 | message content is not an express or implied license to such content from Discord. You 92 | must seek permission from End Users. 93 | 94 | 2.5 __End Users.__ Without limiting any other provision of this Agreement, you agree to the 95 | following with respect to End Users and their accounts: 96 | 97 | (a) You shall not modify an End User's account state except in response to such End User 98 | giving you explicit permission to do so. For example, you may not join an End User to a 99 | server unless such End User approved joining that server (such as when using a "group 100 | finder" app). 101 | 102 | (b) You shall not post messages, trigger notifications, or play audio on behalf of an End 103 | User except in response to such End User expressly opting-in to each instance of such 104 | behavior. 105 | 106 | (c) You shall ensure that your Application retains End User Data only if the End User 107 | associated with such End User Data expressly triggers a command with an explicit 108 | keyword or click (on a website) and even in such cases, such End User Data shall be 109 | retained only as necessary to provide the defined functionality of the Application. 110 | 111 | (d) You shall ensure that an End User’s access to the Platform or any portion of 112 | functionality enabled by the SDK or API is subject to the TOS; accordingly, you shall 113 | ensure that all End Users expressly agree to the TOS. Without limiting the foregoing, 114 | you shall ensure that each End User expressly agree to the collection, use and disclosure 115 | of all information made available by such End User in accordance with the terms of this 116 | Agreement and the TOS, which includes Discord’s Privacy Policy. 117 | 118 | (e) You and your Application will not, and you will not, encourage or create functionality 119 | for your users that violates Discord’s TOS. 120 | 121 | (f) You shall ensure that all End User Data is stored using encryption and that you take 122 | reasonable steps to secure End User Data. 123 | 124 | (g) You shall not obtain End User passwords to Discord’s service under any 125 | circumstance; you shall use only Discord’s designated approval methods for obtaining 126 | access to or permission to access End User Data. 127 | 128 | 2.6 __Developer Accounts.__ You will need to create an account to have access to the SDK and/or 129 | API (the “Developer Account”). In conjunction with your Developer Account, you will: (a) 130 | provide true, accurate, current and complete information about yourself, your Applications and 131 | your business (such information being the "Registration Data") and (b) maintain and promptly 132 | update the Registration Data to keep it true, accurate, current and complete. You may be limited 133 | by the account creation process to one account per email address. You are entirely responsible 134 | for the security and confidentiality of your password and Developer Account. Furthermore, you 135 | are entirely responsible for any and all activities that occur under your account. You will not 136 | share your Developer Account, your user name and password with any third party or permit any 137 | third party to log on using your account information. You agree to immediately notify us of any 138 | unauthorized use of your Developer Account or any other breach of security of which you 139 | become aware. You agree that we can use, store, and share Registration Data as permitted in 140 | Discord’s Privacy Policy. Discord maintains the right to cancel your Developer Account for any 141 | reason or no reason at all, at any time. After you have successfully created your Developer 142 | Account, you will be issued one or more unique security keys, secrets, tokens, access codes, 143 | passwords or other credentials (collectively, “Keys”). All activities that occur using your Keys 144 | are your responsibility. You are not permitted to disclose, sell, transfer, or sublicense them to 145 | anyone. 146 | 147 | 2.7 __Rate Limits.__ You will not attempt to exceed or circumvent limitations on access to and use of 148 | the SDK or API, exceed or circumvent any limitation on the API calls you may make, or 149 | otherwise use the SDK or API in a manner that exceeds reasonable request volume, or 150 | constitutes excessive or abusive usage (“Rate Limits”). If Discord, in its sole discretion, 151 | determines that you have attempted to exceed or circumvent Rate Limits, or other controls that 152 | limit use of the SDK or API, then your ability to use the SDK or API may be temporarily 153 | suspended or permanently blocked. 154 | 155 | 2.8 __Security Measures.__ Your network, operating system and the software of your web servers, 156 | databases, and computer systems must be properly configured to securely operate and store your 157 | Applications. Your Applications must use industry standard security measures to protect against 158 | and prevent security breaches and any unauthorized disclosure of the personal information of 159 | your End Users, including administrative, physical and technical safeguards for protection of the 160 | security, confidentiality and integrity of the personal information of your End Users. You must 161 | promptly report any security deficiencies in, or intrusions to, your Applications or systems that 162 | you discover. 163 | 164 | 2.9 __Audit and Monitoring.__ You agree to provide us with access to your 165 | Applications and/or other materials related to your use of the API and SDK as may be requested 166 | by us to verify your compliance with this Agreement, to audit your use, display and storage of 167 | the API and SDK. You agree that we may crawl or otherwise remotely monitor such items 168 | related to your use of the API and SDK and you agree not to block or interfere with such efforts. 169 | 170 | ### 3\. WARRANTY 171 | 172 | You represent and warrant to Discord that: (a) you have validly entered 173 | into this Agreement and have the legal power to do so; (b) you are responsible for the conduct of 174 | your End Users and their compliance with the terms of this Agreement and the TOS; (c) any 175 | Applications developed by you or your contractors shall not infringe or violate the intellectual 176 | property, proprietary, privacy or other rights of any person or entity; (d) you shall comply with 177 | all applicable laws and regulations, including but not limited to privacy laws and regulations; (e) 178 | your Applications must use industry standard security measures to protect against and prevent 179 | security breaches of your Applications and unauthorized access to your End User’s personal 180 | information; and (f) you have and comply with a privacy policy that complies with all applicable 181 | laws. 182 | 183 | ### 4\. DISCORD APPLICATION DEVELOPMENT AND FEEDBACK 184 | 185 | You acknowledge 186 | and agree that Discord may create features, applications, content, and other products or services 187 | that may be similar to your Applications, and nothing in this Agreement will be construed as 188 | restricting or preventing Discord from creating and fully exploiting such applications, content 189 | and other items, without any obligation to you. If you elect to provide us with any suggestions or 190 | feedback, you hereby assign all right, title and interest in and to such suggestions or feedback to 191 | Discord and acknowledge that we will be entitled to use, implement and exploit any such 192 | suggestions or feedback in any manner without restriction, and without any obligation of 193 | confidentiality, attribution, accounting or compensation to you. 194 | 195 | ### 5\. PROPRIETARY RIGHTS 196 | 197 | Except for the licenses expressly granted to you in this 198 | Agreement, Discord shall own and retain all right, title and interest, including without limitation 199 | all intellectual property rights, in and to (i) the API or SDK and any and all elements and 200 | components thereof, including content, technology, software code, user interfaces and any 201 | derivative works and/or compilations thereof; (ii) the Discord trademark; and (iii) any feedback 202 | provided by you (including suggestions, comments, improvements, ideas, etc.) about or relating 203 | to Discord, the API or SDK or any applications, websites or other materials that Discord may be 204 | developing (collectively, “Discord Property”). You shall own and retain all right, title and 205 | interest in and to your Applications, except with respect to any Discord Property or End User 206 | Data that has been incorporated therein. 207 | 208 | ### 6\. TERMINATION 209 | 210 | Without prejudice to any other rights or remedies that we may have, 211 | Discord may terminate the license granted hereunder: (i) upon notice if Licensee fails to comply 212 | with any of the terms and conditions of this Agreement; or (ii) for convenience, upon thirty (30) 213 | days’ prior written notice. In addition, Discord may terminate or suspend the license granted 214 | hereunder if your Application(s) for any reason compromise or threaten to compromise the 215 | integrity of Discord’s service. In the event the license is terminated, Licensee shall discontinue 216 | any further use, and destroy all copies, of the API or SDK and Documentation in its possession 217 | or control. Sections 1.2, 1.3, 4-9 and 11-16 shall survive any termination of this Agreement. 218 | 219 | ### 7\. NO WARRANTY 220 | 221 | THE API OR SDK AND DOCUMENTATION ARE BEING 222 | PROVIDED TO YOU "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS 223 | OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTY OF 224 | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 225 | 226 | ### 8\. LIMITATION OF LIABILITY 227 | 228 | TO THE MAXIMUM EXTENT PERMITTED BY 229 | LAW, IN NO EVENT SHALL DISCORD OR ITS AFFILIATES, OR ITS OR THEIR 230 | RESPECTIVE DIRECTORS, OFFICERS, EMPLOYEES, AGENTS OR REPRESENTATIVES 231 | (COLLECTIVELY, THE "DISCORD PARTIES") BE LIABLE OR RESPONSIBLE FOR 232 | DAMAGES OF ANY KIND (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR 233 | LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF INFORMATION 234 | OR DATA, OR ANY OTHER INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL 235 | DAMAGES) ARISING OUT OF THE USE OF OR INABILITY TO USE THE API OR SDK 236 | OR OTHERWISE IN CONNECTION WITH THIS AGREEMENT, EVEN IF ADVISED OF 237 | THE POSSIBILITY OF SUCH DAMAGES. IN ANY EVENT, THE DISCORD PARTIES’ 238 | TOTAL AGGREGATE LIABILITY TO YOU FOR ALL DAMAGES OF ANY KIND AND 239 | TYPE (REGARDLESS OF WHETHER BASED IN CONTRACT OR TORT) SHALL NOT 240 | EXCEED THE GREATER OF (A) THE LICENSE FEE (IF ANY) PAID BY YOU FOR THE 241 | API OR SDK OR (B) $100. THE LIMITATIONS AND DISCLAIMERS IN THIS 242 | AGREEMENT DO NOT PURPORT TO LIMIT LIABILITY OR ALTER RIGHTS THAT 243 | CANNOT BE EXCLUDED UNDER APPLICABLE LAW. Some jurisdictions do not allow the 244 | exclusion of implied warranties or limitation of liability for incidental or consequential damages, 245 | which means that some of the above disclaimers and limitations may not apply to you. IN 246 | THESE JURISDICTIONS, DISCORD’S LIABILITY WILL BE LIMITED TO THE 247 | GREATEST EXTENT PERMITTED BY LAW. 248 | IT IS EXPRESSLY UNDERSTOOD AND AGREED THAT IN THE EVENT ANY REMEDY 249 | HEREUNDER IS DETERMINED TO HAVE FAILED OF ITS ESSENTIAL PURPOSE, ALL 250 | LIMITATIONS OF LIABILITY AND EXCLUSIONS OF DAMAGES SET FORTH HEREIN 251 | SHALL REMAIN IN EFFECT. 252 | 253 | ### 9\. INDEMNIFICATION 254 | 255 | Licensee, at its own expense, shall defend, indemnify and hold 256 | harmless Discord and its affiliates, and its and their employees, contractors, agents, directors and 257 | customers from and against any and all claims, actions, demands, liabilities, losses, damages, 258 | judgments, settlements, costs and expenses, including reasonable attorneys’ fees (any or all of 259 | the foregoing hereinafter referred to as “Losses”), insofar as such Losses (or third party actions 260 | in respect thereof) are based on, arise out of, or are related to (i) a breach by Licensee of any 261 | representation, warranty, covenant or agreement made by it hereunder or (ii) the use, operation, 262 | promotion, distribution or license of the Applications by Licensee or its employees, contractors 263 | or agents. 264 | 265 | ### 10\. CONFIDENTIALITY 266 | 267 | You will: (a) protect and not disclose information made available 268 | by us that is identified as confidential or that reasonably should be considered confidential; (b) 269 | use this information only to fulfill your obligations under this Agreement; and (c) either destroy 270 | or return all such information to us promptly when the Agreement terminates (and, upon request, 271 | confirm such destruction in writing). 272 | 273 | ### 11\. PUBLICITY 274 | 275 | Licensee grants us the right to use Licensee’s company name and logo for 276 | marketing or promotional purposes on our website if Licensee’s use of the SDK or API is public. 277 | Otherwise, Discord will obtain Licensee’s prior written permission for such use. 278 | 279 | ### 12\. EXPORT CONTROLS 280 | 281 | In connection with Licensee’s use of the API or SDK Licensee 282 | shall comply with all applicable export and re-export control laws and regulations such as the 283 | Export Administration Regulations, the International Traffic in Arms Regulations and countryspecific 284 | economic sanctions programs implemented by the Office of Foreign Assets Control. 285 | 286 | ### 13\. CHILDREN 287 | 288 | The Platform is not intended for and should not be used by anyone under 289 | the age of 13. Licensee will not knowingly collect or enable the collection of any personal 290 | information from children under the age of 13. 291 | 292 | ### 14\. INJUNCTIVE RELIEF 293 | 294 | Licensee agrees that Discord will have the right to seek an 295 | injunction against any unauthorized use of the API or SDK by Licensee, in addition to any other 296 | rights and remedies to which Discord may be entitled. 297 | 298 | ### 15\. SEVERABILITY 299 | 300 | If any provision of this Agreement is held to be invalid or 301 | unenforceable by a court of competent jurisdiction, then such provision shall be adjusted to the 302 | minimum extent necessary for validity or enforceability, and in any event, the remaining 303 | provisions will nevertheless remain in full force and effect. 304 | 305 | ### 16\. ENTIRE AGREEMENT 306 | 307 | This Agreement constitutes the entire understanding and 308 | agreement between Discord and you with respect to the subject matter of this Agreement and 309 | supersedes all prior or contemporaneous oral or written communications with respect thereto. 310 | We may change this Agreement from time to time in our discretion. If we make a material 311 | change to the Agreement, we will provide you with reasonable notice prior to the change taking 312 | effect. Licensee can review the most current version of the Agreement at any time by visiting 313 | this page. The materially revised Agreement will become effective on the date set forth in our 314 | notice, and all other changes will become effective upon posting of the change. If Licensee (or 315 | your End Users) accesses or uses the Platform after the effective date, that use will constitute 316 | your acceptance of any revised terms and conditions. 317 | 318 | ### 17\. GOVERNING LAW, JURISDICTION AND VENUE 319 | 320 | This Agreement shall be 321 | interpreted, construed and enforced in all respects in accordance with the internal laws of the 322 | State of California, without regard to its principles of conflicts of law. Any claim or dispute 323 | between you and the Company that arises in whole or in part from this Agreement or your use of 324 | the API or SDK shall be decided exclusively by a court of competent jurisdiction located in 325 | Santa Clara County, California, and you hereby consent to, and waive all defenses of lack of 326 | personal jurisdiction and forum non conveniens with respect to venue and jurisdiction in the state 327 | and federal courts of Santa Clara County, California. 328 | 329 | ### 18\. NO ASSIGNMENT 330 | 331 | Licensee shall not assign, sublicense or delegate any of its rights or 332 | obligations under this Agreement to any third party without the prior written consent of Discord. 333 | Any assignment, sublicense or delegation in violation of this provision shall be null and void. 334 | 335 | ### 19\. GOVERNMENT USE AND ACCESS 336 | 337 | The API and SDK are “commercial items” as 338 | that term is defined at 48 C.F.R. 2.101, consisting of “commercial computer software” and 339 | “commercial computer software documentation” as such terms are used in 48 C.F.R. 12.212. 340 | Any use, modification, derivative, reproduction, release, performance, display, disclosure or 341 | distribution of the API or SDK by any government entity is prohibited, except as expressly 342 | permitted by the terms of this Agreement. Additionally, any use by U.S. government entities 343 | must be in accordance with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through 227.7202-4. The 344 | contractor/manufacturer is Discord Inc., 401 California Ave Burlingame, CA 94010. Licensee 345 | shall not allow or assist any government entities, law enforcement, or other organizations to 346 | conduct surveillance or obtain data using its access to the SDK or API in order to avoid serving 347 | legal process directly on Discord. Any such use by you for law enforcement purposes is a breach 348 | of this Agreement. 349 | 350 | ### 20\. ACKNOWLEDGMENT 351 | 352 | Use of the API or SDK affirms that Licensee has read this 353 | Agreement, understands it, and agrees to be bound by its contents. -------------------------------------------------------------------------------- /docs/Reference.md: -------------------------------------------------------------------------------- 1 | # API Reference 2 | 3 | Discord's API is based around two core layers, a HTTPS/REST API for general operations, and persistent secure websocket based connection for sending and subscribing to real-time events. The most common use case of the Discord API will be providing a service, or access to a platform through the [OAuth2](http://oauth.net/2/) API. 4 | 5 | ## Base URL 6 | 7 | The base URL for all API requests is: 8 | 9 | ``` 10 | https://discordapp.com/api 11 | ``` 12 | 13 | ## API Versioning 14 | 15 | >danger 16 | >API and Gateway versions below v6 will be discontinued on October 16, 2017, after which they will be non-functioning. 17 | 18 | Discord exposes different versions of our API. You can specify version by including it in the request path: 19 | 20 | ``` 21 | https://discordapp.com/api/v{version_number} 22 | ``` 23 | 24 | Omitting the version number from the route will route requests to the current default version. You can find the change log for the newest API version [here](https://discordapp.com/developers/docs/change-log). 25 | 26 | >warn 27 | >API and Gateway v6 will be made default on October 16, 2017 28 | 29 | ###### API Versions 30 | 31 | | Version | Status | Default | 32 | | ------- | ------ | ------- | 33 | | 6 | Available | | 34 | | 5 | Deprecated | | 35 | | 4 | Deprecated | | 36 | | 3 | Deprecated | ✓ | 37 | 38 | ## Authentication 39 | 40 | Authenticating with the Discord API can be done in one of two ways: 41 | 42 | 1. Using a bot token gained by [registering a bot](#DOCS_OAUTH2/registering-applications), for more information on bots see [bots vs user accounts](#DOCS_OAUTH2/bot-vs-user-accounts). 43 | 2. Using an OAuth2 bearer token gained through the [OAuth2 API](#DOCS_OAUTH2/oauth2). 44 | 45 | For all authentication types, authentication is performed with the `Authorization` HTTP header in the following format: 46 | 47 | ``` 48 | Authorization: TOKEN_TYPE TOKEN 49 | ``` 50 | 51 | ### Example Authorization Headers 52 | 53 | For bot tokens: 54 | 55 | ``` 56 | Authorization: Bot MTk4NjIyNDgzNDcxOTI1MjQ4.Cl2FMQ.ZnCjm1XVW7vRze4b7Cq4se7kKWs 57 | ``` 58 | 59 | For OAuth bearer tokens: 60 | 61 | ``` 62 | Authorization: Bearer CZhtkLDpNYXgPH9Ml6shqh2OwykChw 63 | ``` 64 | 65 | ## Encryption 66 | 67 | All HTTP-layer services and protocols (e.g. http, websocket) within the Discord API use TLS 1.2. 68 | 69 | ## Snowflake IDs 70 | 71 | Discord utilizes Twitter's [snowflake](https://github.com/twitter/snowflake/tree/snowflake-2010) format for uniquely identifiable descriptors (IDs). These IDs are up to 64bits in size (e.g. a uint64) and therefore are always returned as strings in the API to prevent integer overflows in some languages. Snowflake IDs are guaranteed to be unique across all of Discord, except in some unique scenarios in which child objects share their parents ID. 72 | 73 | ## Nullable Resource Fields 74 | 75 | Resource fields that may be null have types that are prefixed with a question mark. 76 | 77 | ## Optional Resource Fields 78 | 79 | Resources fields that are optional have names that are suffixed with a question mark. 80 | 81 | ###### Example Nullable and Optional Field 82 | 83 | | Field | Type | 84 | | ----- | ---- | 85 | | optional_field? | string | 86 | | nullable_field | ?string | 87 | | optional_and_nullable_field? | ?string | 88 | 89 | ## Consistency 90 | 91 | Discord operates at a scale where true consistency is impossible. Because of this, lots of operations in our API and in-between our services are [eventually consistent](https://en.wikipedia.org/wiki/Eventual_consistency). Due to this, client actions can never be serialized and may be executed in _any_ order (if executed at all). Along with these constraints, events in Discord may: 92 | 93 | - Never be sent to a client 94 | - Be sent _exactly_ one time to the client 95 | - Be sent up to N times per client 96 | 97 | Clients should operate on events and results from the API in as much of a idempotent behavior as possible. 98 | 99 | ## HTTP API 100 | 101 | ### User Agent 102 | 103 | Clients using the HTTP API must provide a valid [User Agent](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43) which specifies information about the client library and version, in the following format: 104 | 105 | ``` 106 | User-Agent: DiscordBot ($url, $versionNumber) 107 | ``` 108 | 109 | ### Rate Limiting 110 | 111 | The HTTP API implements a process for limiting and preventing excessive requests in accordance with [RFC 6585](https://tools.ietf.org/html/rfc6585#section-4). API users that regularly hit and ignore rate limits will have their API keys revoked, and be blocked from the platform. For more information on rate limiting of requests, please see the [Rate Limits](#DOCS_RATE_LIMITS/rate-limits) section. 112 | 113 | >warn 114 | > A bot account must connect and identify to a [Gateway](#DOCS_GATEWAY/connecting) at least once before being able to send messages. 115 | 116 | ## Gateway (WebSocket) API 117 | 118 | Discord's Gateway API is used for maintaining persistent, stateful websocket connections between your client and our servers. These connections are used for sending and receiving real-time events your client can use to track and update local state. The Gateway API uses secure websocket connections as specified in [RFC 6455](https://tools.ietf.org/html/rfc6455). For information on opening Gateway connections, please see the [Gateway API](#DOCS_GATEWAY/gateways) section. 119 | -------------------------------------------------------------------------------- /docs/resources/Audit_Log.md: -------------------------------------------------------------------------------- 1 | # Audit Logs Resource 2 | 3 | ## Audit Logs 4 | 5 | Whenever an admin action is performed on the API, an entry is added to the respective guild's audit log. You can specify the reason by attaching the `X-Audit-Log-Reason` request header. This header supports url encoded utf8 characters. 6 | 7 | ### Audit Log Object 8 | 9 | ###### Audit Log Structure 10 | 11 | | Field | Type | Description | 12 | |-------|------|-------------| 13 | | webhooks | array of [webhook](#DOCS_WEBHOOK/webhook-object) objects | list of webhooks found in the audit log | 14 | | users | array of [user](#DOCS_USER/user-object) objects | list of users found in the audit log | 15 | | audit_log_entries | array of [audit log entry](#DOCS_AUDIT_LOG/audit-log-entry-object) objects | list of audit log entires | 16 | 17 | ### Audit Log Entry Object 18 | 19 | ###### Audit Log Entry Structure 20 | 21 | | Field | Type | Description | 22 | |-------|------|-------------| 23 | | target_id | string | id of the affected entity (webhook, user, role, etc.) | 24 | | changes | array of [audit log change](#DOCS_AUDIT_LOG/audit-log-change-object) objects | changes made to the target_id | 25 | | user_id | snowflake | the user who made the changes 26 | | id | snowflake | id of the entry 27 | | action_type | [audit log event](#DOCS_AUDIT_LOG/audit-log-entry-object-audit-log-events) | type of action that occured | 28 | | options | array of [optional audit entry info](#DOCS_AUDIT_LOG/audit-log-entry-object-optional-audit-entry-info) objects | additional info for certain action types | 29 | | reason | string | the reason for the change | 30 | 31 | ###### Audit Log Events 32 | 33 | | Event | Value | 34 | |-------|------| 35 | | GUILD_UPDATE | 1 | 36 | | CHANNEL_CREATE | 10 | 37 | | CHANNEL_UPDATE | 11 | 38 | | CHANNEL_DELETE | 12 | 39 | | CHANNEL_OVERWRITE_CREATE | 13 | 40 | | CHANNEL_OVERWRITE_UPDATE | 14 | 41 | | CHANNEL_OVERWRITE_DELETE | 15 | 42 | | MEMBER_KICK | 20 | 43 | | MEMBER_PRUNE | 21 | 44 | | MEMBER_BAN_ADD | 22 | 45 | | MEMBER_BAN_REMOVE | 23 | 46 | | MEMBER_UPDATE | 24 | 47 | | MEMBER_ROLE_UPDATE | 25 | 48 | | ROLE_CREATE | 30 | 49 | | ROLE_UPDATE | 31 | 50 | | ROLE_DELETE | 32 | 51 | | INVITE_CREATE | 40 | 52 | | INVITE_UPDATE | 41 | 53 | | INVITE_DELETE | 42 | 54 | | WEBHOOK_CREATE | 50 | 55 | | WEBHOOK_UPDATE | 51 | 56 | | WEBHOOK_DELETE | 52 | 57 | | EMOJI_CREATE | 60 | 58 | | EMOJI_UPDATE | 61 | 59 | | EMOJI_DELETE | 62 | 60 | | MESSAGE_DELETE | 72 | 61 | 62 | ###### Optional Audit Entry Info 63 | 64 | | Field | Type | Description | Action Type | 65 | | ----- | ---- | ----------- | ----------- | 66 | | delete_member_days | string | number of days after which inactive members were kicked | MEMBER_PRUNE | 67 | | members_removed | string | number of members removed by the prune | MEMBER_PRUNE | 68 | | channel_id | snowflake | channel in which the messages were deleted | MESSAGE_DELETE | 69 | | count | string | number of deleted messages | MESSAGE_DELETE | 70 | | id | snowflake | id of the overwritten entity | CHANNEL_OVERWRITE_CREATE & CHANNEL_OVERWRITE_UPDATE & CHANNEL_OVERWRITE_DELETE | 71 | | type | string | type of overwritten entity ("member" or "role") | CHANNEL_OVERWRITE_CREATE & CHANNEL_OVERWRITE_UPDATE & CHANNEL_OVERWRITE_DELETE | 72 | | role_name | string | name of the role if type is "role"| CHANNEL_OVERWRITE_CREATE & CHANNEL_OVERWRITE_UPDATE & CHANNEL_OVERWRITE_DELETE | 73 | 74 | ### Audit Log Change Object 75 | 76 | ###### Audit Log Change Structure 77 | 78 | | Field | Type | Description | 79 | |-------|------|-------------| 80 | | new_value | [mixed](#DOCS_AUDIT_LOG/audit-log-change-object-audit-log-change-key) | new value of the key | 81 | | old_value | [mixed](#DOCS_AUDIT_LOG/audit-log-change-object-audit-log-change-key) | old value of the key | 82 | | key | string | type of audit log [change key](#DOCS_AUDIT_LOG/audit-log-change-object-audit-log-change-key) | 83 | 84 | ###### Audit Log Change Key 85 | 86 | | Name | Object Changed | Type | Description | 87 | | ---- | ------ | ---------- | ----------- | 88 | | name | [guild](#DOCS_GUILD/guild-object)| string | name changed | 89 | | icon_hash | [guild](#DOCS_GUILD/guild-object) | string | icon changed | 90 | | splash_hash | [guild](#DOCS_GUILD/guild-object) | string | invite splash page artwork changed | 91 | | owner_id | [guild](#DOCS_GUILD/guild-object) | snowflake | owner changed | 92 | | region | [guild](#DOCS_GUILD/guild-object) | string | region changed | 93 | | afk_channel_id | [guild](#DOCS_GUILD/guild-object) | snowflake | afk channel changed | 94 | | afk_timeout | [guild](#DOCS_GUILD/guild-object) | integer | afk timout duration changed | 95 | | mfa_level | [guild](#DOCS_GUILD/guild-object) | integer | two-factor auth requirement changed | 96 | | verification_level | [guild](#DOCS_GUILD/guild-object) | integer | required verification level changed | 97 | | explicit_content_filter | [guild](#DOCS_GUILD/guild-object) | integer | change in [whose messages](#DOCS_GUILD/guild-object-explicit-content-filter-level) are scanned and deleted for explicit content in the server | 98 | | default_message_notifications | [guild](#DOCS_GUILD/guild-object) | integer | default [message notification level](#DOCS_GUILD/guild-object-default-message-notification-level) changed | 99 | | vanity_url_code | [guild](#DOCS_GUILD/guild-object) | string | guild invite vanity url changed | 100 | | $add | [guild](#DOCS_GUILD/guild-object) | array of [role](#DOCS_PERMISSIONS/role-object) objects | new role added | 101 | | $remove | [guild](#DOCS_GUILD/guild-object) | array of [role](#DOCS_PERMISSIONS/role-object) objects | role removed | 102 | | prune_delete_days | [guild](#DOCS_GUILD/guild-object) | integer | change in number of days after which inactive and role-unassigned members are kicked | 103 | | widget_enabled | [guild](#DOCS_GUILD/guild-object) | bool | server widget enabled/disable | 104 | | widget_channel_id | [guild](#DOCS_GUILD/guild-object) | snowflake | channel id of the server widget changed | 105 | | position | [channel](#DOCS_CHANNEL/channel-object) | integer | text or voice channel position changed | 106 | | topic | [channel](#DOCS_CHANNEL/channel-object) | string | text channel topic changed | 107 | | bitrate | [channel](#DOCS_CHANNEL/channel-object) | integer | voice channel bitrate changed | 108 | | permission_overwrites | [channel](#DOCS_CHANNEL/channel-object) | array of [channel overwrite](#DOCS_CHANNEL/overwrite-object) objects| permissions on a channel changed | 109 | | nsfw | [channel](#DOCS_CHANNEL/channel-object) | bool | channel nsfw restriction changed | 110 | | application_id | [channel](#DOCS_CHANNEL/channel-object)| snowflake | application id of the added or removed webhook or bot | 111 | | permissions | [role](#DOCS_GUILD/role-object)| integer | [permissions](#DOCS_PERMISSIONS/permissions-bitwise-permission-flags) for a role changed | 112 | | color | [role](#DOCS_PERMISSIONS/role-object) | integer | role color changed | 113 | | hoist | [role](#DOCS_PERMISSIONS/role-object) | bool | role is now displayed/no longer displayed separate from online users | 114 | | mentionable | [role](#DOCS_PERMISSIONS/role-object) | bool | role is now mentionable/unmentionable | 115 | | allow | [role](#DOCS_PERMISSIONS/role-object) | integer | a permission on a text or voice channel was allowed for a role | 116 | | deny | [role](#DOCS_PERMISSIONS/role-object) | integer | a permission on a text or voice channel was denied for a role | 117 | | code | [invite](#DOCS_INVITE/invite-object) | string | invite code changed | 118 | | channel_id | [invite](#DOCS_INVITE/invite-channel-object) | snowflake | channel for invite code changed | 119 | | inviter_id | [invite](#DOCS_INVITE/invite-metadata-object) | snowflake | person who created invite code changed | 120 | | max_uses | [invite](#DOCS_INVITE/invite-metadata-object) | integer | change to max number of times invite code can be used | 121 | | uses | [invite](#DOCS_INVITE/invite-metadata-object) | integer | number of times invite code used changed | 122 | | max_age | [invite](#DOCS_INVITE/invite-metadata-object) | integer | how long invite code lasts changed | 123 | | temporary | [invite](#DOCS_INVITE/invite-metadata-object) | bool | invite code is temporary/never expires | 124 | | deaf | [user](#DOCS_USER/user-object) | bool | user server deafened/undeafened | 125 | | mute | [user](#DOCS_USER/user-object) | bool | user server muted/unmuteds | 126 | | nick | [user](#DOCS_USER/user-object) | string | user nickname changed | 127 | | avatar_hash | [user](#DOCS_USER/user-object) | string | user avatar changed | 128 | | id | any | snowflake | the id of the changed entity - sometimes used in conjunction with other keys | 129 | | type | any | integer ([channel type](#DOCS_CHANNEL/channel-object-channel-types)) or string | type of entity created | 130 | 131 | 132 | ## Get Guild Audit Log % GET /guilds/{guild.id#DOCS_GUILD/guild-object}/audit-logs 133 | 134 | Returns an [audit log](#DOCS_AUDIT_LOG/audit-log-object) object for the guild. Requires the 'VIEW_AUDIT_LOG' permission. 135 | 136 | ###### Query String Parameters 137 | 138 | |Field | Type | Description | 139 | | ---- | ----- | ---------- | 140 | | user_id | snowflake | filter the log for a user id | 141 | | action_type | int | the type of [audit log event](#DOCS_AUDIT_LOG/audit-log-entry-object-audit-log-events) | 142 | | before | snowflake | filter the log before a certain entry id | 143 | | limit | integer | how many entries are returned (default 50, minimum 1, maximum 100) | 144 | -------------------------------------------------------------------------------- /docs/resources/Channel.md: -------------------------------------------------------------------------------- 1 | # Channels Resource 2 | 3 | ## Channel Object 4 | 5 | Represents a guild or DM channel within Discord. 6 | 7 | ###### Channel Structure 8 | 9 | | Field | Type | Description | 10 | |-------|------|-------------| 11 | | id | snowflake | the id of this channel (will be equal to the guild if it's the "general" channel) | 12 | | type | integer | the [type of channel](#DOCS_CHANNEL/channel-object-channel-types) | 13 | | guild\_id? | snowflake | the id of the guild | 14 | | position? | integer | sorting position of the channel | 15 | | permission\_overwrites? | array of [overwrite](#DOCS_CHANNEL/overwrite-object) objects | explicit permission overwrites for members and roles | 16 | | name? | string | the name of the channel (2-100 characters) | 17 | | topic? | string | the channel topic (0-1024 characters) | 18 | | last\_message\_id? | snowflake | the id of the last message sent in this channel (may not point to an existing or valid message) | 19 | | bitrate? | integer | the bitrate (in bits) of the voice channel | 20 | | user\_limit? | integer | the user limit of the voice channel | 21 | | recipients? | array of [user](#DOCS_USER/user-object) objects | the recipients of the DM | 22 | | icon? | ?string | icon hash | 23 | | owner_id? | snowflake | id of the DM creator | 24 | | application_id? | snowflake | application id of the group DM creator if it is bot-created | 25 | 26 | ###### Channel Types 27 | 28 | | Type | ID | 29 | | ---- | -- | 30 | | GUILD_TEXT| 0 | 31 | | DM | 1 | 32 | | GUILD_VOICE | 2 | 33 | | GROUP_DM | 3 | 34 | | GUILD_CATEGORY | 4 | 35 | 36 | ###### Example Guild Text Channel 37 | 38 | ```json 39 | { 40 | "id": "41771983423143937", 41 | "guild_id": "41771983423143937", 42 | "name": "general", 43 | "type": 0, 44 | "position": 6, 45 | "permission_overwrites": [], 46 | "topic": "24/7 chat about how to gank Mike #2", 47 | "last_message_id": "155117677105512449" 48 | } 49 | ``` 50 | 51 | ###### Example Guild Voice Channel 52 | 53 | ```json 54 | { 55 | "id": "155101607195836416", 56 | "guild_id": "41771983423143937", 57 | "name": "ROCKET CHEESE", 58 | "type": 2, 59 | "position": 5, 60 | "permission_overwrites": [], 61 | "bitrate": 64000, 62 | "user_limit": 0 63 | } 64 | ``` 65 | 66 | ###### Example DM Channel 67 | 68 | ```json 69 | { 70 | "last_message_id": "3343820033257021450", 71 | "type": 1, 72 | "id": "319674150115610528", 73 | "recipients": [ 74 | { 75 | "username": "test", 76 | "discriminator": "9999", 77 | "id": "82198898841029460", 78 | "avatar": "33ecab261d4681afa4d85a04691c4a01" 79 | } 80 | ] 81 | } 82 | ``` 83 | 84 | ###### Example Group DM Channel 85 | 86 | ```json 87 | { 88 | "name": "Some test channel", 89 | "icon": null, 90 | "recipients": [ 91 | { 92 | "username": "test", 93 | "discriminator": "9999", 94 | "id": "82198898841029460", 95 | "avatar": "33ecab261d4681afa4d85a04691c4a01" 96 | }, 97 | { 98 | "username": "test2", 99 | "discriminator": "9999", 100 | "id": "82198810841029460", 101 | "avatar": "33ecab261d4681afa4d85a10691c4a01" 102 | } 103 | ], 104 | "last_message_id": "3343820033257021450", 105 | "type": 3, 106 | "id": "319674150115710528", 107 | "owner_id": "82198810841029460" 108 | } 109 | ``` 110 | 111 | ### Message Object 112 | 113 | Represents a message sent in a channel within Discord. 114 | 115 | ###### Message Structure 116 | 117 | | Field | Type | Description | 118 | |-------|------|-------------| 119 | | id | snowflake | id of the message | 120 | | channel\_id | snowflake | id of the channel the message was sent in | 121 | | author* | [user](#DOCS_USER/user-object) object | the author of this message (not guaranteed to be a valid user, see below) | 122 | | content | string | contents of the message | 123 | | timestamp | ISO8601 timestamp | when this message was sent | 124 | | edited\_timestamp | ?ISO8601 timestamp | when this message was edited (or null if never) | 125 | | tts | bool | whether this was a TTS message | 126 | | mention\_everyone | bool | whether this message mentions everyone | 127 | | mentions | array of [user](#DOCS_USER/user-object) objects | users specifically mentioned in the message | 128 | | mention\_roles | array of [role](#DOCS_PERMISSIONS/role-object) object ids | roles specifically mentioned in this message | 129 | | attachments | array of [attachment](#DOCS_CHANNEL/attachment-object) objects | any attached files | 130 | | embeds | array of [embed](#DOCS_CHANNEL/embed-object) objects | any embedded content | 131 | | reactions? | array of [reaction](#DOCS_CHANNEL/reaction-object) objects | reactions to the message | 132 | | nonce? | ?snowflake | used for validating a message was sent | 133 | | pinned | bool | whether this message is pinned | 134 | | webhook\_id? | string | if the message is generated by a webhook, this is the webhook's id | 135 | | type | int | [type of message](#DOCS_CHANNEL/message-object-message-types) | 136 | 137 | * 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. 138 | 139 | ###### Message Types 140 | 141 | | Type | Value | 142 | | ---- | ----- | 143 | | DEFAULT | 0 | 144 | | RECIPIENT_ADD | 1 | 145 | | RECIPIENT_REMOVE | 2 | 146 | | CALL | 3 | 147 | | CHANNEL_NAME_CHANGE | 4 | 148 | | CHANNEL_ICON_CHANGE | 5 | 149 | | CHANNEL_PINNED_MESSAGE | 6 | 150 | | GUILD_MEMBER_JOIN | 7 | 151 | 152 | ###### Example Message 153 | 154 | ```json 155 | { 156 | "reactions": [ 157 | { 158 | "count": 1, 159 | "me": false, 160 | "emoji": { 161 | "id": null, 162 | "name": "🔥" 163 | } 164 | } 165 | ], 166 | "attachments": [], 167 | "tts": false, 168 | "embeds": [], 169 | "timestamp": "2017-07-11T17:27:07.299000+00:00", 170 | "mention_everyone": false, 171 | "id": "334385199974967042", 172 | "pinned": false, 173 | "edited_timestamp": null, 174 | "author": { 175 | "username": "Mason", 176 | "discriminator": "9999", 177 | "id": "53908099506183680", 178 | "avatar": "a_bab14f271d565501444b2ca3be944b25" 179 | }, 180 | "mention_roles": [], 181 | "content": "Supa Hot", 182 | "channel_id": "290926798999357250", 183 | "mentions": [], 184 | "type": 0 185 | } 186 | ``` 187 | 188 | ### Reaction Object 189 | 190 | ###### Reaction Structure 191 | 192 | | Field | Type | Description | 193 | |-------|------|-------------| 194 | | count | integer | times this emoji has been used to react | 195 | | me | bool | whether the current user reacted using this emoji | 196 | | emoji | partial [emoji object](#DOCS_GUILD/emoji-object) | emoji information | 197 | 198 | ### Overwrite Object 199 | 200 | ###### Overwrite Structure 201 | 202 | | Field | Type | Description | 203 | |-------|------|-------------| 204 | | id | snowflake | role or user id | 205 | | type | string | either "role" or "member" | 206 | | allow | integer | permission bit set | 207 | | deny | integer | permission bit set | 208 | 209 | ### Embed Object 210 | 211 | ###### Embed Structure 212 | 213 | | Field | Type | Description | 214 | |-------|------|-------------| 215 | | title | string | title of embed | 216 | | type | string | type of embed (always "rich" for webhook embeds) | 217 | | description | string | description of embed | 218 | | url | string | url of embed | 219 | | timestamp | ISO8601 timestamp | timestamp of embed content | 220 | | color | integer | color code of the embed | 221 | | footer | [embed footer](#DOCS_CHANNEL/embed-footer-structure) object | footer information 222 | | image | [embed image](#DOCS_CHANNEL/embed-image-structure) object | image information 223 | | thumbnail | [embed thumbnail](#DOCS_CHANNEL/embed-thumbnail-structure) object | thumbnail information | 224 | | video | [embed video](#DOCS_CHANNEL/embed-video-structure) object | video information | 225 | | provider | [embed provider](#DOCS_CHANNEL/embed-provider-structure) object | provider information | 226 | | author | [embed author](#DOCS_CHANNEL/embed-author-structure) object | author information | 227 | | fields | array of [embed field](#DOCS_CHANNEL/embed-field-structure) objects | fields information | 228 | 229 | ###### Embed Thumbnail Structure 230 | 231 | | Field | Type | Description | 232 | |-------|------|-------------| 233 | | url | string | source url of thumbnail (only supports http(s) and attachments) | 234 | | proxy_url | string | a proxied url of the thumbnail | 235 | | height | integer | height of thumbnail | 236 | | width | integer | width of thumbnail | 237 | 238 | ###### Embed Video Structure 239 | 240 | | Field | Type | Description | 241 | |-------|------|-------------| 242 | | url | string | source url of video | 243 | | height | integer | height of video | 244 | | width | integer | width of video | 245 | 246 | ###### Embed Image Structure 247 | 248 | | Field | Type | Description | 249 | |-------|------|-------------| 250 | | url | string | source url of image (only supports http(s) and attachments) | 251 | | proxy_url | string | a proxied url of the image | 252 | | height | integer | height of image | 253 | | width | integer | width of image | 254 | 255 | ###### Embed Provider Structure 256 | 257 | | Field | Type | Description | 258 | |-------|------|-------------| 259 | | name | string | name of provider | 260 | | url | string | url of provider | 261 | 262 | ###### Embed Author Structure 263 | 264 | | Field | Type | Description | 265 | |-------|------|-------------| 266 | | name | string | name of author | 267 | | url | string | url of author | 268 | | icon_url | string | url of author icon (only supports http(s) and attachments) | 269 | | proxy_icon_url | string | a proxied url of author icon | 270 | 271 | ###### Embed Footer Structure 272 | 273 | | Field | Type | Description | 274 | |-------|------|-------------| 275 | | text | string | footer text | 276 | | icon_url | string | url of footer icon (only supports http(s) and attachments) | 277 | | proxy_icon_url | string | a proxied url of footer icon | 278 | 279 | ###### Embed Field Structure 280 | 281 | | Field | Type | Description | 282 | |-------|------|-------------| 283 | | name | string | name of the field | 284 | | value | string | value of the field | 285 | | inline | bool | whether or not this field should display inline | 286 | 287 | ### Attachment Object 288 | 289 | ###### Attachment Structure 290 | 291 | | Field | Type | Description | 292 | |-------|------|-------------| 293 | | id | snowflake | attachment id | 294 | | filename | string | name of file attached | 295 | | size | integer | size of file in bytes | 296 | | url | string | source url of file | 297 | | proxy_url | string | a proxied url of file | 298 | | height | ?integer | height of file (if image) | 299 | | width | ?integer | width of file (if image) | 300 | 301 | ## Message Formatting 302 | 303 | Discord utilizes a subset of markdown for rendering message content on its clients, while also adding some custom functionality to enable things like mentioning users and channels. This functionality uses the following formats: 304 | 305 | ###### Formats 306 | 307 | | Type | Structure | Example | 308 | |---------|-------------|-------------| 309 | | User | `<@USER_SNOWFLAKE_ID>` | `<@80351110224678912>` | 310 | | User (Nickname) | `<@!USER_SNOWFLAKE_ID>` | `<@!80351110224678912>` | 311 | | Channel | `<#CHANNEL_SNOWFLAKE_ID>` | `<#103735883630395392>` | 312 | | Role | `<@&ROLE_SNOWFLAKE_ID>` | `<@&165511591545143296>` | 313 | | Custom Emoji | `<:NAME:ID>` | `<:mmLol:216154654256398347>` | 314 | 315 | Using the markdown for either users, roles or channels will mention the target(s) accordingly. 316 | 317 | ## Get Channel % GET /channels/{channel.id#DOCS_CHANNEL/channel-object} 318 | 319 | Get a channel by ID. Returns a [guild channel](#DOCS_CHANNEL/channel-object) or [dm channel](#DOCS_CHANNEL/channel-object) object. 320 | 321 | ## Modify Channel % PUT/PATCH /channels/{channel.id#DOCS_CHANNEL/channel-object} 322 | 323 | Update a channels settings. Requires the 'MANAGE_CHANNELS' permission for the guild. Returns a [guild channel](#DOCS_CHANNEL/channel-object) on success, and a 400 BAD REQUEST on invalid parameters. Fires a [Channel Update](#DOCS_GATEWAY/channel-update) Gateway event. For the **PATCH** method, all the JSON Params are optional. 324 | 325 | ###### JSON Params 326 | 327 | | Field | Type | Description | Channel Type | 328 | |-------|------|-------------|--------------| 329 | | name | string | 2-100 character channel name | Both | 330 | | position | integer | the position of the channel in the left-hand listing | Both | 331 | | topic | string | 0-1024 character channel topic | Text | 332 | | bitrate | integer | the bitrate (in bits) of the voice channel; 8000 to 96000 (128000 for VIP servers) | Voice | 333 | | user_limit | integer | the user limit of the voice channel; 0 refers to no limit, 1 to 99 refers to a user limit | Voice | 334 | 335 | ## Delete/Close Channel % DELETE /channels/{channel.id#DOCS_CHANNEL/channel-object} 336 | 337 | Delete a guild channel, or close a private message. Requires the 'MANAGE_CHANNELS' permission for the guild. Returns a [guild channel](#DOCS_CHANNEL/channel-object) or [dm channel](#DOCS_CHANNEL/channel-object) object on success. Fires a [Channel Delete](#DOCS_GATEWAY/channel-delete) Gateway event. 338 | 339 | >warn 340 | > Deleting a guild channel cannot be undone. Use this with caution, as it is impossible to undo this action when performed on a guild channel. In contrast, when used with a private message, it is possible to undo the action by opening a private message with the recipient again. 341 | 342 | ## Get Channel Messages % GET /channels/{channel.id#DOCS_CHANNEL/channel-object}/messages 343 | 344 | Returns the messages for a channel. If operating on a guild channel, this endpoint requires the 'READ_MESSAGES' permission to be present on the current user. Returns an array of [message](#DOCS_CHANNEL/message-object) objects on success. 345 | 346 | >info 347 | > The before, after, and around keys are mutually exclusive, only one may be passed at a time. 348 | 349 | ###### Query String Params 350 | 351 | | Field | Type | Description | Required | Default | 352 | |-------|------|-------------|----------|---------| 353 | | around | snowflake | get messages around this message ID | false | absent | 354 | | before | snowflake | get messages before this message ID | false | absent | 355 | | after | snowflake | get messages after this message ID | false | absent | 356 | | limit | integer | max number of messages to return (1-100) | false | 50 | 357 | 358 | ## Get Channel Message % GET /channels/{channel.id#DOCS_CHANNEL/channel-object}/messages/{message.id#DOCS_CHANNEL/message-object} 359 | 360 | Returns a specific message in the channel. If operating on a guild channel, this endpoints requires the 'READ_MESSAGE_HISTORY' permission to be present on the current user. Returns a [message](#DOCS_CHANNEL/message-object) object on success. 361 | 362 | ## Create Message % POST /channels/{channel.id#DOCS_CHANNEL/channel-object}/messages 363 | 364 | Post a message to a guild text or DM channel. If operating on a guild channel, this endpoint requires the 'SEND_MESSAGES' permission to be present on the current user. Returns a [message](#DOCS_CHANNEL/message-object) object. Fires a [Message Create](#DOCS_GATEWAY/message-create) Gateway event. See [message formatting](#DOCS_CHANNEL/message-formatting) for more information on how to properly format messages. 365 | 366 | >warn 367 | > This endpoint supports both JSON and form data bodies. It does require multipart/form-data requests instead of the normal JSON request type when uploading files. Make sure you set your `Content-Type` to `multipart/form-data` if you're doing that. Note that in that case, the `embed` field cannot be used, but you can pass an url-encoded JSON body as a form value for `payload_json`. 368 | 369 | ###### JSON Params 370 | 371 | | Field | Type | Description | Required | 372 | |-------|------|-------------|----------| 373 | | content | string | the message contents (up to 2000 characters) | true | 374 | | nonce | snowflake | a nonce that can be used for optimistic message sending | false | 375 | | tts | bool | true if this is a TTS message | false | 376 | | file | file contents | the contents of the file being sent | one of content, file, embeds (multipart form data only) | 377 | | embed | [embed](#DOCS_CHANNEL/embed-object) object | embedded `rich` content | false | 378 | 379 | >info 380 | > For the embed object, you can set every field except `type` (it will be `rich` regardless of if you try to set it), `provider`, `video`, and any `height`, `width`, or `proxy_url` values for images. 381 | 382 | ###### Using Attachments within Embeds 383 | 384 | You can upload attachments when creating a message and use those attachments within your embed. To do this, you will want to upload files as part of your `multipart/form-data` body. Make sure that you're uploading files that contain a filename, as you will need a filename to reference against. 385 | 386 | In the embed object, you can then set an image to use an attachment as its url with our attachment scheme syntax: `attachment://filename.png` 387 | 388 | For example: 389 | 390 | ```json 391 | { 392 | "embed": { 393 | "image": { 394 | "url": "attachment://screenshot.png" 395 | } 396 | } 397 | } 398 | ``` 399 | 400 | >warn 401 | > Only filenames with proper image extensions are supported for the time being. 402 | 403 | ## Create Reaction % PUT /channels/{channel.id#DOCS_CHANNEL/channel-object}/messages/{message.id#DOCS_CHANNEL/message-object}/reactions/{emoji#DOCS_GUILD/emoji-object}/@me 404 | 405 | Create a reaction for the message. This endpoint requires the 'READ\_MESSAGE\_HISTORY' permission to be present on the current user. Additionally, if nobody else has reacted to the message using this emoji, this endpoint requires the 'ADD\_REACTIONS' permission to be present on the current user. Returns a 204 empty response on success. 406 | 407 | ## Delete Own Reaction % DELETE /channels/{channel.id#DOCS_CHANNEL/channel-object}/messages/{message.id#DOCS_CHANNEL/message-object}/reactions/{emoji#DOCS_GUILD/emoji-object}/@me 408 | 409 | Delete a reaction the current user has made for the message. Returns a 204 empty response on success. 410 | 411 | ## Delete User Reaction % DELETE /channels/{channel.id#DOCS_CHANNEL/channel-object}/messages/{message.id#DOCS_CHANNEL/message-object}/reactions/{emoji#DOCS_GUILD/emoji-object}/{user.id#DOCS_USER/user-object} 412 | 413 | Deletes another user's reaction. This endpoint requires the 'MANAGE\_MESSAGES' permission to be present on the current user. Returns a 204 empty response on success. 414 | 415 | ## Get Reactions % GET /channels/{channel.id#DOCS_CHANNEL/channel-object}/messages/{message.id#DOCS_CHANNEL/message-object}/reactions/{emoji#DOCS_GUILD/emoji-object} 416 | 417 | Get a list of users that reacted with this emoji. Returns an array of [user](#DOCS_USER/user-object) objects on success. 418 | 419 | ## Delete All Reactions % DELETE /channels/{channel.id#DOCS_CHANNEL/channel-object}/messages/{message.id#DOCS_CHANNEL/message-object}/reactions 420 | 421 | Deletes all reactions on a message. This endpoint requires the 'MANAGE\_MESSAGES' permission to be present on the current user. 422 | 423 | ## Edit Message % PATCH /channels/{channel.id#DOCS_CHANNEL/channel-object}/messages/{message.id#DOCS_CHANNEL/message-object} 424 | 425 | Edit a previously sent message. You can only edit messages that have been sent by the current user. Returns a [message](#DOCS_CHANNEL/message-object) object. Fires a [Message Update](#DOCS_GATEWAY/message-update) Gateway event. 426 | 427 | >info 428 | > All parameters to this endpoint are optional. 429 | 430 | ###### JSON Params 431 | 432 | | Field | Type | Description | 433 | |-------|------|-------------| 434 | | content | string | the new message contents (up to 2000 characters) | 435 | | embed | [embed](#DOCS_CHANNEL/embed-object) object | embedded `rich` content | 436 | 437 | ## Delete Message % DELETE /channels/{channel.id#DOCS_CHANNEL/channel-object}/messages/{message.id#DOCS_CHANNEL/message-object} 438 | 439 | Delete a message. If operating on a guild channel and trying to delete a message that was not sent by the current user, this endpoint requires the 'MANAGE_MESSAGES' permission. Returns a 204 empty response on success. Fires a [Message Delete](#DOCS_GATEWAY/message-delete) Gateway event. 440 | 441 | ## Bulk Delete Messages % POST /channels/{channel.id#DOCS_CHANNEL/channel-object}/messages/bulk-delete 442 | 443 | Delete multiple messages in a single request. This endpoint can only be used on guild channels and requires the 'MANAGE_MESSAGES' permission. Returns a 204 empty response on success. Fires multiple [Message Delete](#DOCS_GATEWAY/message-delete) Gateway events. 444 | 445 | The gateway will ignore any individual messages that do not exist or do not belong to this channel, but these will count towards the minimum and maximum message count. Duplicate snowflakes will only be counted once for these limits. 446 | 447 | > warn 448 | > This endpoint will not delete messages older than 2 weeks, and will fail if any message provided is older than that. 449 | > An endpoint will be added in the future to prune messages older than 2 weeks from a channel. 450 | 451 | ###### JSON Params 452 | 453 | | Field | Type | Description | 454 | |-------|------|-------------| 455 | | messages | array of snowflakes | an array of message ids to delete | 456 | 457 | ## Bulk Delete Messages (deprecated) % POST /channels/{channel.id#DOCS_CHANNEL/channel-object}/messages/bulk_delete 458 | 459 | Same as above, but this endpoint is deprecated. 460 | 461 | ## Edit Channel Permissions % PUT /channels/{channel.id#DOCS_CHANNEL/channel-object}/permissions/{overwrite.id#DOCS_CHANNEL/overwrite-object} 462 | 463 | Edit the channel permission overwrites for a user or role in a channel. Only usable for guild channels. Requires the 'MANAGE_ROLES' permission. Returns a 204 empty response on success. For more information about permissions, see [permissions](#DOCS_PERMISSIONS/permissions). 464 | 465 | ###### JSON Params 466 | 467 | | Field | Type | Description | 468 | |-------|------|-------------| 469 | | allow | integer | the bitwise value of all allowed permissions | 470 | | deny | integer | the bitwise value of all disallowed permissions | 471 | | type | string | "member" for a user or "role" for a role | 472 | 473 | ## Get Channel Invites % GET /channels/{channel.id#DOCS_CHANNEL/channel-object}/invites 474 | 475 | Returns a list of [invite](#DOCS_INVITE/invite-object) objects (with [invite metadata](#DOCS_INVITE/invite-metadata-object)) for the channel. Only usable for guild channels. Requires the 'MANAGE_CHANNELS' permission. 476 | 477 | ## Create Channel Invite % POST /channels/{channel.id#DOCS_CHANNEL/channel-object}/invites 478 | 479 | Create a new [invite](#DOCS_INVITE/invite-object) object for the channel. Only usable for guild channels. Requires the `CREATE_INSTANT_INVITE` permission. All JSON paramaters for this route are optional, however the request body is not. If you are not sending any fields, you still have to send an empty JSON object (`{}`). Returns an [invite](#DOCS_INVITE/invite-object) object. 480 | 481 | ###### JSON Params 482 | 483 | | Field | Type | Description | Default | 484 | |-------|------|-------------|----------| 485 | | max_age | integer | duration of invite in seconds before expiry, or 0 for never | 86400 (24 hours) | 486 | | max_uses | integer | max number of uses or 0 for unlimited | 0 | 487 | | temporary | bool | whether this invite only grants temporary membership | false | 488 | | unique | bool | if true, don't try to reuse a similar invite (useful for creating many unique one time use invites) | false | 489 | 490 | ## Delete Channel Permission % DELETE /channels/{channel.id#DOCS_CHANNEL/channel-object}/permissions/{overwrite.id#DOCS_CHANNEL/overwrite-object} 491 | 492 | Delete a channel permission overwrite for a user or role in a channel. Only usable for guild channels. Requires the 'MANAGE_ROLES' permission. Returns a 204 empty response on success. For more information about permissions, see [permissions](#DOCS_PERMISSIONS/permissions) 493 | 494 | ## Trigger Typing Indicator % POST /channels/{channel.id#DOCS_CHANNEL/channel-object}/typing 495 | 496 | Post a typing indicator for the specified channel. Generally bots should **not** implement this route. However, if a bot is responding to a command and expects the computation to take a few seconds, this endpoint may be called to let the user know that the bot is processing their message. Returns a 204 empty response on success. Fires a [Typing Start](#DOCS_GATEWAY/typing-start) Gateway event. 497 | 498 | ## Get Pinned Messages % GET /channels/{channel.id#DOCS_CHANNEL/channel-object}/pins 499 | 500 | Returns all pinned messages in the channel as an array of [message](#DOCS_CHANNEL/message-object) objects. 501 | 502 | ## Add Pinned Channel Message % PUT /channels/{channel.id#DOCS_CHANNEL/channel-object}/pins/{message.id#DOCS_CHANNEL/message-object} 503 | 504 | Pin a message in a channel. Requires the 'MANAGE_MESSAGES' permission. Returns a 204 empty response on success. 505 | 506 | ## Delete Pinned Channel Message % DELETE /channels/{channel.id#DOCS_CHANNEL/channel-object}/pins/{message.id#DOCS_CHANNEL/message-object} 507 | 508 | Delete a pinned message in a channel. Requires the 'MANAGE_MESSAGES' permission. Returns a 204 empty response on success. 509 | 510 | ## Group DM Add Recipient % PUT /channels/{channel.id#DOCS_CHANNEL/channel-object}/recipients/{user.id#DOCS_USER/user-object} 511 | 512 | Adds a recipient to a Group DM using their access token 513 | 514 | ###### JSON Params 515 | 516 | | Field | Type | Description | 517 | |-------|------|-------------| 518 | | access_token | string | access token of a user that has granted your app the `gdm.join` scope | 519 | | nick | string | nickname of the user being added | 520 | 521 | ## Group DM Remove Recipient % DELETE /channels/{channel.id#DOCS_CHANNEL/channel-object}/recipients/{user.id#DOCS_USER/user-object} 522 | 523 | Removes a recipient from a Group DM 524 | -------------------------------------------------------------------------------- /docs/resources/Guild.md: -------------------------------------------------------------------------------- 1 | # Guild Resource 2 | 3 | Guilds in Discord represent an isolated collection of users and channels, and are often referred to as "servers" in the UI. 4 | 5 | ### Guild Object 6 | 7 | ###### Guild Structure 8 | 9 | | Field | Type | Description | 10 | |-------|------|-------------| 11 | | id | snowflake | guild id | 12 | | name | string | guild name (2-100 characters) | 13 | | icon | string | icon hash | 14 | | splash | string | splash hash | 15 | | owner\_id | snowflake | id of owner | 16 | | region | string | {voice\_region.id} | 17 | | afk\_channel\_id | snowflake | id of afk channel | 18 | | afk\_timeout | integer | afk timeout in seconds | 19 | | embed\_enabled | bool | is this guild embeddable (e.g. widget) | 20 | | embed\_channel\_id | snowflake | id of embedded channel | 21 | | verification\_level | integer | level of [verification](#DOCS_GUILD/guild-object-verification-level) required for the guild | 22 | | default\_message\_notifications | integer | default message [notifications level](#DOCS_GUILD/guild-object-default-message-notification-level) | 23 | | explicit\_content\_filter | integer | default explicit content [filter level](#DOCS_GUILD/guild-object-explicit-content-filter-level) | 24 | | roles | array of [role](#DOCS_PERMISSIONS/role-object) objects | roles in the guild | 25 | | emojis | array of [emoji](#DOCS_GUILD/emoji-object) objects | custom guild emojis | 26 | | features | array of strings | enabled guild features | 27 | | mfa\_level | integer | required [MFA level](#DOCS_GUILD/guild-object-mfa-level) for the guild | 28 | | application_id | ?snowflake | application id of the guild creator if it is bot-created | 29 | | widget_enabled | bool | whether or not the server widget is enabled | 30 | | widget_channel_id | snowflake | the channel id for the server widget | 31 | | joined\_at \* | ISO8601 timestamp | when this guild was joined at | 32 | | large \* | bool | whether this is considered a large guild | 33 | | unavailable \* | bool | is this guild unavailable | 34 | | member\_count \* | integer | total number of members in this guild | 35 | | voice\_states \* | array of partial [voice state](#DOCS_VOICE/voice-state-object) objects | (without the `guild_id` key) | 36 | | members \* | array of [guild member](#DOCS_GUILD/guild-member-object) objects | users in the guild | 37 | | channels \* | array of [channel](#DOCS_CHANNEL/channel-object) objects | channels in the guild | 38 | | presences \* | array of partial [presence update](#DOCS_GATEWAY/presence-update) objects | presences of the users in the guild | 39 | 40 | ** \* These fields are only sent within the [GUILD_CREATE](#DOCS_GATEWAY/guild-create) event ** 41 | 42 | ###### Default Message Notification Level 43 | 44 | | Key | Value | 45 | | --- | ----- | 46 | | ALL_MESSAGES | 0 | 47 | | ONLY_MENTIONS | 1 | 48 | 49 | ###### Explicit Content Filter Level 50 | 51 | | Level | Integer 52 | | ---- | ------ | 53 | | DISABLED | 0 | 54 | | MEMBERS_WITHOUT_ROLES | 1 | 55 | | ALL_MEMBERS | 2 | 56 | 57 | ###### MFA Level 58 | 59 | | Level | Integer | 60 | | ----- | ------- | 61 | | NONE | 0 | 62 | | ELEVATED | 1 | 63 | 64 | ###### Verification Level 65 | 66 | | Level | Integer | Description | 67 | | ----- | ------- | ----------- | 68 | | NONE | 0 | unrestricted | 69 | | LOW | 1 | must have verified email on account | 70 | | MEDIUM | 2 | must be registered on Discord for longer than 5 minutes | 71 | | HIGH | 3 | (╯°□°）╯︵ ┻━┻ - must be a member of the server for longer than 10 minutes | 72 | | VERY_HIGH | 4 | ┻━┻ミヽ(ಠ益ಠ)ﾉ彡┻━┻ - must have a verified phone number | 73 | 74 | ###### Example Guild 75 | 76 | ```json 77 | { 78 | "id": "41771983423143937", 79 | "application_id": null, 80 | "name": "Discord Developers", 81 | "icon": "SEkgTU9NIElUUyBBTkRSRUkhISEhISEh", 82 | "splash": null, 83 | "owner_id": "80351110224678912", 84 | "region": "us-east", 85 | "afk_channel_id": "42072017402331136", 86 | "afk_timeout": 300, 87 | "embed_enabled": true, 88 | "embed_channel_id": "41771983444115456", 89 | "verification_level": 1, 90 | "default_message_notifications": 0, 91 | "explicit_content_filter": 0, 92 | "mfa_level": 0, 93 | "widget_enabled": false, 94 | "widget_channel_id": "41771983423143937", 95 | "roles": [], 96 | "emojis": [], 97 | "features": ["INVITE_SPLASH"], 98 | "unavailable": false 99 | } 100 | ``` 101 | 102 | ### Unavailable Guild Object 103 | 104 | A partial [guild](#DOCS_GUILD/guild-object) object. Represents an Offline Guild, or a Guild whose information has not been provided through [Guild Create](#DOCS_GATEWAY/guild-create) events during the Gateway connect. 105 | 106 | ###### Example Unavailable Guild 107 | 108 | ```json 109 | { 110 | "id": "41771983423143937", 111 | "unavailable": true 112 | } 113 | ``` 114 | 115 | ### Guild Embed Object 116 | 117 | ###### Guild Embed Structure 118 | 119 | | Field | Type | Description | 120 | |-------|------|-------------| 121 | | enabled | bool | if the embed is enabled | 122 | | channel_id | snowflake | the embed channel id | 123 | 124 | ###### Example Guild Embed 125 | 126 | ```json 127 | { 128 | "enabled": true, 129 | "channel_id": "41771983444115456" 130 | } 131 | ``` 132 | 133 | ### Guild Member Object 134 | 135 | ###### Guild Member Structure 136 | 137 | | Field | Type | Description | 138 | |-------|------|-------------| 139 | | user | object | [user](#DOCS_USER/user-object) object | 140 | | nick? | string | this users guild nickname (if one is set) | 141 | | roles | array | array of [role](#DOCS_PERMISSIONS/role-object) object id's | 142 | | joined_at | ISO8601 timestamp | when the user joined the guild | 143 | | deaf | bool | if the user is deafened | 144 | | mute | bool | if the user is muted | 145 | 146 | ###### Example Guild Member 147 | 148 | ```json 149 | { 150 | "user": {}, 151 | "nick": "NOT API SUPPORT", 152 | "roles": [], 153 | "joined_at": "2015-04-26T06:26:56.936000+00:00", 154 | "deaf": false, 155 | "mute": false 156 | } 157 | ``` 158 | 159 | ### Integration Object 160 | 161 | ###### Integration Structure 162 | 163 | | Field | Type | Description | 164 | |-------|------|-------------| 165 | | id | snowflake | integration id | 166 | | name | string | integration name | 167 | | type | string | integration type (twitch, youtube, etc) | 168 | | enabled | bool | is this integration enabled | 169 | | syncing | bool | is this integration syncing | 170 | | role_id | snowflake | id that this integration uses for "subscribers" | 171 | | expire_behavior | integer | the behavior of expiring subscribers | 172 | | expire_grace_period | integer | the grace period before expiring subscribers | 173 | | user | [user](#DOCS_USER/user-object) object | user for this integration | 174 | | account | [account](#DOCS_GUILD/integration-account-object) object | integration account information | 175 | | synced_at | ISO8601 timestamp | when this integration was last synced | 176 | 177 | ### Integration Account Object 178 | 179 | ###### Integration Account Structure 180 | 181 | | Field | Type | Description | 182 | |-------|------|-------------| 183 | | id | string | id of the account | 184 | | name | string | name of the account | 185 | 186 | ### Emoji Object 187 | 188 | ###### Emoji Structure 189 | 190 | | Field | Type | Description | 191 | |-------|------|-------------| 192 | | id | snowflake | emoji id | 193 | | name | string | emoji name | 194 | | roles | array of [role object](#DOCS_PERMISSIONS/role-object) ids | roles this emoji is active for | 195 | | require_colons | bool | whether this emoji must be wrapped in colons | 196 | | managed | bool | whether this emoji is managed | 197 | 198 | ### Ban Object 199 | 200 | ###### Ban Structure 201 | 202 | | Field | Type | Description | 203 | |-------|------|-------------| 204 | | reason | ?string | the reason for the ban | 205 | | user | [user](#DOCS_USER/user-object) object | the banned user | 206 | 207 | ###### Example Ban 208 | 209 | ```json 210 | { 211 | "reason": "mentioning b1nzy", 212 | "user": { 213 | "username": "Mason", 214 | "discriminator": "9999", 215 | "id": "53908099506183680", 216 | "avatar": "a_bab14f271d565501444b2ca3be944b25" 217 | } 218 | } 219 | ``` 220 | 221 | 222 | ## Create Guild % POST /guilds 223 | 224 | Create a new guild. Returns a [guild](#DOCS_GUILD/guild-object) object on success. Fires a [Guild Create](#DOCS_GATEWAY/guild-create) Gateway event. 225 | 226 | >warn 227 | > By default this endpoint is limited to 10 active guilds. These limits are raised for whitelisted [GameBridge](#DOCS_GAMEBRDIGE) applications. 228 | 229 | ###### JSON Params 230 | 231 | | Field | Type | Description | 232 | |-------|------|-------------| 233 | | name | string | name of the guild (2-100 characters) | 234 | | region | string | {voice_region.id} for voice | 235 | | icon | string | base64 128x128 jpeg image for the guild icon | 236 | | verification_level | integer | guild verification level | 237 | | default\_message\_notifications | integer | default message [notifications setting](#DOCS_GUILD/default-message-notification-level) | 238 | | roles | array of [role](#DOCS_PERMISSIONS/role-object) objects | new guild roles | 239 | | channels | array of partial [channel](#DOCS_CHANNEL/channel-object) objects | new guild's channels | 240 | 241 | ###### Example Partial Channel Object 242 | 243 | ```json 244 | { 245 | "name": "naming-things-is-hard", 246 | "type": 0 247 | } 248 | ``` 249 | 250 | >info 251 | > If roles are specified, the required `id` field within each role object is an integer placeholder, and will be replaced by the API upon consumption. Its purpose is to allow you to [overwrite](#DOCS_CHANNEL/overwrite-object) a role's permissions in a channel when also passing in channels with the channels array. 252 | 253 | ## Get Guild % GET /guilds/{guild.id#DOCS_GUILD/guild-object} 254 | 255 | Returns the [guild](#DOCS_GUILD/guild-object) object for the given id. 256 | 257 | ## Modify Guild % PATCH /guilds/{guild.id#DOCS_GUILD/guild-object} 258 | 259 | Modify a guild's settings. Returns the updated [guild](#DOCS_GUILD/guild-object) object on success. Fires a [Guild Update](#DOCS_GATEWAY/guild-update) Gateway event. 260 | 261 | >info 262 | > All parameters to this endpoint are optional 263 | 264 | ###### JSON Params 265 | 266 | | Field | Type | Description | 267 | |-------|------|-------------| 268 | | name | string | guild name | 269 | | region | string | guild {voice_region.id} | 270 | | verification_level | integer | guild verification level | 271 | | default\_message\_notifications | integer | default message [notifications setting](#DOCS_GUILD/default-message-notification-level) | 272 | | afk\_channel\_id | snowflake | id for afk channel | 273 | | afk_timeout | integer | afk timeout in seconds | 274 | | icon | string | base64 128x128 jpeg image for the guild icon | 275 | | owner_id | snowflake | user id to transfer guild ownership to (must be owner) | 276 | | splash | string | base64 128x128 jpeg image for the guild splash (VIP only) | 277 | 278 | ## Delete Guild % DELETE /guilds/{guild.id#DOCS_GUILD/guild-object} 279 | 280 | Delete a guild permanently. User must be owner. Returns `204 No Content` on success. Fires a [Guild Delete](#DOCS_GATEWAY/guild-delete) Gateway event. 281 | 282 | ## Get Guild Channels % GET /guilds/{guild.id#DOCS_GUILD/guild-object}/channels 283 | 284 | Returns a list of guild [channel](#DOCS_CHANNEL/channel-object) objects. 285 | 286 | ## Create Guild Channel % POST /guilds/{guild.id#DOCS_GUILD/guild-object}/channels 287 | 288 | Create a new [channel](#DOCS_CHANNEL/channel-object) object for the guild. Requires the 'MANAGE_CHANNELS' permission. Returns the new [channel](#DOCS_CHANNEL/channel-object) object on success. Fires a [Channel Create](#DOCS_GATEWAY/channel-create) Gateway event. 289 | 290 | >info 291 | > All parameters for this endpoint are optional excluding 'name' 292 | 293 | ###### JSON Params 294 | 295 | | Field | Type | Description | 296 | |-------|------|-------------| 297 | | name | string | channel name (2-100 characters) | 298 | | type | string | "voice" or "text" | 299 | | bitrate | integer | the bitrate (in bits) of the voice channel (voice only) | 300 | | user_limit | integer | the user limit of the voice channel (voice only) | 301 | | permission_overwrites | an array of [overwrite](#DOCS_CHANNEL/overwrite-object) objects | the channel's permission overwrites | 302 | 303 | ## Modify Guild Channel Positions % PATCH /guilds/{guild.id#DOCS_GUILD/guild-object}/channels 304 | 305 | Modify the positions of a set of [channel](#DOCS_CHANNEL/channel-object) objects for the guild. Requires 'MANAGE_CHANNELS' permission. Returns a 204 empty response on success. Fires multiple [Channel Update](#DOCS_GATEWAY/channel-update) Gateway events. 306 | 307 | >info 308 | > Only channels to be modified are required, with the minimum being a swap between at least two channels. 309 | 310 | This endpoint takes a JSON array of parameters in the following format: 311 | 312 | ###### JSON Params 313 | 314 | | Field | Type | Description | 315 | |-------|------|-------------| 316 | | id | snowflake | channel id | 317 | | position | integer | sorting position of the channel | 318 | 319 | ## Get Guild Member % GET /guilds/{guild.id#DOCS_GUILD/guild-object}/members/{user.id#DOCS_USER/user-object} 320 | 321 | Returns a [guild member](#DOCS_GUILD/guild-member-object) object for the specified user. 322 | 323 | ## List Guild Members % GET /guilds/{guild.id#DOCS_GUILD/guild-object}/members 324 | 325 | Returns a list of [guild member](#GUILD/guild-member-object) objects that are members of the guild. 326 | 327 | >info 328 | > All parameters to this endpoint are optional 329 | 330 | ###### Query String Params 331 | 332 | | Field | Type | Description | Default | 333 | |-------|------|-------------|---------| 334 | | limit | integer | max number of members to return (1-1000) | 1 | 335 | | after | snowflake | the highest user id in the previous page | 0 | 336 | 337 | ## Add Guild Member % PUT /guilds/{guild.id#DOCS_GUILD/guild-object}/members/{user.id#DOCS_USER/user-object} 338 | 339 | Adds a user to the guild, provided you have a valid oauth2 access token for the user with the `guilds.join` scope. Returns a 201 Created with the [guild member](#DOCS_GUILD/guild-member-object) as the body. Fires a [Guild Member Add](#DOCS_GATEWAY/guild-member-add) Gateway event. Requires the bot to have the `CREATE_INSTANT_INVITE` permission. 340 | 341 | >info 342 | > All parameters to this endpoint except for `access_token` are optional. 343 | 344 | ###### JSON Params 345 | 346 | | Field | Type | Description | Permission | 347 | |-------|------|-------------|------------| 348 | | access_token | string | an oauth2 access token granted with the `guilds.join` to the bot's application for the user you want to add to the guild | | 349 | | nick | string | value to set users nickname to | MANAGE_NICKNAMES | 350 | | roles | array | array of roles the member is assigned | MANAGE_ROLES | 351 | | mute | bool | if the user is muted | MUTE_MEMBERS | 352 | | deaf | bool | if the user is deafened | DEAFEN_MEMBERS | 353 | 354 | ## Modify Guild Member % PATCH /guilds/{guild.id#DOCS_GUILD/guild-object}/members/{user.id#DOCS_USER/user-object} 355 | 356 | Modify attributes of a [guild member](#DOCS_GUILD/guild-member-object). Returns a 204 empty response on success. Fires a [Guild Member Update](#DOCS_GATEWAY/guild-member-update) Gateway event. 357 | 358 | >info 359 | > All parameters to this endpoint are optional. When moving members to channels, the API user 360 | > _must_ have permissions to both connect to the channel and have the MOVE_MEMBERS permission. 361 | 362 | ###### JSON Params 363 | 364 | | Field | Type | Description | Permission | 365 | |-------|------|-------------|------------| 366 | | nick | string | value to set users nickname to | MANAGE_NICKNAMES | 367 | | roles | array | array of role ids the member is assigned | MANAGE_ROLES | 368 | | mute | bool | if the user is muted | MUTE_MEMBERS | 369 | | deaf | bool | if the user is deafened | DEAFEN_MEMBERS | 370 | | channel_id | snowflake | id of channel to move user to (if they are connected to voice) | MOVE_MEMBERS | 371 | 372 | ## Modify Current User's Nick % PATCH /guilds/{guild.id#DOCS_GUILD/guild-object}/members/@me/nick 373 | 374 | Modifies the nickname of the current user in a guild. Returns a 200 with the nickname on success. Fires a [Guild Member Update](#DOCS_GATEWAY/guild-member-update) Gateway event. 375 | 376 | ###### JSON Params 377 | 378 | | Field | Type | Description | Permission | 379 | |-------|------|-------------|------------| 380 | | nick | string | value to set users nickname to | CHANGE_NICKNAME | 381 | 382 | ## Add Guild Member Role % PUT /guilds/{guild.id#DOCS_GUILD/guild-object}/members/{user.id#DOCS_USER/user-object}/roles/{role.id#DOCS_PERMISSIONS/role-object} 383 | 384 | Adds a role to a [guild member](#DOCS_GUILD/guild-member-object). Requires the 'MANAGE_ROLES' permission. Returns a 204 empty response on success. Fires a [Guild Member Update](#DOCS_GATEWAY/guild-member-update) Gateway event. 385 | 386 | ## Remove Guild Member Role % DELETE /guilds/{guild.id#DOCS_GUILD/guild-object}/members/{user.id#DOCS_USER/user-object}/roles/{role.id#DOCS_PERMISSIONS/role-object} 387 | 388 | Removes a role from a [guild member](#DOCS_GUILD/guild-member-object). Requires the 'MANAGE_ROLES' permission. Returns a 204 empty response on success. Fires a [Guild Member Update](#DOCS_GATEWAY/guild-member-update) Gateway event. 389 | 390 | ## Remove Guild Member % DELETE /guilds/{guild.id#DOCS_GUILD/guild-object}/members/{user.id#DOCS_USER/user-object} 391 | 392 | Remove a member from a guild. Requires 'KICK_MEMBERS' permission. Returns a 204 empty response on success. Fires a [Guild Member Remove](#DOCS_GATEWAY/guild-member-remove) Gateway event. 393 | 394 | ## Get Guild Bans % GET /guilds/{guild.id#DOCS_GUILD/guild-object}/bans 395 | 396 | Returns a list of [ban](#DOCS_GUILD/ban-object) objects for the users banned from this guild. Requires the 'BAN_MEMBERS' permission. 397 | 398 | ## Create Guild Ban % PUT /guilds/{guild.id#DOCS_GUILD/guild-object}/bans/{user.id#DOCS_USER/user-object} 399 | 400 | Create a guild ban, and optionally delete previous messages sent by the banned user. Requires the 'BAN_MEMBERS' permission. Returns a 204 empty response on success. Fires a [Guild Ban Add](#DOCS_GATEWAY/guild-ban-add) Gateway event. 401 | 402 | ###### JSON Params 403 | 404 | | Field | Type | Description | 405 | |-------|------|-------------| 406 | | delete-message-days | integer | number of days to delete messages for (0-7) | 407 | 408 | ## Remove Guild Ban % DELETE /guilds/{guild.id#DOCS_GUILD/guild-object}/bans/{user.id#DOCS_USER/user-object} 409 | 410 | Remove the ban for a user. Requires the 'BAN_MEMBERS' permissions. Returns a 204 empty response on success. Fires a [Guild Ban Remove](#DOCS_GATEWAY/guild-ban-remove) Gateway event. 411 | 412 | ## Get Guild Roles % GET /guilds/{guild.id#DOCS_GUILD/guild-object}/roles 413 | 414 | Returns a list of [role](#DOCS_PERMISSIONS/role-object) objects for the guild. Requires the 'MANAGE_ROLES' permission. 415 | 416 | ## Create Guild Role % POST /guilds/{guild.id#DOCS_GUILD/guild-object}/roles 417 | 418 | Create a new [role](#DOCS_PERMISSIONS/role-object) for the guild. Requires the 'MANAGE_ROLES' permission. Returns the new [role](#DOCS_PERMISSIONS/role-object) object on success. Fires a [Guild Role Create](#DOCS_GATEWAY/guild-role-create) Gateway event. All JSON params are optional. 419 | 420 | ###### JSON Params 421 | 422 | | Field | Type | Description | Default | 423 | |-------|------|-------------|---------| 424 | | name | string | name of the role | "new role" | 425 | | permissions | integer | bitwise of the enabled/disabled permissions | @everyone permissions in guild | 426 | | color | integer | RGB color value | 0 | 427 | | hoist | bool | whether the role should be displayed separately in the sidebar | false | 428 | | mentionable | bool | whether the role should be mentionable | false | 429 | 430 | ## Modify Guild Role Positions % PATCH /guilds/{guild.id#DOCS_GUILD/guild-object}/roles 431 | 432 | Modify the positions of a set of [role](#DOCS_PERMISSIONS/role-object) objects for the guild. Requires the 'MANAGE_ROLES' permission. Returns a list of all of the guild's [role](#DOCS_PERMISSIONS/role-object) objects on success. Fires multiple [Guild Role Update](#DOCS_GATEWAY/guild-role-update) Gateway events. 433 | 434 | This endpoint takes a JSON array of parameters in the following format: 435 | 436 | ###### JSON Params 437 | 438 | | Field | Type | Description | 439 | |-------|------|-------------| 440 | | id | snowflake | role | 441 | | position | integer | sorting position of the role | 442 | 443 | ## Modify Guild Role % PATCH /guilds/{guild.id#DOCS_GUILD/guild-object}/roles/{role.id#DOCS_PERMISSIONS/role-object} 444 | 445 | Modify a guild role. Requires the 'MANAGE_ROLES' permission. Returns the updated [role](#DOCS_PERMISSIONS/role-object) on success. Fires a [Guild Role Update](#DOCS_GATEWAY/guild-role-update) Gateway event. 446 | 447 | ###### JSON Params 448 | 449 | | Field | Type | Description | 450 | |-------|------|-------------| 451 | | name | string | name of the role | 452 | | permissions | integer | bitwise of the enabled/disabled permissions | 453 | | color | integer | RGB color value | 454 | | hoist | bool | whether the role should be displayed separately in the sidebar | 455 | | mentionable | bool | whether the role should be mentionable | 456 | 457 | ## Delete Guild Role % DELETE /guilds/{guild.id#DOCS_GUILD/guild-object}/roles/{role.id#DOCS_PERMISSIONS/role-object} 458 | 459 | Delete a guild role. Requires the 'MANAGE_ROLES' permission. Returns a 204 empty response on success. Fires a [Guild Role Delete](#DOCS_GATEWAY/guild-role-delete) Gateway event. 460 | 461 | ## Get Guild Prune Count % GET /guilds/{guild.id#DOCS_GUILD/guild-object}/prune 462 | 463 | Returns an object with one 'pruned' key indicating the number of members that would be removed in a prune operation. Requires the 'KICK_MEMBERS' permission. 464 | 465 | ###### Query String Params 466 | 467 | | Field | Type | Description | 468 | |-------|------|-------------| 469 | | days | integer | number of days to count prune for (1 or more) | 470 | 471 | ## Begin Guild Prune % POST /guilds/{guild.id#DOCS_GUILD/guild-object}/prune 472 | 473 | Begin a prune operation. Requires the 'KICK_MEMBERS' permission. Returns an object with one 'pruned' key indicating the number of members that were removed in the prune operation. Fires multiple [Guild Member Remove](#DOCS_GATEWAY/guild-member-remove) Gateway events. 474 | 475 | ###### Query String Params 476 | 477 | | Field | Type | Description | 478 | |-------|------|-------------| 479 | | days | integer | number of days to prune (1 or more) | 480 | 481 | ## Get Guild Voice Regions % GET /guilds/{guild.id#DOCS_GUILD/guild-object}/regions 482 | 483 | Returns a list of [voice region](#DOCS_VOICE/voice-region-object) objects for the guild. Unlike the similar `/voice` route, this returns VIP servers when the guild is VIP-enabled. 484 | 485 | ## Get Guild Invites % GET /guilds/{guild.id#DOCS_GUILD/guild-object}/invites 486 | 487 | Returns a list of [invite](#DOCS_INVITE/invite-object) objects (with [invite metadata](#DOCS_INVITE/invite-metadata-object)) for the guild. Requires the 'MANAGE_GUILD' permission. 488 | 489 | ## Get Guild Integrations % GET /guilds/{guild.id#DOCS_GUILD/guild-object}/integrations 490 | 491 | Returns a list of [integration](#DOCS_GUILD/integration-object) objects for the guild. Requires the 'MANAGE_GUILD' permission. 492 | 493 | ## Create Guild Integration % POST /guilds/{guild.id#DOCS_GUILD/guild-object}/integrations 494 | 495 | Attach an [integration](#DOCS_GUILD/integration-object) object from the current user to the guild. Requires the 'MANAGE_GUILD' permission. Returns a 204 empty response on success. Fires a [Guild Integrations Update](#DOCS_GATEWAY/guild-integrations-update) Gateway event. 496 | 497 | ###### JSON Params 498 | 499 | | Field | Type | Description | 500 | |-------|------|-------------| 501 | | type | string | the integration type | 502 | | id | snowflake | the integration id | 503 | 504 | ## Modify Guild Integration % PATCH /guilds/{guild.id#DOCS_GUILD/guild-object}/integrations/{integration.id#DOCS_GUILD/integration-object} 505 | 506 | Modify the behavior and settings of a [integration](#DOCS_GUILD/integration-object) object for the guild. Requires the 'MANAGE_GUILD' permission. Returns a 204 empty response on success. Fires a [Guild Integrations Update](#DOCS_GATEWAY/guild-integrations-update) Gateway event. 507 | 508 | ###### JSON Params 509 | 510 | | Field | Type | Description | 511 | |-------|------|-------------| 512 | | expire_behavior | integer | the behavior when an integration subscription lapses (see the [integration](#DOCS_GUILD/integration-object) object documentation) | 513 | | expire\_grace\_period | integer | period (in seconds) where the integration will ignore lapsed subscriptions | 514 | | enable_emoticons | bool | whether emoticons should be synced for this integration (twitch only currently) | 515 | 516 | ## Delete Guild Integration % DELETE /guilds/{guild.id#DOCS_GUILD/guild-object}/integrations/{integration.id#DOCS_GUILD/integration-object} 517 | 518 | Delete the attached [integration](#DOCS_GUILD/integration-object) object for the guild. Requires the 'MANAGE_GUILD' permission. Returns a 204 empty response on success. Fires a [Guild Integrations Update](#DOCS_GATEWAY/guild-integrations-update) Gateway event. 519 | 520 | ## Sync Guild Integration % POST /guilds/{guild.id#DOCS_GUILD/guild-object}/integrations/{integration.id#DOCS_GUILD/integration-object}/sync 521 | 522 | Sync an integration. Requires the 'MANAGE_GUILD' permission. Returns a 204 empty response on success. 523 | 524 | ## Get Guild Embed % GET /guilds/{guild.id#DOCS_GUILD/guild-object}/embed 525 | 526 | Returns the [guild embed](#DOCS_GUILD/guild-embed-object) object. Requires the 'MANAGE_GUILD' permission. 527 | 528 | ## Modify Guild Embed % PATCH /guilds/{guild.id#DOCS_GUILD/guild-object}/embed 529 | 530 | Modify a [guild embed](#DOCS_GUILD/guild-embed-object) object for the guild. All attributes may be passed in with JSON and modified. Requires the 'MANAGE_GUILD' permission. Returns the updated [guild embed](#DOCS_GUILD/guild-embed-object) object. 531 | -------------------------------------------------------------------------------- /docs/resources/Invite.md: -------------------------------------------------------------------------------- 1 | # Invite Resource 2 | 3 | ## Invite Object 4 | 5 | Represents a code that when used, adds a user to a guild. 6 | 7 | ###### Invite Structure 8 | 9 | | Field | Type | Description | 10 | |-------|------|-------------| 11 | | code | string | the invite code (unique ID) | 12 | | guild | partial [guild](#DOCS_GUILD/guild-object) object | the guild this invite is for | 13 | | channel | partial [channel](#DOCS_CHANNEL/channel-object) object | the channel this invite is for | 14 | 15 | ###### Example Invite Object 16 | 17 | ```json 18 | { 19 | "code": "0vCdhLbwjZZTWZLD", 20 | "guild": { 21 | "id": "165176875973476352", 22 | "name": "CS:GO Fraggers Only", 23 | "splash": null, 24 | "icon": null 25 | }, 26 | "channel": { 27 | "id": "165176875973476352", 28 | "name": "illuminati", 29 | "type": 0 30 | } 31 | } 32 | ``` 33 | 34 | ## Invite Metadata Object 35 | 36 | ###### Invite Metadata Structure 37 | 38 | | Field | Type | Description | 39 | |-------|------|-------------| 40 | | inviter | a [user](#DOCS_USER/user-object) object | user who created the invite | 41 | | uses | integer | number of times this invite has been used | 42 | | max_uses | integer | max number of times this invite can be used | 43 | | max_age | integer | duration (in seconds) after which the invite expires | 44 | | temporary | bool | whether this invite only grants temporary membership | 45 | | created_at | ISO8601 timestamp | when this invite was created | 46 | | revoked | bool | whether this invite is revoked | 47 | 48 | ###### Example Invite Metadata 49 | 50 | ```json 51 | { 52 | "inviter": {}, 53 | "uses": 0, 54 | "max_uses": 0, 55 | "max_age": 0, 56 | "temporary": false, 57 | "created_at": "2016-03-31T19:15:39.954000+00:00", 58 | "revoked": false 59 | } 60 | ``` 61 | 62 | ## Get Invite % GET /invites/{invite.code#DOCS_INVITE/invite-object} 63 | 64 | Returns an [invite](#DOCS_INVITE/invite-object) object for the given code. 65 | 66 | ## Delete Invite % DELETE /invites/{invite.code#DOCS_INVITE/invite-object} 67 | 68 | Delete an invite. Requires the `MANAGE_CHANNELS` permission. Returns an [invite](#DOCS_INVITE/invite-object) object on success. 69 | 70 | ## Accept Invite % POST /invites/{invite.code#DOCS_INVITE/invite-object} 71 | 72 | Accept an invite. This requires the `guilds.join` OAuth2 scope to be able to accept invites on behalf of normal users (via an OAuth2 Bearer token). Bot users are disallowed. Returns an [invite](#DOCS_INVITE/invite-object) object on success. 73 | -------------------------------------------------------------------------------- /docs/resources/User.md: -------------------------------------------------------------------------------- 1 | # Users Resource 2 | 3 | Users in Discord are generally considered the base entity. Users can spawn across the entire platform, be members of 4 | guilds, participate in text and voice chat, and much more. Users are separated by a distinction of "bot" vs "normal." Although they are similar, bot users are automated users that are "owned" by another user. Unlike normal users, bot users do 5 | *not* have a limitation on the number of Guilds they can be a part of. 6 | 7 | ## Avatar Data 8 | 9 | Avatar data is a [Data URI scheme](https://en.wikipedia.org/wiki/Data_URI_scheme) that supports JPG, GIF, and PNG formats. An example Data URI format is: 10 | 11 | ``` 12 | data:image/jpeg;base64,BASE64_ENCODED_JPEG_IMAGE_DATA 13 | ``` 14 | 15 | Ensure you use the proper header type (`image/jpeg`, `image/png`, `image/gif`) that matches the image data being provided. 16 | 17 | ## Usernames and Nicknames 18 | 19 | Discord enforces the following restrictions for usernames and nicknames: 20 | 21 | 1. Names can contain most valid unicode characters. We limit some zero-width and non-rendering characters. 22 | 2. Names must be between 2 and 32 characters long. 23 | 3. Names cannot contain the following substrings: '@', '#', ':', '\```'. 24 | 4. Names cannot be: 'discordtag', 'everyone', 'here'. 25 | 5. Names are sanitized and trimmed of leading, trailing, and exessive internal whitespace. 26 | 27 | There are other rules and restrictions not shared here for the sake of spam and abuse mitigation, but the majority of users won't encounter them. It's important to properly handle all error messages returned by Discord when editing or updating names. 28 | 29 | ## User Object 30 | 31 | ###### User Structure 32 | 33 | | Field | Type | Description | Required OAuth2 Scope | 34 | |-------|------|-------------|----| 35 | | id | snowflake | the user's id | identify | 36 | | username | string | the user's username, not unique across the platform | identify | 37 | | discriminator | string | the user's 4-digit discord-tag | identify | 38 | | avatar | string | the user's avatar hash | identify | 39 | | bot | bool | whether the user belongs to an OAuth2 application | identify | 40 | | mfa_enabled | bool | whether the user has two factor enabled on their account | identify | 41 | | verified | bool | whether the email on this account has been verified | email | 42 | | email | string | the user's email | email | 43 | 44 | ###### Example User 45 | 46 | ```json 47 | { 48 | "id": "80351110224678912", 49 | "username": "Nelly", 50 | "discriminator": "1337", 51 | "avatar": "8342729096ea3675442027381ff50dfe", 52 | "verified": true, 53 | "email": "nelly@discordapp.com" 54 | } 55 | ``` 56 | 57 | ## Connection Object 58 | 59 | The connection object that the user has attached. 60 | 61 | ###### Connection Structure 62 | 63 | | Field | Type | Description | 64 | |-------|------|-------------| 65 | | id | string | id of the connection account | 66 | | name | string | the username of the connection account | 67 | | type | string | the service of the connection (twitch, youtube) | 68 | | revoked | bool | whether the connection is revoked | 69 | | integrations | array | an array of partial [server integrations](#DOCS_GUILD/integration-object) | 70 | 71 | ## Get Current User % GET /users/@me 72 | 73 | Returns the [user](#DOCS_USER/user-object) object of the requester's account. For OAuth2, this requires the `identify` scope, which will return the object _without_ an email, and optionally the `email` scope, which returns the object _with_ an email. 74 | 75 | ## Get User % GET /users/{user.id#DOCS_USER/user-object} 76 | 77 | Returns a [user](#DOCS_USER/user-object) object for a given user ID. 78 | 79 | ## Modify Current User % PATCH /users/@me 80 | 81 | Modify the requester's user account settings. Returns a [user](#DOCS_USER/user-object) object on success. 82 | 83 | ###### JSON Params 84 | 85 | | Field | Type | Description | 86 | |-------|------|-------------| 87 | | username | string | users username, if changed may cause the users discriminator to be randomized. | 88 | | avatar | [avatar data](#DOCS_USER/avatar-data) | if passed, modifies the user's avatar | 89 | 90 | ## Get Current User Guilds % GET /users/@me/guilds 91 | 92 | Returns a list of partial [guild](#DOCS_GUILD/guild-object) objects the current user is a member of. Requires the `guilds` OAuth2 scope. 93 | 94 | ###### Example Partial Guild 95 | 96 | ```json 97 | { 98 | "id": "80351110224678912", 99 | "name": "1337 Krew", 100 | "icon": "8342729096ea3675442027381ff50dfe", 101 | "owner": true, 102 | "permissions": 36953089 103 | } 104 | ``` 105 | 106 | >info 107 | > This endpoint returns 100 guilds by default, which is the maximum number of guilds a non-bot user can join. Therefore, pagination is **not needed** for integrations that need to get a list of users' guilds. 108 | 109 | ###### Query String Params 110 | 111 | | Field | Type | Description | Required | Default | 112 | |-------|------|-------------|----------|---------| 113 | | before | snowflake | get guilds before this guild ID | false | absent | 114 | | after | snowflake | get guilds after this guild ID | false | absent | 115 | | limit | integer | max number of guilds to return (1-100) | false | 100 | 116 | 117 | ## Leave Guild % DELETE /users/@me/guilds/{guild.id#DOCS_GUILD/guild-object} 118 | 119 | Leave a guild. Returns a 204 empty response on success. 120 | 121 | ## Get User DMs % GET /users/@me/channels 122 | 123 | Returns a list of [DM channel](#DOCS_CHANNEL/channel-object) objects. 124 | 125 | ## Create DM % POST /users/@me/channels 126 | 127 | Create a new DM channel with a user. Returns a [DM channel](#DOCS_CHANNEL/channel-object) object. 128 | 129 | ###### JSON Params 130 | 131 | | Field | Type | Description | 132 | |-------|------|-------------| 133 | | recipient_id | snowflake | the recipient to open a DM channel with | 134 | 135 | ## Create Group DM % POST /users/@me/channels 136 | 137 | Create a new group DM channel with multiple users. Returns a [DM channel](#DOCS_CHANNEL/channel-object) object. 138 | 139 | >warn 140 | > By default this endpoint is limited to 10 active group DMs. These limits are raised for whitelisted [GameBridge](#DOCS_GAMEBRDIGE) applications. 141 | 142 | ###### JSON Params 143 | 144 | | Field | Type | Description | 145 | |-------|------|-------------| 146 | | access_tokens | array of strings | access tokens of users that have granted your app the `gdm.join` scope | 147 | | nicks | dict | a dictionary of user ids to their respective nicknames | 148 | 149 | ## Get User Connections % GET /users/@me/connections 150 | 151 | Returns a list of [connection](#DOCS_USER/connection-object) objects. Requires the `connections` OAuth2 scope. 152 | -------------------------------------------------------------------------------- /docs/resources/Voice.md: -------------------------------------------------------------------------------- 1 | # Voice Resource 2 | 3 | ## Voice State Object 4 | 5 | Used to represent a user's voice connection status. 6 | 7 | ###### Voice State Structure 8 | 9 | | Field | Type | Description | 10 | |-------|------|-------------| 11 | | guild_id? | snowflake | the guild id this voice state is for | 12 | | channel_id | snowflake | the channel id this user is connected to | 13 | | user_id | snowflake | the user id this voice state is for | 14 | | session_id | string | the session id for this voice state | 15 | | deaf | bool | whether this user is deafened by the server | 16 | | mute | bool | whether this user is muted by the server | 17 | | self_deaf | bool | whether this user is locally deafened | 18 | | self_mute | bool | whether this user is locally muted | 19 | | suppress | bool | whether this user is muted by the current user | 20 | 21 | ###### Example Voice State 22 | 23 | ```json 24 | { 25 | "channel_id": "157733188964188161", 26 | "user_id": "80351110224678912", 27 | "session_id": "90326bd25d71d39b9ef95b299e3872ff", 28 | "deaf": false, 29 | "mute": false, 30 | "self_deaf": false, 31 | "self_mute": true, 32 | "suppress": false 33 | } 34 | ``` 35 | 36 | ## Voice Region 37 | 38 | ###### Voice Region Structure 39 | 40 | | Field | Type | Description | 41 | |-------|------|-------------| 42 | | id | string | unique ID for the region | 43 | | name | string | name of the region | 44 | | sample_hostname | string | an example hostname for the region | 45 | | sample_port | integer | an example port for the region | 46 | | vip | bool | true if this is a vip-only server | 47 | | optimal | bool | true for a single server that is closest to the current user's client | 48 | | deprecated | bool | whether this is a deprecated voice region (avoid switching to these) | 49 | | custom | bool | whether this is a custom voice region (used for events/etc) | 50 | 51 | ## List Voice Regions % GET /voice/regions 52 | 53 | Returns an array of [voice region](#DOCS_VOICE/voice-region-object) objects that can be used when creating servers. 54 | -------------------------------------------------------------------------------- /docs/resources/Webhook.md: -------------------------------------------------------------------------------- 1 | # Webhook Resource 2 | 3 | Webhooks are a low-effort way to post messages to channels in Discord. They do not require a bot user or authentication to use. 4 | 5 | ## Webhook Object 6 | 7 | Used to represent a webhook. 8 | 9 | ###### Webhook Structure 10 | 11 | | Field | Type | Description | 12 | |-------|------|-------------| 13 | | id | snowflake | the id of the webhook | 14 | | guild_id? | snowflake | the guild id this webhook is for | 15 | | channel_id | snowflake | the channel id this webhook is for | 16 | | user? | [user](#DOCS_USER/user-object) object | the user this webhook was created by (not returned when getting a webhook with its token) | 17 | | name | ?string | the default name of the webhook | 18 | | avatar | ?string | the default avatar of the webhook | 19 | | token | string | the secure token of the webhook | 20 | 21 | ###### Example Webhook 22 | 23 | ```json 24 | { 25 | "name": "test webhook", 26 | "channel_id": "199737254929760256", 27 | "token": "3d89bb7572e0fb30d8128367b3b1b44fecd1726de135cbe28a41f8b2f777c372ba2939e72279b94526ff5d1bd4358d65cf11", 28 | "avatar": null, 29 | "guild_id": "199737254929760256", 30 | "id": "223704706495545344", 31 | "user": { 32 | "username": "test", 33 | "discriminator": "7479", 34 | "id": "190320984123768832", 35 | "avatar": "b004ec1740a63ca06ae2e14c5cee11f3" 36 | } 37 | } 38 | ``` 39 | 40 | ## Create Webhook % POST /channels/{channel.id#DOCS_CHANNEL/channel-object}/webhooks 41 | 42 | Create a new webhook. Returns a [webhook](#DOCS_WEBHOOK/webhook-object) object on success. 43 | 44 | ###### JSON Params 45 | 46 | | Field | Type | Description | 47 | |-------|------|-------------| 48 | | name | string | name of the webhook (2-32 characters) | 49 | | avatar | [avatar data](#DOCS_USER/avatar-data) string | base64 128x128 jpeg image for the default webhook avatar | 50 | 51 | ## Get Channel Webhooks % GET /channels/{channel.id#DOCS_CHANNEL/channel-object}/webhooks 52 | 53 | Returns a list of channel [webhook](#DOCS_WEBHOOK/webhook-object) objects. 54 | 55 | ## Get Guild Webhooks % GET /guilds/{guild.id#DOCS_GUILD/guild-object}/webhooks 56 | 57 | Returns a list of guild [webhook](#DOCS_WEBHOOK/webhook-object) objects. 58 | 59 | ## Get Webhook % GET /webhooks/{webhook.id#DOCS_WEBHOOK/webhook-object} 60 | 61 | Returns the new [webhook](#DOCS_WEBHOOK/webhook-object) object for the given id. 62 | 63 | ## Get Webhook with Token % GET /webhooks/{webhook.id#DOCS_WEBHOOK/webhook-object}/{webhook.token#DOCS_WEBHOOK/webhook-object} 64 | 65 | Same as above, except this call does not require authentication and returns no user in the webhook object. 66 | 67 | ## Modify Webhook % PATCH /webhooks/{webhook.id#DOCS_WEBHOOK/webhook-object} 68 | 69 | Modify a webhook. Returns the updated [webhook](#DOCS_WEBHOOK/webhook-object) object on success. 70 | 71 | >info 72 | > All parameters to this endpoint are optional 73 | 74 | ###### JSON Params 75 | 76 | | Field | Type | Description | 77 | |-------|------|-------------| 78 | | name | string | the default name of the webhook | 79 | | avatar | [avatar data](#DOCS_USER/avatar-data) string | base64 128x128 jpeg image for the default webhook avatar | 80 | 81 | ## Modify Webhook with Token % PATCH /webhooks/{webhook.id#DOCS_WEBHOOK/webhook-object}/{webhook.token#DOCS_WEBHOOK/webhook-object} 82 | 83 | Same as above, except this call does not require authentication and returns no user in the webhook object. 84 | 85 | ## Delete Webhook % DELETE /webhooks/{webhook.id#DOCS_WEBHOOK/webhook-object} 86 | 87 | Delete a webhook permanently. User must be owner. Returns a 204 NO CONTENT response on success. 88 | 89 | ## Delete Webhook with Token % DELETE /webhooks/{webhook.id#DOCS_WEBHOOK/webhook-object}/{webhook.token#DOCS_WEBHOOK/webhook-object} 90 | 91 | Same as above, except this call does not require authentication. 92 | 93 | ## Execute Webhook % POST /webhooks/{webhook.id#DOCS_WEBHOOK/webhook-object}/{webhook.token#DOCS_WEBHOOK/webhook-object} 94 | 95 | >warn 96 | > This endpoint supports both JSON and form data bodies. It does require multipart/form-data requests instead of the normal JSON request type when uploading files. Make sure you set your `Content-Type` to `multipart/form-data` if you're doing that. Note that in that case, the `embeds` field cannot be used, but you can pass an url-encoded JSON body as a form value for `payload_json`. 97 | 98 | ###### Querystring Params 99 | 100 | | Field | Type | Description | Required | 101 | |-------|------|-------------|----------| 102 | | wait | bool | waits for server confirmation of message send before response, and returns the created message body (defaults to `false`; when `false` a message that is not saved does not return an error) | false | 103 | 104 | ###### JSON/Form Params 105 | 106 | | Field | Type | Description | Required | 107 | |-------|------|-------------|----------| 108 | | content | string | the message contents (up to 2000 characters) | one of content, file, embeds | 109 | | username | string | override the default username of the webhook | false | 110 | | avatar_url | string | override the default avatar of the webhook | false | 111 | | tts | bool | true if this is a TTS message | false | 112 | | file | file contents | the contents of the file being sent | one of content, file, embeds | 113 | | embeds | array of [embed](#DOCS_CHANNEL/embed-object) objects | embedded `rich` content | one of content, file, embeds | 114 | 115 | >info 116 | > For the webhook embed objects, you can set every field except `type` (it will be `rich` regardless of if you try to set it), `provider`, `video`, and any `height`, `width`, or `proxy_url` values for images. 117 | 118 | ## Execute Slack-Compatible Webhook % POST /webhooks/{webhook.id#DOCS_WEBHOOK/webhook-object}/{webhook.token#DOCS_WEBHOOK/webhook-object}/slack 119 | 120 | ###### Querystring Params 121 | 122 | | Field | Type | Description | Required | 123 | |-------|------|-------------|----------| 124 | | wait | bool | waits for server confirmation of message send before response (defaults to `true`; when `false` a message that is not saved does not return an error) | false | 125 | 126 | Refer to [Slack's documentation](https://api.slack.com/incoming-webhooks) for more information. We do not support Slack's `channel`, `icon_emoji`, `mrkdwn`, or `mrkdwn_in` properties. 127 | 128 | ## Execute GitHub-Compatible Webhook % POST /webhooks/{webhook.id#DOCS_WEBHOOK/webhook-object}/{webhook.token#DOCS_WEBHOOK/webhook-object}/github 129 | 130 | ###### Querystring Params 131 | 132 | | Field | Type | Description | Required | 133 | |-------|------|-------------|----------| 134 | | wait | bool | waits for server confirmation of message send before response (defaults to `true`; when `false` a message that is not saved does not return an error) | false | 135 | 136 | Add a new webhook to your GitHub repo (in the repo's settings), and use this endpoint as the "Payload URL." You can choose what events your Discord channel receives by choosing the "Let me select individual events" option and selecting individual events for the new webhook you're configuring. 137 | -------------------------------------------------------------------------------- /docs/topics/GameBridge.md: -------------------------------------------------------------------------------- 1 | # GameBridge 2 | 3 | ## Private Beta FYI 4 | 5 | For now GameBridge is in private beta. If you're interested in trying out Discord to power your game please [sign up over here](https://discordapp.com/gamebridge). 6 | 7 | ## About the GameBridge SDK 8 | 9 | GameBridge is offered as an SDK to embed within your game. This way you can offer features to all your users regardless of whether they have Discord running on their computer or not. For users who have Discord installed, GameBridge will detect this and use their real Discord account. For users who do not have Discord installed, GameBridge will create a guest account as part of its silent initialization. 10 | 11 | The GameBridge SDK is a headless, optimized version of [Discord's RPC](#DOCS_RPC) available to your game inside of a DLL. Once you start the SDK it will spin up an RPC server and tell you what port to connect to. 12 | 13 | ## Using GameBridge 14 | 15 | The GameBridge SDK is still baking. If you've signed up for the private beta, we will reach out to you with some beta goodness. In the meantime, if you've requested access you can develop against a Discord client's [RPC server](#DOCS_RPC) to start building your integration now. 16 | -------------------------------------------------------------------------------- /docs/topics/Gateway.md: -------------------------------------------------------------------------------- 1 | # Gateways 2 | 3 | Gateways are Discord's form of real-time communication over secure websockets. Clients will receive events and data over the gateway they are connected to and send data over the REST API. For information about connecting to a gateway see the [Connecting](#DOCS_GATEWAY/connecting) section. The API for interacting with Gateways is complex and fairly unforgiving, therefore its highly recommended you read _all_ of the following documentation before writing a custom implementation. 4 | 5 | ## Get Gateway % GET /gateway 6 | 7 | Returns an object with a single valid WSS URL, which the client can use as a basis for [Connecting](#DOCS_GATEWAY/connecting). Clients **should** cache this value and only call this endpoint to retrieve a new URL if they are unable to properly establish a connection using the cached version of the URL. 8 | 9 | >info 10 | > This endpoint does not require any authentication. 11 | 12 | ###### Example Response 13 | 14 | ```json 15 | { 16 | "url": "wss://gateway.discord.gg/" 17 | } 18 | ``` 19 | 20 | ## Get Gateway Bot % GET /gateway/bot 21 | 22 | Returns an object with the same information as [Get Gateway](#DOCS_GATEWAY/get-gateway), plus a `shards` key, containing the recommended number of [shards](#DOCS_GATEWAY/sharding) to connect with (as an integer). Bots that want to dynamically/automatically spawn shard processes should use this endpoint to determine the number of processes to run. This route should be called once when starting up numerous shards, with the response being cached and passed to all sub-shards/processes. Unlike the [Get Gateway](#DOCS_GATEWAY/get-gateway), this route should not be cached for extended periods of time as the value is not guaranteed to be the same per-call, and changes as the bot joins/leaves guilds. 23 | 24 | >warn 25 | > This endpoint requires authentication using a valid bot token. 26 | 27 | ###### Example Response 28 | 29 | ```json 30 | { 31 | "url": "wss://gateway.discord.gg/", 32 | "shards": 9 33 | } 34 | ``` 35 | 36 | ## Gateway Protocol Versions 37 | 38 | The Discord Gateway has a versioning system which is separate from the core APIs. The documentation herein is only for the latest version in the following table, unless otherwise specified. 39 | 40 | >danger 41 | >Gateway versions below v6 will be discontinued on **October 16, 2017**. 42 | 43 | | Version | Status | 44 | |---------|----------------| 45 | | 6 | In Service | 46 | | 5 | Deprecated | 47 | | 4 | Deprecated | 48 | 49 | ## Gateway OP Codes/Payloads 50 | 51 | ###### Gateway Payload Structure 52 | 53 | | Field | Type | Description | Present | 54 | |-------|------|-------------|---------| 55 | | op | integer | opcode for the payload | Always | 56 | | d | ?mixed (object, integer, bool) | event data | Always | 57 | | s | integer | sequence number, used for resuming sessions and heartbeats | Only for OP 0 | 58 | | t | string | the event name for this payload | Only for OP 0 | 59 | 60 | ###### Gateway OP Codes 61 | 62 | | Code | Name | Description | 63 | |------|------|-------------| 64 | | 0 | Dispatch | dispatches an event | 65 | | 1 | Heartbeat | used for ping checking | 66 | | 2 | Identify | used for client handshake | 67 | | 3 | Status Update | used to update the client status | 68 | | 4 | Voice State Update | used to join/move/leave voice channels | 69 | | 5 | Voice Server Ping | used for voice ping checking | 70 | | 6 | Resume | used to resume a closed connection | 71 | | 7 | Reconnect | used to tell clients to reconnect to the gateway | 72 | | 8 | Request Guild Members | used to request guild members | 73 | | 9 | Invalid Session | used to notify client they have an invalid session id | 74 | | 10 | Hello | sent immediately after connecting, contains heartbeat and server debug information | 75 | | 11 | Heartbeat ACK | sent immediately following a client heartbeat that was received | 76 | 77 | ### Gateway Dispatch 78 | 79 | Used by the gateway to notify the client of events. 80 | 81 | ###### Example Gateway Dispatch 82 | 83 | ```json 84 | { 85 | "op": 0, 86 | "d": {}, 87 | "s": 42, 88 | "t": "GATEWAY_EVENT_NAME" 89 | } 90 | ``` 91 | 92 | ### Gateway Heartbeat 93 | 94 | Used to maintain an active gateway connection. Must be sent every `heartbeat_interval` milliseconds after the [Hello](#DOCS_GATEWAY/gateway-hello) payload is received. Note that this interval already has room for error, and that client implementations do not need to send a heartbeat faster than what's specified. The inner `d` key must be set to the last seq (`s`) received by the client. If none has yet been received you should send `null` (you cannot send a heartbeat before authenticating, however). 95 | 96 | >info 97 | > It is worth noting that in the event of a service outage where you stay connected to the gateway, you should continue to heartbeat and receive ACKs. The gateway will eventually respond and issue a session once it is able to. 98 | 99 | ###### Example Gateway Heartbeat 100 | 101 | ```json 102 | { 103 | "op": 1, 104 | "d": 251 105 | } 106 | ``` 107 | 108 | ### Gateway Heartbeat ACK 109 | 110 | Used for the client to maintain an active gateway connection. Sent by the server after receiving a [Gateway Heartbeat](#DOCS_GATEWAY/gateway-heartbeat) 111 | 112 | ###### Example Gateway Heartbeat ACK 113 | 114 | ```json 115 | { 116 | "op": 11 117 | } 118 | ``` 119 | 120 | ### Gateway Hello 121 | 122 | Sent on connection to the websocket. Defines the heartbeat interval that the client should heartbeat to. 123 | 124 | ###### Gateway Hello Structure 125 | 126 | | Field | Type | Description | 127 | |-------|------|-------------| 128 | | heartbeat_interval | integer | the interval (in milliseconds) the client should heartbeat with | 129 | | _trace | array of strings | used for debugging, array of servers connected to | 130 | 131 | ###### Example Gateway Hello 132 | 133 | ```json 134 | { 135 | "heartbeat_interval": 45000, 136 | "_trace": ["discord-gateway-prd-1-99"] 137 | } 138 | ``` 139 | 140 | ### Gateway Identify 141 | 142 | Used to trigger the initial handshake with the gateway. 143 | 144 | ###### Gateway Identify Structure 145 | 146 | | Field | Type | Description | 147 | |-------|------|-------------| 148 | | token | string | authentication token | 149 | | properties | object | [connection properties](#DOCS_GATEWAY/gateway-identify-gateway-identify-connection-properties) | 150 | | compress | bool | whether this connection supports compression of packets | 151 | | large_threshold | integer | value between 50 and 250, total number of members where the gateway will stop sending offline members in the guild member list | 152 | | shard | array of two integers (shard_id, num_shards) | used for [Guild Sharding](#DOCS_GATEWAY/sharding) | 153 | | presence | [gateway status update](#DOCS_GATEWAY/gateway-status-update) object | presence structure for initial presence information | 154 | 155 | ###### Gateway Identify Connection Properties 156 | 157 | | Field | Type | Description | 158 | | ----- | ---- | ----------- | 159 | | $os | string | your operating system | 160 | | $browser | string | your library name | 161 | | $device | string | your library name 162 | 163 | ###### Example Gateway Identify 164 | 165 | ```json 166 | { 167 | "token": "my_token", 168 | "properties": { 169 | "$os": "linux", 170 | "$browser": "disco", 171 | "$device": "disco" 172 | }, 173 | "compress": true, 174 | "large_threshold": 250, 175 | "shard": [1, 10], 176 | "presence": { 177 | "game": { 178 | "name": "Cards Against Humanity" 179 | }, 180 | "status": "dnd", 181 | "since": 91879201, 182 | "afk": false 183 | } 184 | } 185 | ``` 186 | 187 | ### Gateway Reconnect 188 | 189 | Used to tell clients to reconnect to the gateway. Clients should immediately reconnect, and use the resume payload on the gateway. 190 | 191 | ### Gateway Request Guild Members 192 | 193 | Used to request offline members for a guild. When initially connecting, the gateway will only send offline members if a guild has less than the `large_threshold` members (value in the [Gateway Identify](#DOCS_GATEWAY/gateway-identify)). If a client wishes to receive additional members, they need to explicitly request them via this operation. The server will send [Guild Members Chunk](#DOCS_GATEWAY/guild-members-chunk) events in response with up to 1000 members per chunk until all members that match the request have been sent. 194 | 195 | ###### Gateway Request Guild Members Structure 196 | 197 | | Field | Type | Description | 198 | |-------|------|-------------| 199 | | guild_id | snowflake | id of the guild to get offline members for | 200 | | query | string | string that username starts with, or an empty string to return all members | 201 | | limit | integer | maximum number of members to send or 0 to request all members matched | 202 | 203 | ###### Example Gateway Request Guild Members 204 | 205 | ```json 206 | { 207 | "guild_id": "41771983444115456", 208 | "query": "", 209 | "limit": 0 210 | } 211 | ``` 212 | 213 | ### Gateway Resume 214 | 215 | Used to replay missed events when a disconnected client resumes. 216 | 217 | ###### Gateway Resume Structure 218 | 219 | | Field | Type | Description | 220 | |-------|------|-------------| 221 | | token | string | session token | 222 | | session_id | string | session id | 223 | | seq | integer | last sequence number received | 224 | 225 | ###### Example Gateway Resume 226 | 227 | ```json 228 | { 229 | "token": "randomstring", 230 | "session_id": "evenmorerandomstring", 231 | "seq": 1337 232 | } 233 | ``` 234 | 235 | ### Gateway Status Update 236 | 237 | Sent by the client to indicate a presence or status update. 238 | 239 | ###### Gateway Status Update Structure 240 | 241 | | Field | Type | Description | 242 | |-------|------|-------------| 243 | | since | ?integer | unix time (in milliseconds) of when the client went idle, or null if the client is not idle | 244 | | game | ?[game](#DOCS_GATEWAY/game-object) object | null, or the user's new activity | 245 | | status | string | the user's new [status](#DOCS_GATEWAY/status-types) | 246 | | afk | bool | whether or not the client is afk | 247 | 248 | ###### Status Types 249 | 250 | | Status | Description | 251 | | ------ | ----------- | 252 | | online | Online | 253 | | dnd | Do Not Disturb | 254 | | idle | AFK | 255 | | invisible | Invisible and shown as offline | 256 | | offline | Offline | 257 | 258 | ###### Example Gateway Status Update 259 | 260 | ```json 261 | { 262 | "since": 91879201, 263 | "game": { 264 | "name": "Save the Oxford Comma" 265 | }, 266 | "status": "online", 267 | "afk": false 268 | } 269 | ``` 270 | 271 | ### Gateway Voice State Update 272 | 273 | Sent when a client wants to join, move, or disconnect from a voice channel. 274 | 275 | ###### Gateway Voice State Update Structure 276 | 277 | | Field | Type | Description | 278 | |-------|------|-------------| 279 | | guild_id | snowflake | id of the guild | 280 | | channel_id | ?snowflake | id of the voice channel client wants to join (null if disconnecting) | 281 | | self_mute | bool | is the client muted | 282 | | self_deaf | bool | is the client deafened | 283 | 284 | ###### Example Gateway Voice State Update 285 | 286 | ```json 287 | { 288 | "guild_id": "41771983423143937", 289 | "channel_id": "127121515262115840", 290 | "self_mute": false, 291 | "self_deaf": false 292 | } 293 | ``` 294 | 295 | ### Gateway Invalid Session 296 | 297 | Sent to indicate one of at least three different situations: 298 | - the gateway could not initialize a session after receiving an [OP 2 Identify](#DOCS_GATEWAY/gateway-identify) 299 | - the gateway could not resume a previous session after receiving an [OP 6 Resume](#DOCS_GATEWAY/gateway-resume) 300 | - the gateway has invalidated an active session and is requesting client action 301 | 302 | The inner `d` key is a boolean that indicates whether the session may be resumable. See [Connecting](#DOCS_GATEWAY/connecting) and [Resuming](#DOCS_GATEWAY/resuming) for more information. 303 | 304 | ###### Example Gateway Invalid Session 305 | 306 | ```json 307 | { 308 | "op": 9, 309 | "d": false 310 | } 311 | ``` 312 | 313 | ## Connecting 314 | 315 | The first step in establishing connectivity to the gateway is requesting a valid websocket endpoint from the API. This can be done through either the [Get Gateway](#DOCS_GATEWAY/get-getway) or the [Get Gateway Bot](#DOCS_GATEWAY/get-getway-bot) endpoints. 316 | 317 | With the resulting payload, you can now open a websocket connection to the "url" (or endpoint) specified. Generally, it is a good idea to explicitly pass the gateway version and encoding (see the url params table below) as URL parameters (e.g. from our example we may connect to `wss://gateway.discord.gg/?v=6&encoding=json`). 318 | 319 | Once connected, the client should immediately receive an [OP 10 Hello](#DOCS_GATEWAY/gateway-hello) payload, with information on the connection's heartbeat interval. The client should now begin sending [OP 1 Heartbeat](#DOCS_GATEWAY/gateway-heartbeat) payloads every `heartbeat_interval` milliseconds, until the connection is eventually closed or terminated. Clients can detect zombied or failed connections by listening for [OP 11 Heartbeat ACK](#DOCS_GATEWAY/gateway-heartbeat-ack). If a client does not receive a heartbeat ack between its attempts at sending heartbeats, it should immediately terminate the connection with a non 1000 close code, reconnect, and attempt to resume. 320 | 321 | Next, the client is expected to send an [OP 2 Identify](#DOCS_GATEWAY/gateway-identify) _or_ [OP 6 Resume](#DOCS_GATEWAY/gateway-resume) payload. If the payload is valid, the gateway will respond with a [Ready](#DOCS_GATEWAY/ready) event after identifying or a [Resumed](#DOCS_GATEWAY/resumed) event after resuming, and your client can be considered in a "connected" state. Clients are limited to 1 identify every 5 seconds; if they exceed this limit, the gateway will respond with an [OP 9 Invalid Session](#DOCS_GATEWAY/gateway-invalid-session). It is important to note that although the ready event contains a large portion of the required initial state, some information (such as guilds and their members) is asynchronously sent (see [Guild Create](#DOCS_GATEWAY/guild-create) event) 322 | 323 | >warn 324 | > Clients are limited to 1000 `IDENTIFY` calls to the websocket in a 24-hour period. This limit is global and across all shards, but does not include `RESUME` calls. Upon hitting this limit, all active sessions for the bot will be terminated, the bot's token will be reset, and the owner will receive an email notification. It's up to the owner to update their application with the new token. 325 | 326 | ###### Gateway URL Params 327 | 328 | | Field | Type | Description | 329 | |-------|------|-------------| 330 | | v | integer | Gateway Version to use | 331 | | encoding | string | 'json' or 'etf' | 332 | 333 | ### Resuming 334 | 335 | The internet is a scary place, and persistent connections can often experience issues which causes them to sever and disconnect. Due to Discord's architecture, this is a semi-regular event and should be expected. Because a large portion of a client's state must be thrown out and recomputed when a connection is opened, Discord has a process for "resuming" (or reconnecting) a connection without throwing away the previous state. This process is very similar to starting a fresh connection, and allows the client to replay any lost events from the last sequence number they received in the exact same way they would receive them normally. 336 | 337 | To utilize resuming, your client should store the `session_id` from the [Ready](#DOCS_GATEWAY/ready), and the sequence number of the last event it received. When your client detects that the connection has been disconnected, through either the underlying socketing being closed or from a lack of [Gateway Heartbeat ACK](#DOCS_GATEWAY/gateway-heartbeat-ack)s, it should completely close the connection and open a new one (following the same strategy as [Connecting](#DOCS_GATEWAY/connecting)). Once the new connection has been opened, the client should send a [Gateway Resume](#DOCS_GATEWAY/gateway-resume). If successful, the gateway will respond by replaying all missed events in order, finishing with a [Resumed](#DOCS_GATEWAY/resumed) event to signal replay has finished, and all subsequent events are new. It's also possible that your client cannot reconnect in time to resume, in which case the client will receive a [OP 9 Invalid Session](#DOCS_GATEWAY/invalid-session) and is expected to wait a random amount of time (between 1 and 5 seconds), then send a fresh [OP 2 Identify](#DOCS_GATEWAY/gateway-identify). 338 | 339 | ### Disconnections 340 | 341 | If the gateway ever issues a disconnect to your client it will provide a close event code that you can use to properly handle the disconnection. 342 | 343 | ###### Gateway Close Event Codes 344 | 345 | | Code | Description | Explanation | 346 | |------|-------------|-------------| 347 | | 4000 | unknown error | We're not sure what went wrong. Try reconnecting? | 348 | | 4001 | unknown opcode | You sent an invalid [Gateway OP Code](#DOCS_GATEWAY/gateway-op-codespayloads-gateway-op-codes). Don't do that! | 349 | | 4002 | decode error | You sent an invalid [payload](#DOCS_GATEWAY/sending-payloads) to us. Don't do that! | 350 | | 4003 | not authenticated | You sent us a payload prior to [identifying](#DOCS_GATEWAY/gateway-identify). | 351 | | 4004 | authentication failed | The account token sent with your [identify payload](#DOCS_GATEWAY/gateway-identify) is incorrect. | 352 | | 4005 | already authenticated | You sent more than one identify payload. Don't do that! | 353 | | 4007 | invalid seq | The sequence sent when [resuming](#DOCS_GATEWAY/resuming) the session was invalid. Reconnect and start a new session. | 354 | | 4008 | rate limited | Woah nelly! You're sending payloads to us too quickly. Slow it down! | 355 | | 4009 | session timeout | Your session timed out. Reconnect and start a new one. | 356 | | 4010 | invalid shard | You sent us an invalid [shard when identifying](#DOCS_GATEWAY/sharding). | 357 | | 4011 | sharding required | The session would have handled too many guilds - you are required to [shard](#DOCS_GATEWAY/sharding) your connection in order to connect. | 358 | 359 | ### ETF/JSON 360 | 361 | When initially creating and handshaking connections to the Gateway, a user can chose whether they wish to communicate over plain-text JSON, or binary [ETF](http://erlang.org/doc/apps/erts/erl_ext_dist.html). When using ETF, the client must not send compressed messages to the server. 362 | 363 | ### Rate Limiting 364 | 365 | Unlike the HTTP API, the Gateway does not provide a method for forced back-off or cooldown, but instead implements a hard limit on the number of messages sent over a period of time. Currently, clients are allowed 120 events every 60 seconds, meaning you can send on average at a rate of up to 2 events per second. Clients who surpass this limit are immediately disconnected from the Gateway, and similarly to the HTTP API, repeat offenders will have their API access revoked. Clients are also limited to one gateway connection per 5 seconds. If you hit this limit, the Gateway will respond with an [OP 9 Invalid Session](#DOCS_GATEWAY/gateway-invalid-session). 366 | 367 | >warn 368 | > Clients may only update their game status 5 times per minute. 369 | 370 | ## Tracking State 371 | 372 | Most of a client's state is provided during the initial [Ready](#DOCS_GATEWAY/ready) event and the [Guild Create](#DOCS_GATEWAY/guild-create) events that immediately follow. As objects are further created/updated/deleted, other events are sent to notify the client of these changes and to provide the new or updated data. To avoid excessive API calls, Discord expects clients to locally cache as many object states as possible, and to update them as gateway events are received. 373 | 374 | An example of state tracking can be found with member status caching. When initially connecting to the gateway, the client receives information regarding the online status of guild members (online, idle, dnd, offline). To keep this state updated, a client must track and parse [Presence Update](#DOCS_GATEWAY/presence-update) events as they are received, and apply the provided data to the cached member objects. 375 | 376 | ## Guild (Un)availability 377 | 378 | When connecting to the gateway as a bot user, guilds that the bot is a part of start out as unavailable. Unavailable simply means that the gateway is either connecting, is unable to connect to a guild, or has disconnected from a guild. Don't fret however! When a guild goes unavailable the gateway will automatically attempt to reconnect on your behalf. As far as a client is concerned there is no distinction between a truly unavailable guild (meaning that the node that the guild is running on is unavailable) or a guild that the client is trying to connect to. As such, guilds only exist in two states: available or unavailable. 379 | 380 | ## Sharding 381 | 382 | As bots grow and are added to an increasing number of guilds, some developers may find it necessary to break or split portions of their bots operations into separate logical processes. As such, Discord gateways implement a method of user-controlled guild-sharding which allows for splitting events across a number of gateway connections. Guild sharding is entirely user controlled, and requires no state-sharing between separate connections to operate. 383 | 384 | To enable sharding on a connection, the user should send the `shard` array in the [identify](#DOCS_GATEWAY/gateway-identify) payload. The first item in this array should be the zero-based integer value of the current shard, while the second represents the total number of shards. DMs will only be sent to shard 0. To calculate what events will be sent to what shard, the following formula can be used: 385 | 386 | ```python 387 | (guild_id >> 22) % num_shards == shard_id 388 | ``` 389 | 390 | As an example, if you wanted to split the connection between three shards, you'd use the following values for `shard` for each connection: `[0, 3]`, `[1, 3]`, and `[2, 3]`. Note that only the first shard (`[0, 3]`) would receive DMs. 391 | 392 | ## Payloads 393 | 394 | ### Sending Payloads 395 | 396 | Packets sent from the client to the Gateway API are encapsulated within a [gateway payload object](#DOCS_GATEWAY/gateway-dispatch) and must have the proper OP code and data object set. The payload object can then be serialized in the format of choice (see [ETF/JSON](#DOCS_GATEWAY/etf-json)), and sent over the websocket. Payloads to the gateway are limited to a maximum of 4096 bytes sent, going over this will cause a connection termination with error code 4002. 397 | 398 | ### Receiving Payloads 399 | 400 | Receiving payloads with the Gateway API is slightly more complex than sending. When using the JSON encoding with compression enabled, the Gateway has the option of sending payloads as compressed JSON binaries using zlib, meaning your library _must_ detect (see [RFC1950 2.2](https://tools.ietf.org/html/rfc1950#section-2.2)) and decompress these payloads before attempting to parse them. The gateway does not implement a shared compression context between messages sent. 401 | 402 | ### Event Names 403 | 404 | Event names are in standard constant form, fully upper-cased and replacing all spaces with underscores. For instance, [Channel Create](#DOCS_GATEWAY/channel-create) would be `CHANNEL_CREATE` and [Voice State Update](#DOCS_GATEWAY/voice-state-update) would be `VOICE_STATE_UPDATE`. Within the following documentation they have been left in standard English form to aid in readability. 405 | 406 | ## Events 407 | 408 | ### Ready 409 | 410 | The ready event is dispatched when a client has completed the initial handshake with the gateway (for new sessions). The ready event can be the largest and most complex event the gateway will send, as it contains all the state required for a client to begin interacting with the rest of the platform. 411 | 412 | ###### Ready Event Fields 413 | 414 | | Field | Type | Description | 415 | |-------|------|-------------| 416 | | v | integer | [gateway protocol version](#DOCS_GATEWAY/gateway-protocol-versions) | 417 | | user | [user](#DOCS_USER/user-object) object | information about the user including email | 418 | | private_channels | array of [DM channel](#DOCS_CHANNEL/channel-object) objects | the direct messages the user is in | 419 | | guilds | array of [Unavailable Guild](#DOCS_GUILD/unavailable-guild-object) objects | the guilds the user is in | 420 | | session_id | string | used for resuming connections | 421 | | _trace | array of strings | used for debugging - the guilds the user is in | 422 | 423 | ### Resumed 424 | 425 | The resumed event is dispatched when a client has sent a [resume payload](#DOCS_GATEWAY/resuming) to the gateway (for resuming existing sessions). 426 | 427 | ###### Resumed Event Fields 428 | 429 | | Field | Type | Description | 430 | |-------|------|-------------| 431 | | _trace | array of strings | used for debugging - the guilds the user is in | 432 | 433 | ### Channel Create 434 | 435 | Sent when a new channel is created, relevant to the current user. The inner payload is a [DM channel](#DOCS_CHANNEL/channel-object) or [guild channel](#DOCS_CHANNEL/channel-object) object. 436 | 437 | ### Channel Update 438 | 439 | Sent when a channel is updated. The inner payload is a [guild channel](#DOCS_CHANNEL/channel-object) object. 440 | 441 | ### Channel Delete 442 | 443 | Sent when a channel relevant to the current user is deleted. The inner payload is a [DM](#DOCS_CHANNEL/channel-object) or [Guild](#DOCS_CHANNEL/channel-object) channel object. 444 | 445 | ### Guild Delete 446 | 447 | Sent when a guild becomes unavailable during a guild outage, or when the user leaves or is removed from a guild. 448 | 449 | ###### Guild Delete Event Fields 450 | 451 | | Field | Type | Description | 452 | |-------|------|-------------| 453 | | id | snowflake | id of the guild | 454 | | unavailable | bool | whether the guild is unavailable, should always be true. if not set, this signifies that the user was removed from the guild | 455 | 456 | 457 | ### Channel Pins Update 458 | 459 | Sent when a message is pinned or unpinned in a text channel. This is not sent when a pinned message is deleted. 460 | 461 | ###### Channel Pins Update Event Fields 462 | 463 | | Field | Type | Description | 464 | |-------|------|-------------| 465 | | channel_id | snowflake | the id of the channel | 466 | | last_pin_timestamp? | ISO8601 timestamp | the time at which the most recent pinned message was pinned | 467 | 468 | ### Guild Create 469 | 470 | This event can be sent in three different scenarios: 471 | 472 | 1. When a user is initially connecting, to lazily load and backfill information for all unavailable guilds sent in the [Ready](#DOCS_GATEWAY/ready) event. 473 | 2. When a Guild becomes available again to the client. 474 | 3. When the current user joins a new Guild. 475 | 476 | The inner payload is a [guild](#DOCS_GUILD/guild-object) object, with all the extra fields specified. 477 | 478 | ### Guild Update 479 | 480 | Sent when a guild is updated. The inner payload is a [guild](#DOCS_GUILD/guild-object) object. 481 | 482 | ### Guild Delete 483 | 484 | Sent when a guild becomes unavailable during a guild outage, or when the user leaves or is removed from a guild. The inner payload is an [unavailable guild](#DOCS_GUILD/unavailable-guild-object) object. If the `unavailable` field is not set, the user was removed from the guild. 485 | 486 | ### Guild Ban Add 487 | 488 | Sent when a user is banned from a guild. The inner payload is a [user](#DOCS_USER/user-object) object, with an extra guild_id key. 489 | 490 | ### Guild Ban Remove 491 | 492 | Sent when a user is unbanned from a guild. The inner payload is a [user](#DOCS_USER/user-object) object, with an extra guild_id key. 493 | 494 | ### Guild Emojis Update 495 | 496 | Sent when a guild's emojis have been updated. 497 | 498 | ###### Guild Emojis Update Event Fields 499 | 500 | | Field | Type | Description | 501 | |-------|------|-------------| 502 | | guild_id | snowflake | id of the guild | 503 | | emojis | array | array of [emojis](#DOCS_GUILD/emoji-object) | 504 | 505 | ### Guild Integrations Update 506 | 507 | Sent when a guild integration is updated. 508 | 509 | ###### Guild Integrations Update Event Fields 510 | 511 | | Field | Type | Description | 512 | |-------|------|-------------| 513 | | guild_id | snowflake | id of the guild whose integrations were updated | 514 | 515 | ### Guild Member Add 516 | 517 | Sent when a new user joins a guild. The inner payload is a [guild member](#DOCS_GUILD/guild-member-object) object with these extra fields: 518 | 519 | ###### Guild Member Add Extra Fields 520 | 521 | | Field | Type | Description | 522 | |-------|------|-------------| 523 | | guild_id | snowflake | id of the guild | 524 | 525 | ### Guild Member Remove 526 | 527 | Sent when a user is removed from a guild (leave/kick/ban). 528 | 529 | ###### Guild Member Remove Event Fields 530 | 531 | | Field | Type | Description | 532 | |-------|------|-------------| 533 | | guild_id | snowflake | the id of the guild | 534 | | user | a [user](#DOCS_USER/user-object) object | the user who was removed | 535 | 536 | ### Guild Member Update 537 | 538 | Sent when a guild member is updated. 539 | 540 | ###### Guild Member Update Event Fields 541 | 542 | | Field | Type | Description | 543 | |-------|------|-------------| 544 | | guild_id | snowflake | the id of the guild | 545 | | roles | array of snowflakes | user role ids | 546 | | user | a [user](#DOCS_USER/user-object) object | the user | 547 | | nick | string | nickname of the user in the guild | 548 | 549 | ### Guild Members Chunk 550 | 551 | Sent in response to [Gateway Request Guild Members](#DOCS_GATEWAY/gateway-request-guild-members). 552 | 553 | ###### Guild Members Chunk Event Fields 554 | 555 | | Field | Type | Description | 556 | |-------|------|-------------| 557 | | guild_id | snowflake | the id of the guild | 558 | | members | array of [guild members](#DOCS_GUILD/guild-member-object) | set of guild members | 559 | 560 | ### Guild Role Create 561 | 562 | Sent when a guild role is created. 563 | 564 | ###### Guild Role Create Event Fields 565 | 566 | | Field | Type | Description | 567 | |-------|------|-------------| 568 | | guild_id | snowflake | the id of the guild | 569 | | role | a [role](#DOCS_PERMISSIONS/role-object) object | the role created | 570 | 571 | ### Guild Role Update 572 | 573 | Sent when a guild role is updated. 574 | 575 | ###### Guild Role Update Event Fields 576 | 577 | | Field | Type | Description | 578 | |-------|------|-------------| 579 | | guild_id | snowflake | the id of the guild | 580 | | role | a [role](#DOCS_PERMISSIONS/role-object) object | the role updated | 581 | 582 | ### Guild Role Delete 583 | 584 | Sent when a guild role is deleted. 585 | 586 | ###### Guild Role Delete Event Fields 587 | 588 | | Field | Type | Description | 589 | |-------|------|-------------| 590 | | guild_id | snowflake | id of the guild | 591 | | role_id | snowflake | id of the role | 592 | 593 | ### Message Create 594 | 595 | Sent when a message is created. The inner payload is a [message](#DOCS_CHANNEL/message-object) object. 596 | 597 | ### Message Update 598 | 599 | Sent when a message is updated. The inner payload is a [message](#DOCS_CHANNEL/message-object) object. 600 | 601 | >warn 602 | > Unlike creates, message updates may contain only a subset of the full message object payload (but will always contain an id and channel_id). 603 | 604 | ### Message Delete 605 | 606 | Sent when a message is deleted. 607 | 608 | ###### Message Delete Event Fields 609 | 610 | | Field | Type | Description | 611 | |-------|------|-------------| 612 | | id | snowflake | the id of the message | 613 | | channel_id | snowflake | the id of the channel | 614 | 615 | ### Message Delete Bulk 616 | 617 | Sent when multiple messages are deleted at once. 618 | 619 | ###### Message Delete Bulk Event Fields 620 | 621 | | Field | Type | Description | 622 | |-------|------|-------------| 623 | | ids | array of snowflakes | the ids of the messages | 624 | | channel_id | snowflake | the id of the channel | 625 | 626 | ### Message Reaction Add 627 | 628 | Sent when a user adds a reaction to a message. 629 | 630 | ###### Message Reaction Add Event Fields 631 | 632 | | Field | Type | Description | 633 | |-------|------|-------------| 634 | | user_id | snowflake | the id of the user | 635 | | channel_id | snowflake | the id of the channel | 636 | | message_id | snowflake | the id of the message | 637 | | emoji | an [emoji](#DOCS_GUILD/emoji-object) object | the emoji used to react | 638 | 639 | ### Message Reaction Remove 640 | 641 | Sent when a user removes a reaction from a message. 642 | 643 | ###### Message Reaction Remove Event Fields 644 | 645 | | Field | Type | Description | 646 | |-------|------|-------------| 647 | | user_id | snowflake | the id of the user | 648 | | channel_id | snowflake | the id of the channel | 649 | | message_id | snowflake | the id of the message | 650 | | emoji | an [emoji](#DOCS_GUILD/emoji-object) object | the emoji used to react | 651 | 652 | ### Message Reaction Remove All 653 | 654 | Sent when a user explicitly removes all reactions from a message. 655 | 656 | ###### Message Reaction Remove All Event Fields 657 | 658 | | Field | Type | Description | 659 | |-------|------|-------------| 660 | | channel_id | snowflake | the id of the channel | 661 | | message_id | snowflake | the id of the message | 662 | 663 | ### Presence Update 664 | 665 | A user's presence is their current state on a guild. This event is sent when a user's presence is updated for a guild. 666 | 667 | >warn 668 | > The user object within this event can be partial, the only field which must be sent is the `id` field, everything else is optional. Along with this limitation, no fields are required, and the types of the fields are **not** validated. Your client should expect any combination of fields and types within this event. 669 | 670 | ###### Presence Update Event Fields 671 | 672 | | Field | Type | Description | 673 | |-------|------|-------------| 674 | | user | [user](#DOCS_USER/user-object) object | the user presence is being updated for | 675 | | roles | array of snowflakes | roles this user is in | 676 | | game | ?[game](#DOCS_GATEWAY/game-object) object | null, or the user's current activity | 677 | | guild_id | snowflake | id of the guild | 678 | | status | string | either "idle", "dnd", "online", or "offline" | 679 | 680 | #### Game Object 681 | 682 | ###### Game Structure 683 | 684 | | Field | Type | Description | Present | 685 | |-------|------|-------------|---------| 686 | | name | string | the game's name | Always | 687 | | type | ?integer | see [Game Types](#DOCS_GATEWAY/game-types) | Sometimes | 688 | | url | ?string | stream url, is validated when type is 1 | When type is 1 | 689 | 690 | ###### Game Types 691 | 692 | | ID | Name | Format | Example | 693 | |----|------|--------|---------| 694 | | 0 | Game | Playing {name} | "Playing Rocket League" | 695 | | 1 | Streaming | Streaming {name} | "Streaming Rocket League" | 696 | 697 | >info 698 | > The streaming type currently only supports Twitch. Only `https://twitch.tv/` urls will work. 699 | 700 | ###### Example Game 701 | 702 | ```json 703 | { 704 | "name": "Rocket League", 705 | "type": 1, 706 | "url": "https://www.twitch.tv/123" 707 | } 708 | ``` 709 | 710 | ### Typing Start 711 | 712 | Sent when a user starts typing in a channel. 713 | 714 | ###### Typing Start Event Fields 715 | 716 | | Field | Type | Description | 717 | |-------|------|-------------| 718 | | channel_id | snowflake | id of the channel | 719 | | user_id | snowflake | id of the user | 720 | | timestamp | integer | unix time (in seconds) of when the user started typing | 721 | 722 | ### User Update 723 | 724 | Sent when properties about the user change. Inner payload is a [user](#DOCS_USER/user-object) object. 725 | 726 | ### Voice State Update 727 | 728 | Sent when someone joins/leaves/moves voice channels. Inner payload is a [voice state](#DOCS_VOICE/voice-state-object) object. 729 | 730 | ### Voice Server Update 731 | 732 | Sent when a guild's voice server is updated. This is sent when initially connecting to voice, and when the current voice instance fails over to a new server. 733 | 734 | ###### Voice Server Update Event Fields 735 | 736 | | Field | Type | Description | 737 | |-------|------|-------------| 738 | | token | string | voice connection token | 739 | | guild_id | snowflake | the guild this voice server update is for | 740 | | endpoint | string | the voice server host | 741 | 742 | ###### Example Voice Server Update Payload 743 | 744 | ```json 745 | { 746 | "token": "my_token", 747 | "guild_id": "41771983423143937", 748 | "endpoint": "smart.loyal.discord.gg" 749 | } 750 | ``` 751 | 752 | ### Webhooks Update 753 | 754 | Sent when a guild channel's webhook is created, updated, or deleted. 755 | 756 | ###### Webhook Update Event Fields 757 | 758 | | Field | Type | Description | 759 | |-------|------|-------------| 760 | | guild_id | snowflake | id of the guild | 761 | | channel_id | snowflake | id of the channel | 762 | -------------------------------------------------------------------------------- /docs/topics/Libraries.md: -------------------------------------------------------------------------------- 1 | # Libraries 2 | 3 | The Discord team curates the following list of officially vetted libraries that conform to our APIs standards around authentication and rate limiting. Using custom implementations or non-compliant libraries which abuse the API or cause excessive rate limits may result in a **permanent** ban. 4 | 5 | | Name | Language | 6 | |------|----------| 7 | | [discordcr](https://github.com/meew0/discordcr) | Crystal | 8 | | [dscord](https://github.com/b1naryth1ef/dscord) | D | 9 | | [nyx](https://github.com/Hackzzila/nyx) | Dart | 10 | | [Discord.Net](https://github.com/RogueException/Discord.Net) | C# | 11 | | [DSharpPlus](https://github.com/NaamloosDT/DSharpPlus) | C# | 12 | | [DiscordGo](https://github.com/bwmarrin/discordgo) | Go | 13 | | [Discord4j](https://github.com/austinv11/Discord4J) | Java | 14 | | [JDA](https://github.com/DV8FromTheWorld/JDA) | Java | 15 | | [discord.js](https://github.com/hydrabolt/discord.js) | JavaScript | 16 | | [Eris](https://github.com/abalabahaha/eris) | JavaScript | 17 | | [Discordia](https://github.com/SinisterRectus/Discordia) | Lua | 18 | | [DiscordPHP](https://github.com/teamreflex/DiscordPHP) | PHP | 19 | | [discord.py](https://github.com/Rapptz/discord.py) | Python | 20 | | [disco](https://github.com/b1naryth1ef/disco) | Python | 21 | | [discordrb](https://github.com/meew0/discordrb) | Ruby | 22 | | [discord-rs](https://github.com/SpaceManiac/discord-rs) | Rust | 23 | | [Sword](https://github.com/Azoy/Sword) | Swift | 24 | -------------------------------------------------------------------------------- /docs/topics/OAuth2.md: -------------------------------------------------------------------------------- 1 | # OAuth2 2 | 3 | OAuth2 enables application developers to build applications that utilize authentication and data from the Discord API. Within the Discord platform, there are two types of oauth2 authentication, "full stack" or "application" auth and bot auth. The former is what is most people will recognize as generic OAuth2, and allows the developer to authenticate and make certain requests on behalf of a user. The latter enables bot creators to have an easy, callback/server-free flow for giving users the ability to add their bot to servers they own. 4 | 5 | ## Bot vs User Accounts 6 | 7 | Discord's API provides a seperate type of user account dedicated to automation, called a bot account. Bot accounts can be created through the [applications page](#MY_APPLICATIONS/top), and are authenticated using a token (rather than a username and password). Unlike the normal OAuth2 flow, bot accounts have full access to all API routes without using bearer tokens, and can connect to the [Real Time Gateway](#DOCS_GATEWAY/gateways). Automating normal user accounts (generally called "self-bots") outside of the OAuth2/bot API is forbidden, and can result in an account termination if found. 8 | 9 | Bot accounts have a few differences in comparison to normal user accounts, namely: 10 | 11 | 1. Bots are added to servers through the OAuth2 API, and cannot accept normal invites. 12 | 2. Bots cannot have friends, nor be added to or join Group DMs. 13 | 3. Bots do not have a maximum number of Guilds (unlike user accounts, which are limited to 100). 14 | 4. Bots have an entirely separate set of [Rate Limits](#DOCS_RATE_LIMITS/rate-limits). 15 | 16 | 17 | Users interested in providing real-time automation to user accounts should consider the [RPC API](#DOCS_RPC/rpc). 18 | 19 | ## Implementing OAuth2 20 | 21 | ### Registering Applications 22 | 23 | The first step in implementing OAuth2 is [registering a developer application](#MY_APPLICATIONS/top), and retrieving your client ID and client secret. Most people who will be implementing OAuth2 will want to find and utilize a library in the language of their choice. For those implementing OAuth2 from scratch, please see [RFC 6749](https://tools.ietf.org/html/rfc6749) for details. In the Discord OAuth2 API, it's technically valid to _not_ have a redirect URI for your application, this enables one-sided authentication flows which allow for server-less bot-adding. The URLs for OAuth2 are as follows: 24 | 25 | ###### OAuth2 Application URLs 26 | 27 | | URL | Description | 28 | |-----|-------------| 29 | | https://discordapp.com/api/oauth2/authorize | Base authorization URL | 30 | | https://discordapp.com/api/oauth2/token | Token URL | 31 | | https://discordapp.com/api/oauth2/token/revoke | Revocation URL | 32 | 33 | 34 | >info 35 | > Discord also implements refresh tokens, which can be passed to the token URL for valid authentication tokens. 36 | 37 | ### Scopes 38 | 39 | Scopes provide access to certain resources of a user's account. Your API client or service should only request scopes it requires for operation. 40 | 41 | ###### OAuth2 Scopes 42 | 43 | | Name | Description | 44 | |------|-------------| 45 | | bot | for oauth2 bots, this puts the bot in the user's selected guild by default | 46 | | connections | allows [/users/@me/connections](#DOCS_USER/get-user-connections) to return linked third-party accounts | 47 | | email | enables [/users/@me](#DOCS_USER/get-current-user) to return an `email` | 48 | | identify | allows [/users/@me](#DOCS_USER/get-current-user) without `email` | 49 | | guilds | allows [/users/@me/guilds](#DOCS_USER/get-current-user-guilds) to return basic information about all of a user's guilds | 50 | | guilds.join | allows [/invites/{invite.id}](#DOCS_INVITE/accept-invite) to be used for joining users to a guild | 51 | | gdm.join | allows your app to [join users to a group dm](#DOCS_CHANNEL/group-dm-add-recipient) | 52 | | 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) | 53 | | rpc | for local rpc server access, this allows you to control a user's local Discord client | 54 | | rpc.api | for local rpc server api access, this allows you to access the API as the local user | 55 | | rpc.notifications.read | for local rpc server api access, this allows you to receive notifications pushed out to the user | 56 | | webhook.incoming | this generates a webhook that is returned in the oauth token response for authorization code grants | 57 | 58 | >info 59 | > Unlike the rest of the scopes, `guilds.join` requires you to have a bot account linked to your application and can only be used to join users to guilds which your bot services. 60 | 61 | ## Bots 62 | 63 | Bots within the Discord API are a form of user account that is authenticated _without_ a username or password, and has similar properties and abilities to normal user accounts. Bot accounts enable developers to have a simple portal that allows authenticated users to add third-party bots to servers they own or manage. 64 | 65 | ### Registering Bots 66 | 67 | Bots can be registered by clicking the "add bot" button when editing or creating an [OAuth2 application](#MY_APPLICATIONS/top). 68 | 69 | ### Two-Factor Authentication Requirement 70 | 71 | For bots with [elevated permissions](#DOCS_PERMISSIONS/bitwise-permission-flags) (permissions with a * next to them), we enforce two-factor authentication for the owner's account when used on guilds that have server-wide 2FA enabled. 72 | 73 | ### Adding Bots to Guilds 74 | 75 | A URL can be generated that redirects authenticated users to the add-bot flow. It can be in the following format without a `redirect_uri`: 76 | 77 | ``` 78 | https://discordapp.com/api/oauth2/authorize?client_id=157730590492196864&scope=bot&permissions=0 79 | ``` 80 | 81 | Or with a `redirect_uri`: 82 | 83 | ``` 84 | https://discordapp.com/api/oauth2/authorize?client_id=157730590492196864&scope=bot&permissions=0&redirect_uri=https%3A%2F%2Fnicememe.website 85 | ``` 86 | 87 | `client_id` is your _bot's_ application ID. `permissions` is an integer following the [permissions](#DOCS_PERMISSIONS/bitwise-permission-flags) format. If supplied, the `redirect_uri` will include additional query string parameters on redirect: `guild_id`, the guild the _bot_ has joined, and `permissions`, the same integer sent at the start of the flow. 88 | 89 | ### Adding Webhooks to Channels 90 | 91 | A URL can be generated that redirects authenticated users to the add-webhook flow, by using the following format (this utilizes the OAuth2 authentication authorization code flow, which requires a server-side application): 92 | 93 | ``` 94 | https://discordapp.com/api/oauth2/authorize?client_id=157730590492196864&scope=webhook.incoming&redirect_uri=https%3A%2F%2Fnicememe.website&response_type=code 95 | ``` 96 | 97 | `client_id` is your application's ID and `redirect_uri` is one of your application's URL-encoded redirect URIs. 98 | 99 | When a user is directed to this URL, they are prompted to select a channel for the webhook to be placed in. Your application will receive an authorization code back in the querystring (as usual with the authorization code grant). 100 | 101 | When you exchange the authorization code for an access token, the token response will contain the [webhook](#DOCS_WEBHOOK/webhook-object) object: 102 | 103 | ```json 104 | { 105 | "token_type": "Bearer", 106 | "access_token": "7r70pJOvarwv1fkPqacZqFOCv39tX2", 107 | "scope": "webhook.incoming", 108 | "expires_in": 604800, 109 | "refresh_token": "TY0U8LP8joJURIhqREL4AuQXcj5DlO", 110 | "webhook": { 111 | "name": "test", 112 | "channel_id": "199737254929760256", 113 | "token": "DuAt6zzLQpPhaAq0IcnCrDUWWpY9Y07dqkB5ulLkhwpA00ZK7IjLve5AE4ACUZqCUTY8", 114 | "avatar": "eaa0292a003ceb15264a838a8eff961a", 115 | "guild_id": "199737254929760256", 116 | "id": "236380988341485568" 117 | } 118 | } 119 | ``` 120 | 121 | ### Get Current Application Information % GET /oauth2/applications/@me 122 | 123 | Returns the bot's OAuth2 application info. 124 | 125 | ###### Response Structure 126 | 127 | | Field | Type | Description | 128 | |-------|------|-------------| 129 | | id | snowflake | the id of the app | 130 | | name | string | the name of the app | 131 | | icon? | string | the icon hash of the app | 132 | | description? | string | the description of the app | 133 | | rpc_origins? | array | an array of rpc origin url strings, if rpc is enabled | 134 | | bot_public | bool | when false only app owner can join the app's bot to guilds | 135 | | bot_require_code_grant | bool | when true the app's bot will only join upon completion of the full oauth2 code grant flow | 136 | | owner | [user](#DOCS_USER/user-object) object | partial user object containing info on the owner of the application | 137 | 138 | ###### Example Application Information 139 | 140 | ```json 141 | { 142 | "description": "Test", 143 | "icon": null, 144 | "id": "172150183260323840", 145 | "name": "Baba O-Riley", 146 | "bot_public": true, 147 | "bot_require_code_grant": false, 148 | "owner": { 149 | "username": "i own a bot", 150 | "discriminator": "1738", 151 | "id": "172150183260323840", 152 | "avatar": null 153 | } 154 | } 155 | ``` 156 | -------------------------------------------------------------------------------- /docs/topics/Permissions.md: -------------------------------------------------------------------------------- 1 | # Permissions 2 | 3 | Permissions in Discord are a way to limit and grant certain abilities to users. A set of base permissions can be configured at the guild level for different roles, when these roles are attached to users they grant or revoke specific privileges within the guild. Along with the global guild-level permissions, Discord also supports role overwrites which can be set at the channel level allowing customization of permissions on a per-role, per-channel basis. 4 | 5 | Permissions in Discord are stored within a 53-bit integer and are calculated using bitwise operations. Permissions for a user in a given channel can be calculated by ORing together their guild-level role permission integers, and their channel-level role permission integers. For more information about bitwise operations and flags, see [this page](https://en.wikipedia.org/wiki/Bit_field). 6 | 7 | ###### Bitwise Permission Flags 8 | 9 | | Permission | Value | Description | 10 | |------------|-------|-----------| 11 | | CREATE\_INSTANT\_INVITE | `0x00000001` | Allows creation of instant invites | 12 | | KICK\_MEMBERS * | `0x00000002` | Allows kicking members | 13 | | BAN\_MEMBERS * | `0x00000004` | Allows banning members | 14 | | ADMINISTRATOR * | `0x00000008` | Allows all permissions and bypasses channel permission overwrites | 15 | | MANAGE\_CHANNELS * | `0x00000010` | Allows management and editing of channels | 16 | | MANAGE\_GUILD * | `0x00000020` | Allows management and editing of the guild | 17 | | ADD\_REACTIONS | `0x00000040` | Allows for the addition of reactions to messages | 18 | | VIEW\_AUDIT\_LOG | `0x00000080` | Allows for viewing of audit logs | 19 | | READ\_MESSAGES | `0x00000400` | Allows reading messages in a channel. The channel will not appear for users without this permission | 20 | | SEND\_MESSAGES | `0x00000800` | Allows for sending messages in a channel | 21 | | SEND\_TTS\_MESSAGES | `0x00001000` | Allows for sending of `/tts` messages | 22 | | MANAGE\_MESSAGES * | `0x00002000` | Allows for deletion of other users messages | 23 | | EMBED\_LINKS | `0x00004000` | Links sent by this user will be auto-embedded | 24 | | ATTACH\_FILES | `0x00008000` | Allows for uploading images and files | 25 | | READ\_MESSAGE\_HISTORY | `0x00010000` | Allows for reading of message history | 26 | | MENTION\_EVERYONE | `0x00020000` | Allows for using the `@everyone` tag to notify all users in a channel, and the `@here` tag to notify all online users in a channel | 27 | | USE\_EXTERNAL\_EMOJIS | `0x00040000` | Allows the usage of custom emojis from other servers | 28 | | CONNECT | `0x00100000` | Allows for joining of a voice channel | 29 | | SPEAK | `0x00200000` | Allows for speaking in a voice channel | 30 | | MUTE\_MEMBERS | `0x00400000` | Allows for muting members in a voice channel | 31 | | DEAFEN\_MEMBERS | `0x00800000` | Allows for deafening of members in a voice channel | 32 | | MOVE\_MEMBERS | `0x01000000` | Allows for moving of members between voice channels | 33 | | USE\_VAD | `0x02000000` | Allows for using voice-activity-detection in a voice channel | 34 | | CHANGE\_NICKNAME | `0x04000000` | Allows for modification of own nickname | 35 | | MANAGE\_NICKNAMES | `0x08000000` | Allows for modification of other users nicknames | 36 | | MANAGE\_ROLES * | `0x10000000` | Allows management and editing of roles | 37 | | MANAGE\_WEBHOOKS * | `0x20000000` | Allows management and editing of webhooks | 38 | | MANAGE\_EMOJIS * | `0x40000000` | Allows management and editing of emojis | 39 | 40 | **\* These permissions require the owner account to use [two-factor authentication](#DOCS_OAUTH2/twofactor-authentication-requirement) when used on a guild that has server-wide 2FA enabled.** 41 | 42 | ## Permission Hierarchy 43 | 44 | Permissions follow a hierarchy with the following roles: 45 | 46 | * A bot can grant roles to other users that are of a lower position than their highest role. 47 | * A bot can edit roles of a lower position than their highest role, but they can only grant permissions they have to those roles. 48 | * Bots can only sort roles lower than their highest role. 49 | * Bots can only kick/ban users of with a lower highest role than themselves. 50 | 51 | ## Role Object 52 | 53 | Roles represent a set of permissions attached to a group of users. Roles have unique names, colors, and can be "pinned" to the side bar, causing their members to be listed separately. Roles are unique per guild, and can have separate permission profiles for the global context (guild) and channel context. 54 | 55 | ###### Role Structure 56 | 57 | | Field | Type | Description | 58 | |-------|------|-------------| 59 | | id | snowflake | role id | 60 | | name | string | role name | 61 | | color | integer | integer representation of hexadecimal color code | 62 | | hoist | bool | if this role is pinned in the user listing | 63 | | position | integer | position of this role | 64 | | permissions | integer | permission bit set | 65 | | managed | bool | whether this role is managed by an integration | 66 | | mentionable | bool | whether this role is mentionable | 67 | 68 | Roles without colors (`color == 0`) do not count towards the final computed color in the user list. 69 | 70 | ###### Example Role 71 | 72 | ```json 73 | { 74 | "id": "41771983423143936", 75 | "name": "WE DEM BOYZZ!!!!!!", 76 | "color": 3447003, 77 | "hoist": true, 78 | "position": 1, 79 | "permissions": 66321471, 80 | "managed": false, 81 | "mentionable": false 82 | } 83 | ``` 84 | -------------------------------------------------------------------------------- /docs/topics/Rate_Limits.md: -------------------------------------------------------------------------------- 1 | # Rate Limits 2 | 3 | Discord's API rate limits requests in order to prevent abuse and overload of our services. Rate limits are applied on a per-route basis (meaning they can be different for each route called), with the exception of an additional global rate limit spanning across the entire API. Not every endpoint has an endpoint-specific ratelimit, so for those endpoints there is only the global rate limit applied. 4 | 5 | By "per-route," we mean that unique rate limits exist for the path you are accessing on our API, not including the HTTP method (GET, POST, PUT, DELETE) and including major parameters. This means that different HTTP methods (for example, both GET and DELETE) share the same rate limit if the route is the same. Additionally, rate limits take into account major parameters in the URL. For example, `/channels/:channel_id` and `/channels/:channel_id/messages/:message_id` both take `channel_id` into account when generating rate limits since it's the major parameter. The only current major parameters are `channel_id` and `guild_id`. 6 | 7 | >warn 8 | > There is currently a single exception to the above rule regarding different HTTP methods sharing the same rate limit, and that is for the [deletion of messages](#DOCS_CHANNEL/delete-message). Deleting messages falls under a separate, higher rate limit so that bots are able to more quickly delete content from channels (which is useful for moderation bots). 9 | 10 | Because we may change rate limits at any time and rate limits can be different per application, *rate limits should not be hard coded into your bot/application*. In order to properly support our dynamic rate limits, your bot/application should parse for our rate limits in response headers and locally prevent exceeding of the limits as they change. 11 | 12 | ## Header Format 13 | 14 | For every API request made, we return optional HTTP response headers containing the rate limit encountered during your request. 15 | 16 | ``` 17 | X-RateLimit-Limit: 5 18 | X-RateLimit-Remaining: 0 19 | X-RateLimit-Reset: 1470173023 20 | ``` 21 | 22 | * **X-RateLimit-Global** - Returned only on a HTTP 429 response if the rate limit headers returned are of the global rate limit (not per-route) 23 | * **X-RateLimit-Limit** - The number of requests that can be made 24 | * **X-RateLimit-Remaining** - The number of remaining requests that can be made 25 | * **X-RateLimit-Reset** - Epoch time (seconds since 00:00:00 UTC on January 1, 1970) at which the rate limit resets 26 | 27 | ## Exceeding A Rate Limit 28 | 29 | In the case that a rate limit is exceeded, the API will return a HTTP 429 response code with a JSON body. 30 | 31 | ###### Rate Limit Response Structure 32 | 33 | | Field | Type | Description | 34 | |-------|------|-------------| 35 | | message | string | A message saying you are being rate limited. | 36 | | retry_after | integer | The number of milliseconds to wait before submitting another request. | 37 | | global | bool | A value indicating if you are being globally rate limited or not | 38 | 39 | Note that the normal rate-limiting headers will be sent in this response. 40 | 41 | ###### Example Rate Limit Responses 42 | 43 | The rate-limiting response will look something like the following[:](http://takeb1nzyto.space/) 44 | 45 | ``` 46 | < HTTP/1.1 429 TOO MANY REQUESTS 47 | < Content-Type: application/json 48 | < Retry-After: 6457 49 | < X-RateLimit-Limit: 10 50 | < X-RateLimit-Remaining: 0 51 | < X-RateLimit-Reset: 1470173023 52 | { 53 | "message": "You are being rate limited.", 54 | "retry_after": 6457, 55 | "global": false 56 | } 57 | ``` 58 | 59 | For a global rate limit, the response would look like: 60 | 61 | ``` 62 | < HTTP/1.1 429 TOO MANY REQUESTS 63 | < Content-Type: application/json 64 | < Retry-After: 6457 65 | < X-RateLimit-Global: true 66 | { 67 | "message": "You are being rate limited.", 68 | "retry_after": 6457, 69 | "global": true 70 | } 71 | ``` 72 | -------------------------------------------------------------------------------- /docs/topics/Response_Codes.md: -------------------------------------------------------------------------------- 1 | # Response/Error Codes 2 | 3 | ## HTTP Response/Error Codes 4 | 5 | Our API will return semantically valid HTTP response codes based on the success of your request. The following table can be used as a reference for response codes it will return. 6 | 7 | ###### HTTP Response/Error Code List 8 | 9 | | Code | Meaning | 10 | |------|---------| 11 | | 200 (OK) | The request completed successfully | 12 | | 201 (CREATED) | The entity was created successfully | 13 | | 204 (NO CONTENT) | The request completed successfully but returned no content | 14 | | 304 (NOT MODIFIED) | The entity was not modified (no action was taken) | 15 | | 400 (BAD REQUEST) | The request was improperly formatted, or the server couldn't understand it | 16 | | 401 (UNAUTHORIZED) | The `Authorization` header was missing or invalid | 17 | | 403 (FORBIDDEN) | The `Authorization` token you passed did not have permission to the resource | 18 | | 404 (NOT FOUND) | The resource at the location specified doesn't exist | 19 | | 405 (METHOD NOT ALLOWED) | The HTTP method used is not valid for the location specified | 20 | | 429 (TOO MANY REQUESTS) | You've made too many requests, see [Rate Limits](#DOCS_RATE_LIMITS/rate-limits) | 21 | | 502 (GATEWAY UNAVAILABLE) | There was not a gateway available to process your request. Wait a bit and retry | 22 | | 5xx (SERVER ERROR) | The server had an error processing your request (these are rare) | 23 | 24 | ## JSON Error Response 25 | 26 | Along with the HTTP error code, our API can also return more detailed error codes through a `code` key in the JSON error response. The response will also contain a `message` key containing a more friendly error string. 27 | 28 | ###### JSON Error Codes 29 | 30 | | Code | Meaning | 31 | |------|---------| 32 | | 10001 | Unknown account | 33 | | 10002 | Unknown application | 34 | | 10003 | Unknown channel | 35 | | 10004 | Unknown guild | 36 | | 10005 | Unknown integration | 37 | | 10006 | Unknown invite | 38 | | 10007 | Unknown member | 39 | | 10008 | Unknown message | 40 | | 10009 | Unknown overwrite | 41 | | 10010 | Unknown provider | 42 | | 10011 | Unknown role | 43 | | 10012 | Unknown token | 44 | | 10013 | Unknown user | 45 | | 10014 | Unknown Emoji | 46 | | 20001 | Bots cannot use this endpoint | 47 | | 20002 | Only bots can use this endpoint | 48 | | 30001 | Maximum number of guilds reached (100) | 49 | | 30002 | Maximum number of friends reached (1000) | 50 | | 30003 | Maximum number of pins reached (50) | 51 | | 30005 | Maximum number of guild roles reached (250) | 52 | | 30010 | Too many reactions | 53 | | 40001 | Unauthorized | 54 | | 50001 | Missing access | 55 | | 50002 | Invalid account type | 56 | | 50003 | Cannot execute action on a DM channel | 57 | | 50004 | Embed disabled | 58 | | 50005 | Cannot edit a message authored by another user | 59 | | 50006 | Cannot send an empty message | 60 | | 50007 | Cannot send messages to this user | 61 | | 50008 | Cannot send messages in a voice channel | 62 | | 50009 | Channel verification level is too high | 63 | | 50010 | OAuth2 application does not have a bot | 64 | | 50011 | OAuth2 application limit reached | 65 | | 50012 | Invalid OAuth state | 66 | | 50013 | Missing permissions | 67 | | 50014 | Invalid authentication token | 68 | | 50015 | Note is too long | 69 | | 50016 | Provided too few or too many messages to delete. Must provide at least 2 and fewer than 100 messages to delete. | 70 | | 50019 | A message can only be pinned to the channel it was sent in | 71 | | 50021 | Cannot execute action on a system message | 72 | | 50034 | A message provided was too old to bulk delete | 73 | | 50035 | Invalid Form Body | 74 | | 50036 | An invite was accepted to a guild the application's bot is not in | 75 | | 90001 | Reaction Blocked | 76 | 77 | ###### Example JSON Error Response 78 | 79 | ```json 80 | { 81 | "code": 50014, 82 | "message": "Invalid authentication token" 83 | } 84 | ``` 85 | -------------------------------------------------------------------------------- /docs/topics/Rich_Presence.md: -------------------------------------------------------------------------------- 1 | # Introducing Rich Presence 2 | 3 | How easy is it for people to play your game together? With Rich Presence from Discord—a new feature in the ever-expanding GameBridge suite—it just got so easy, a ~~caveman~~ Junior Dev could do it. 4 | 5 | Rich Presence is currently in a private alpha phase. If you're interested in getting access, [apply to our Gamebridge program](https://discordapp.com/gamebridge) and mention Rich Presence, and we'll review your application. 6 | 7 | ## So, what is it? 8 | 9 | Rich Presence allows you to leverage the totally overhauled "Now Playing" section in a Discord user's profile to help people play your game together. Rich game data—including duration, score, current boss or map, and so much more—lives inside a user's profile alongside buttons that let you spectate or join a friend's game directly from Discord, or get a notification when it's over. 10 | 11 | It also features beautiful embeds right in your chat window with real-time information about open party slots and the party's in-game status. No more wondering if there's room for you to join, or if they're mid-game, or about to finish. It's a living invitation to play together! 12 | 13 | ## So, how does it work? 14 | 15 | >Note: While the SDK for Rich Presence is not currently publically available, the documentation here accurately reflects any eventual implementation you would need to do. That means that you can have your codebase all ready to be hooked up to the SDK before having access to it. 16 | 17 | We worked hard to make using Discord's Rich Presence system as easy as possible. All you need is our header file—what you will interact with—and our library—where we did all the hard work for you—and you are ready to roll! 18 | 19 | In the header file, you'll find five event-emitting callbacks: 20 | 21 | 1. `ready()` 22 | 2. `errored()` 23 | 3. `disconnected()` 24 | 4. `joinGame()` 25 | 5. `spectateGame()` 26 | 27 | These five callbacks make up the entirety of what you need to implement. Behind the scenes, we do all the heavy lifting for you. 28 | 29 | ## Whatcha dooooooin'? 30 | 31 | The first step in implementing Rich Presence is registering your callback functions to the five `DiscordEventHandlers` and then calling `Discord_Initialize()` with your `APPLICATION_ID`: 32 | 33 | ```cpp 34 | void InitDiscord() 35 | { 36 | DiscordEventHandlers handlers; 37 | memset(&handlers, 0, sizeof(handlers)); 38 | handlers.ready = handleDiscordReady; 39 | handlers.disconnected = handleDiscordDisconnected; 40 | handlers.errored = handleDiscordError; 41 | Discord_Initialize(APPLICATION_ID, &handlers, 1); 42 | } 43 | ``` 44 | 45 | The `Discord_Initialize()` function has a parameter `autoRegister`. Marking this field as true lets Discord register an application protocol in the format `discord-[your app id]://` so that joining and spectating will work even when the game is closed. Once the game launches, we'll call your `joinGame()` and `spectateGame()` functions to continue the flow. If your game needs custom parameters on launch, such as an auth ticket, you'll need to register your own protocol on the system. More information on this coming soon. For now, just ask us! 46 | 47 | The core of Discord's Rich Presence SDK is the `Discord_UpdatePresence()` function. This is what sends your game data up to Discord to be seen and used by others. You should call `Discord_UpdatePresence()` with the necessary data in your `ready()` callback and any time something in the presence payload changes. The payload is outlined in detail in a later section, but for now, here's an example of a super rich presence: 48 | 49 | ```cpp 50 | void UpdatePresence() 51 | { 52 | DiscordRichPresence discordPresence; 53 | discordPresence.state = "In a Group"; 54 | discordPresence.details = "Competitive | In a Match"; 55 | discordPresence.endTimestamp = time(nullptr) + ((60 * 5) + 23); 56 | discordPresence.partyId = GameEngine.GetPartyId(); 57 | discordPresence.partySize = 3; 58 | discordPresence.partyMax = 6; 59 | discordPresence.matchSecret = "4b2fdce12f639de8bfa7e3591b71a0d679d7c93f"; 60 | discordPresence.spectateSecret = "e7eb30d2ee025ed05c71ea495f770b76454ee4e0"; 61 | discordPresence.instance = 1; 62 | Discord_UpdatePresence(&discordPresence); 63 | } 64 | ``` 65 | 66 | >Note: In order for a user to send a join or spectate invite, Discord needs a `joinSecret` or `spectateSecret`. This means you should call `Discord_UpdatePresence()` even when a user is not actively in a group or game match. That way, Discord has all the data it needs to properly route a party request to other players. 67 | 68 | ## Knock knock! Who's there? You! 69 | 70 | Let's get into the meat of the callback functions: 71 | 72 | `ready()` lets you know when your game is connected to Discord, usually on a first connection or a reconnect. 73 | 74 | `joinGame()` and `spectateGame()` are up to you to handle and implement in your game's infrastructure. For these functions, we send you back either the `joinSecret` or `spectateSecret`, depending on which action happens. You should then reverse your secret back into usable data and handle it as necessary. More on what those secrets are and how to generate them later. 75 | 76 | `disconnect()` and `errored()` don't actually require you to do anything. If for some reason your client disconnects from Discord or encounters an error, we'll reconnect automatically. However, we will send you the events if you'd like to display them, log them, or ignore the problem like a good developer. 77 | 78 | The header file also contains the `Discord_RunCallbacks()` function. This invokes any pending callbacks from Discord on the calling thread (it's thread safe!), giving you ultimate control over your events. If you aren't sure what to do, just call it once per frame in your game's main loop. As Captain Planet says, the power is _yours_! 79 | 80 | ## Movin' with the payload 81 | 82 | Earlier, we showed an example payload of some really rich presence data. The full list of fields is as follows: 83 | 84 | ```cpp 85 | typedef struct DiscordRichPresence { 86 | const char* state; /* max 128 bytes */ 87 | const char* details; /* max 128 bytes */ 88 | int64_t startTimestamp; 89 | int64_t endTimestamp; 90 | const char* largeImageKey; /* max 32 bytes */ 91 | const char* largeImageText; /* max 128 bytes */ 92 | const char* smallImageKey; /* max 32 bytes */ 93 | const char* smallImageText; /* max 128 bytes */ 94 | const char* partyId; /* max 128 bytes */ 95 | int partySize; 96 | int partyMax; 97 | const char* matchSecret; /* max 128 bytes */ 98 | const char* joinSecret; /* max 128 bytes */ 99 | const char* spectateSecret; /* max 128 bytes */ 100 | int8_t instance; 101 | } DiscordRichPresence; 102 | ``` 103 | 104 | *Ooo, let's break it down!* 105 | 106 | __`state`__ is the user's current context. This could be "In Game," "In Queue," "Looking to Play," or any other states you want to denote. 107 | 108 | __`details`__ is a catch-all field that you can customize as you please. It's the first line of data displayed under the name of your game, and should display the most prominent data. For example, "Competitive | Match Type (Score)". 109 | 110 | __`startTimestamp`__ is the Unix timestamp (in seconds) at which the player entered their most recent instanced state, for example, a new game. Providing `startTimestamp` will cause the display time in the presence popout to count up from `00:00`. 111 | 112 | __`endTimestamp`__ is also a Unix timestamp (in seconds), but denotes at what time the player's current instanced state will end. Send this if you want us to do the math and display the timer as counting down to `00:00` from your timestamp. 113 | 114 | __`largeImageKey`__ and __`smallImageKey`__ are the key values for the artwork you have uploaded to your Developer Dashboard (more on that later!). __`largeImageText`__ and __`smallImageText`__ are the mouseover tooltips on the corresponding artwork. 115 | 116 | __`partyId`__ is the public id for the player's current party. Discord uses this to power party status and render dynamic party slots in the chat embeds. It is also required for join invites, but should not be sent for spectate invites. 117 | 118 | __`partySize`__ is the current size of the player's party. Sending `0` is the same as omitting it. 119 | 120 | __`partyMax`__ is the maximum allowed size for a party. Sending `0` means there is no limit on the size. 121 | 122 | __`matchSecret`__ works in tandem with `instance` to power the notification piece of Rich Presence. It's also used as an internal identifier for the player's current match/dungeon/raid so we can match presences for things like the `joinGame()` embed. When you send us a `matchSecret` with `instance` set to `true`, we know a further change in `matchSecret` means the player is done with whatever they were doing, or finally gave up on the Water Temple, and we can send a notification to anyone who subscribed. 123 | 124 | __`joinSecret`__ and __`spectateSecret`__ are unique, non-guessable data that serve as Discord's way to make callbacks to your game. These could be hashed or encrypted values of a player's id for `spectateSecret`, a lobby id and password for `joinSecret`, or any other data your game needs. Discord sends these values back to you in the appropriate callback functions. More on these in the next section. 125 | 126 | __`instance`__ helps Discord be smart about notifications and display. Setting it to `true` tells us to show the "Notify me" button and alert whoever clicks it when the `matchSecret` changes. 127 | 128 | >warn 129 | >The "Notify Me" feature is coming soon. If you want your game to support it on release, you should hook up the necessary fields now. 130 | 131 | We've chosen the fields based on common data between the most popular games on Discord, but they are by no means rigid. Play with them to fit the data you'd like to display for your game! You can also omit any of the fields, and the UI will gracefully adjust. Below is an image that shows which fields go where when sending a full data payload with spectating and notifications enabled; use it for reference for your own data: 132 | 133 | ![](rp-profile-view.png) 134 | 135 | ## Secrets, secrets are...fun! 136 | 137 | Security is of the utmost importance to us here at Discord, and we know it is for you, too. That's why we want to make sure that you properly understand `matchSecret`, `joinSecret`, and `spectateSecret` so that your game data is safe and secure over the wire. 138 | 139 | Secrets are obfuscated data of your choosing. They could be match ids, player ids, lobby ids, or your favorite color in hexadecimal over and over. You should send us data that someone else's game client would need to join or spectate their friend. If you can't or don't want to support those actions, you don't need to send us secrets. In fact, you could skip the rest of this section, but we all know that the real magic is _learning_. 140 | 141 | Your secrets on Discord need to be well-kept. When someone wants to join a friend's game, they hit the "Join" button. Discord checks to make sure their permissions are in order, and then passes their client the `joinSecret` so the callback can fire on their machine, and their game client can handle it. 142 | 143 | To keep security on the up and up, Discord requires that you properly hash/encode/encrypt/put-a-padlock-on-and-swallow-the-key-but-wait-then-how-would-you-open-it your secrets. There are more than a couple of ways of going about this, but here's a couple points to muse over: 144 | 145 | #### What does your game require to join a party, spectate a match, or other actions available through Rich Presence? 146 | 147 | The secrets you send us can be whatever data you want, so make life easy for yourself! If you need a `matchId`, `playerId`, `lobbyPassword`, and `bloodType` (we hope not), hash all of those up as your secret. Then, when you reverse the hash on callback, you'll have everything you need to complete the action. 148 | 149 | #### How good is your security? 150 | 151 | Just because you're doing it doesn't necessarily mean you're doing it in the best—and safest—way possible. Create your secrets on your server, not on your client, and consider using strong encryption methods (anyone seen my private key?) to keep your data safe. [Sodium](https://download.libsodium.org/doc/), a multi-language, cross-compilable crypto library, is a great place to start. It's available straight from [GitHub](https://github.com/jedisct1/libsodium), as a [pre-built library](https://download.libsodium.org/doc/installation/) for some common editors, and on [NuGet](https://www.nuget.org/packages?q=libsodium). It's so easy to use, even this example in C isn't scary: 152 | 153 | ```cpp 154 | #include 155 | 156 | unsigned char* myMessage = "a super secret message for Discord"; 157 | printf("Original text: %s \n \n", myMessage); 158 | 159 | int messageLength = strlen(myMessage) + 1; // Accounting for null terminator byte 160 | int ciphertextLength = crypto_secretbox_MACBYTES + messageLength; 161 | 162 | unsigned char nonce[crypto_secretbox_NONCEBYTES]; // Buffer for your nonce 163 | unsigned char key[crypto_secretbox_KEYBYTES]; // Buffer for your key 164 | unsigned char* ciphertext = malloc(ciphertextLength); 165 | 166 | randombytes_buf(nonce, sizeof nonce); 167 | randombytes_buf(key, sizeof key); 168 | crypto_secretbox_easy(ciphertext, myMessage, messageLength, nonce, key); 169 | 170 | char* hex = malloc(2 * ciphertextLength + 1); 171 | int hexLength = 2 * ciphertextLength + 1; 172 | sodium_bin2hex(hex, hexLength, ciphertext, ciphertextLength); 173 | printf("Encrypted: %s \n \n", hex); 174 | ``` 175 | 176 | We encrypt the data, and then convert it to hex for the sake of readability. Your key is then stored as `hex`, which is what you should send to Discord. And to unencrypt on callback: 177 | 178 | ```cpp 179 | unsigned char* decrypted = malloc(messageLength); 180 | unsigned char* bin = malloc(ciphertextLength); 181 | sodium_hex2bin(bin, ciphertextLength, hex, hexLength, "", NULL, NULL); 182 | crypto_secretbox_open_easy(decrypted, bin, ciphertextLength, nonce, key); 183 | printf("Decrypted: %s", decrypted); 184 | 185 | free(ciphertext); // Don't forget to free up the memory when you're done! 186 | free(decrypted); 187 | free(hex); 188 | free(bin); 189 | ``` 190 | 191 | Running this code snippet gives the following output: 192 | 193 | ``` 194 | Original text: a super secret message for Discord 195 | 196 | Encrypted: 1a4a00a71fac73a645f9bbbc09b089b986210a50c17a926543384c7548f1742d2f92d8d635967264196372fbf0363c879b76b8 197 | 198 | Decrypted: a super secret message for Discord 199 | ``` 200 | 201 | Discord maintains the highest standards of security for data, so we require that you hold yourself to those same standards if you wish to implement these secrets. Remember, it's for your benefit as well! We wouldn't want evildoers ending up in places they shouldn't be! 202 | 203 | ## There's a time and a place for everything 204 | 205 | All fields in the `DiscordRichPresence` object are entirely optional. Anything you choose to omit simply won't be displayed; the UI will dynamically adapt from the full Rich Presence object all the way down to the basic presence view. We highly encourage you to include as many fields as you can to make your game as attractive and interactive for other players as possible. However, if you choose to be a bit more selective, here's a handy table for what each piece of Rich Presence requires: 206 | 207 | ###### Rich Presence Field Requirements 208 | 209 | | Field | Custom Artwork | Notification | Spectating | Joining | 210 | | :------------: | :------------: | :----------: | :--------: | :------: | 211 | | state | | x | x | x | 212 | | details | | | | | 213 | | startTimestamp | | | | | 214 | | endTimestamp | | | | | 215 | | largeImageKey | x | | | | 216 | | smallImageKey | x | | | | 217 | | largeImageText | x | | | | 218 | | smallImageText | x | | | | 219 | | partyId | | | | x | 220 | | partySize | | | | x | 221 | | partyMax | | | | x | 222 | | matchSecret | | x | | | 223 | | joinSecret | | | | x | 224 | | spectateSecret | | | x | | 225 | | instance | | x | | | | 226 | 227 | ## Your New Developer Dashboard 228 | 229 | Included with the launch of Rich Presence is an overhaul of Discord's Developer Dashboard. We want to make Rich Presence and the rest of the GameBridge Suite as easy as possible to use. Our first step is helping you ditch your CDN. You're welcome. 230 | 231 | OK, well, not entirely. But! Discord _will_ host any and all artwork that you need to have the very richest of presences. Upload an image, tag it with a key—preferrably one you can remember—and **bam**. It's ready for Rich Presence use. Head over to your [applications page](#MY_APPLICATIONS/top) to check it out! 232 | 233 | ## It's always better when we're together 234 | 235 | Discord's Rich Presence system is an awesome way to get gamers together in your game. We've done the heavy lifting on the engineering side to make it easy-as-pie for you to implement. So get to coding and make your game's presence as rich as it can be! -------------------------------------------------------------------------------- /docs/topics/Voice_Connections.md: -------------------------------------------------------------------------------- 1 | # Voice 2 | 3 | Voice connections operate in a similar fashion to the [Gateway](#DOCS_GATEWAY/gateways) connection, however they operate on a different set of payloads, and utilize a separate UDP-based connection for voice data transmission. Because UDP is utilized for both the receiving and transmitting of voice, your client _must_ be able to receive UDP packets, even through a firewall or NAT (see [UDP Hole Punching](https://en.wikipedia.org/wiki/UDP_hole_punching) for more information). The Discord Voice servers implement functionality (see [IP Discovery](#DOCS_VOICE_CONNECTIONS/ip-discovery)) for discovering the local machines remote UDP IP/Port, which can assist in some network configurations. 4 | 5 | ## Voice Payloads and Events 6 | 7 | ### Voice Data Packet 8 | 9 | The voice data packet is a payload with an [encrypted voice packet header](#DOCS_VOICE_CONNECTIONS/encrypted-voice-packet-header-structure). The rest of the bytes in the payload are encrypted Opus audio data. 10 | 11 | ###### Voice Events 12 | 13 | | Code | Name | Description | 14 | |--------|----------|-----------------| 15 | | 0 | Identify | used to begin a voice websocket connection | 16 | | 1 | Select Protocol | used to select the voice protocol | 17 | | 2 | Ready | used to complete the websocket handshake | 18 | | 3 | Heartbeat | used to keep the websocket connection alive | 19 | | 4 | Session Description | used to describe the session | 20 | | 5 | Speaking | used to indicate which users are speaking | 21 | 22 | ## Connecting to Voice 23 | 24 | ### Retrieving Voice Server Information 25 | 26 | The first step in connecting to a voice server (and in turn, a guilds voice channel) is formulating a request that can be sent to the [Gateway](#DOCS_GATEWAY/gateways), which will return information about the voice server we will connect to. Because Discord's voice platform is widely distributed, users **should never** cache or save the results of this call. To inform the gateway of our intent to establish voice connectivity, we first send an [OP 4 Gateway Voice State Update](#DOCS_GATEWAY/gateway-voice-state-update). 27 | 28 | If our request succeeded, the gateway will respond with _two_ events (meaning your library must properly wait for both events before continuing), a [Voice State Update](#DOCS_GATEWAY/voice-state-update) _event_ (not a payload), and a [Voice Server Update](#DOCS_GATEWAY/voice-server-update) event. The first will contain a new key, `session_id` and the second will provide voice server information we can use to establish a new voice connection. With this information, we can move on to [Establishing a Voice Websocket Connection](#DOCS_VOICE_CONNECTIONS/establishing-a-voice-websocket-connection). 29 | 30 | ### Establishing a Voice Websocket Connection 31 | 32 | Once we retrieve a session_id, token, and endpoint information, we can connect and handshake with the voice server over another secure websocket. Unlike the gateway endpoint we receive in a HTTP [get gateway](#DOCS_GATEWAY/get-gateway) request, the endpoint received from our [Voice Server Update](#DOCS_GATEWAY/voice-server-update) payload does not contain a URL protocol, so some libraries may require manually prepending it (`wss://`) before connecting. Once connected to the voice websocket endpoint, we can send a OP0 Identify with our server id, user id, session id, and token. 33 | 34 | ###### Example Voice Identify Payload 35 | 36 | ```json 37 | { 38 | "server_id": "41771983423143937", 39 | "user_id": "104694319306248192", 40 | "session_id": "my_session_id", 41 | "token": "my_token" 42 | } 43 | ``` 44 | 45 | The voice server should respond with an OP2 Ready payload, which informs us of our `ssrc`, the UDP port, encryption modes supported and heartbeat_interval the voice server expects. Using this information, we can finally move on to [Establishing a Voice UDP Connection](#DOCS_VOICE_CONNECTIONS/establishing-a-voice-udp-connection). 46 | 47 | ###### Example Voice Ready Payload 48 | 49 | ```json 50 | { 51 | "ssrc": 1, 52 | "port": 1234, 53 | "modes": ["plain", "xsalsa20_poly1305"], 54 | "heartbeat_interval": 1 55 | } 56 | ``` 57 | 58 | ### Establishing a Voice UDP Connection 59 | 60 | Once we receive the properties of a UDP voice server from our OP2 ready payload, we can proceed to the final step of voice connections, which entails establishing and handshaking a UDP connection for voice data. First, we open a UDP connection to the same endpoint we originally received in the [Voice Server Update](#DOCS_GATEWAY/voice-server-update) payload, combined with the port we received in the Voice Ready payload. If required, we can now perform an [IP Discovery](#DOCS_VOICE_CONNECTIONS/ip-discovery) using this connection. Once we've fully discovered our external IP and UDP port, we can then tell the voice websocket what it is, and start receiving/sending data. We do this using the select protocol payload. 61 | 62 | >warn 63 | > The plain mode is deprecated and will be removed soon. All data should be sent using a supported encryption method (right now only `xsalsa20_poly1305`). 64 | 65 | ###### Example Select Protocol Payload 66 | 67 | ```json 68 | { 69 | "protocol": "udp", 70 | "data": { 71 | "address": "127.0.0.1", 72 | "port": 1337, 73 | "mode": "xsalsa20_poly1305" 74 | } 75 | } 76 | ``` 77 | 78 | Finally, the voice server will respond with a OP4 Session Description. We can now start encrypting and sending voice data over the previously established UDP connection. 79 | 80 | #### IP Discovery 81 | 82 | Generally routers on the internet mask or obfuscate UDP ports through a process called NAT. Most users who implement voice will want to utilize IP discovery to find their external IP and port which will then be used for receiving voice communications. To retrieve your external IP and port, send a 70-byte packet with empty data past the 4-byte ssrc. The server will respond back with another 70-byte packet, this time with a NULL-terminated string of the IP, with the port encoded in a **little endian** unsigned short stored in the last two bytes of the packet. 83 | 84 | ## Encrypting and Sending Voice 85 | 86 | Voice data sent to discord should be encoded with [Opus](https://www.opus-codec.org/), using 2 channels (stereo) and a sample rate of 48Khz. Voice Data is sent using a [RTP Header](http://www.rfcreader.com/#rfc3550_line548), followed by encrypted Opus audio data. Voice encryption uses the key passed in session description, combined with the 24 byte header (used as a nonce, appended with 12 null bytes), encrypted with [libsodium](https://download.libsodium.org/doc/). 87 | 88 | ###### Encrypted Voice Packet Header Structure 89 | 90 | | Field | Type | Size | 91 | |--------|--------|--------| 92 | | Type | Single byte value of `0x80` | 1 byte | 93 | | Version | Single byte value of `0x78` | 1 byte | 94 | | Sequence | unsigned short (big endian) | 2 bytes | 95 | | Timestamp | unsigned int (big endian) | 4 bytes | 96 | | SSRC | unsigned int (big endian) | 4 bytes | 97 | 98 | ### Speaking 99 | 100 | To notify clients that you are speaking or have stopped speaking, send an OP5 Speaking payload. 101 | 102 | ###### Example Speaking Payload 103 | 104 | ```json 105 | { 106 | "speaking": true, 107 | "delay": 0 108 | } 109 | ``` 110 | 111 | ### Voice Data Interpolation 112 | 113 | When there's a break in the sent data, the packet transmission shouldn't simply cut off but rather send five frames of silence (`0xF8, 0xFF, 0xFE`) before stopping to avoid unintended Opus interpolation with following transmissions. 114 | -------------------------------------------------------------------------------- /images/API_center.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Rapptz/discord-api-docs/8c98f72ef904a59a788651164654d2080c38dfc0/images/API_center.gif -------------------------------------------------------------------------------- /images/rp-profile-view.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Rapptz/discord-api-docs/8c98f72ef904a59a788651164654d2080c38dfc0/images/rp-profile-view.png -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | module.exports = {}; 2 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "discord-api-docs", 3 | "version": "1.1.0", 4 | "description": "Documentation for using Discord's API", 5 | "main": "index.js", 6 | "directories": { 7 | "doc": "docs" 8 | }, 9 | "repository": { 10 | "type": "git", 11 | "url": "git+https://github.com/hammerandchisel/discord-api-docs.git" 12 | }, 13 | "author": "Discord Krew", 14 | "license": "MIT", 15 | "bugs": { 16 | "url": "https://github.com/hammerandchisel/discord-api-docs/issues" 17 | }, 18 | "homepage": "https://github.com/hammerandchisel/discord-api-docs#readme" 19 | } 20 | --------------------------------------------------------------------------------