Discord API Guide
How to work with Discord Gateways using the API Tester app
Last updated
How to work with Discord Gateways using the API Tester app
Last updated
Gateways are Discord's forms 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. To work with Discord Gateways, you must be registered in the system.
Authenticating with the Discord API can be done in one of two ways:
Using a bot token gained by registering a bot.
Using an OAuth2 bearer token gained through the OAuth2 API.
Let's look at authentication using a bot token gained by registering a bot.
Follow the link and tap "New app":
Next, enter the name and tap "Create".
Select "Bot" in the sidebar and tap "Add Bot".
Name your bot and tap "Reset Token". Copy the received value.
To add the Bot to the Discord channel we want to watch, go to the left side menu and select "OAuth2" and then select "URL Generator".
Under "scope" select the "bot" checkbox. From here we now have a URL at the bottom.
Navigate to this URL and you will have the option to select which server you want to add this Bot to. You should see a message in your General Chat that a bot was added.
Now we have a Discord bot, we can call the gateway endpoint to get a valid WSS endpoint. Open the API Tester app and create a new GET request. Endpoint:
From here you will get a simple response returning a WebSocket gateway URL like this:
Copy this URL:
You can import this request into API Tester app via these links:
curl -X GET 'https://discord.com/api/gateway'
Now let’s figure out how to interact with Discord using a WebSocket in API Tester app.
Go to "Create a new request" and tap the WebSocket icon.
Paste the URL you received at the previous step into the address field and tap Connect:
The first response from Discord typically looks like this:
Identification is used to trigger the initial handshake with the gateway. Insert this code and tap Send:
Insert your token generated when creating the bot in the token field.
After sending it you should receive a READY message in the connection window. This lets you know you have successfully authenticated. Sometimes if it is your first time interacting with a server you will see a GUILD_CREATE message as well. This is just Discord creating some metadata attached to your Discord bot and the server you connected to.
If the connection is closed, reconnect and send the identification message again.
You can import this request into API Tester app via these links:
curl -X WS 'wss://gateway.discord.gg'
Now, when we are authenticated in our WebSocket connection, let's create a message in the General chat of the server you added the bot to, or invite someone, or have someone to join.
You will see a new message received on the WebSocket connection, even if you didn’t create a WebSocket request!
Checking this MESSAGE_CREATE message, you should see the details of the message and the user who created it. Even if it was not you, all in real-time. As another example, we'll create a new channel.
You could monitor and manage your channel events all from API Tester now!
Used to request all members for a guild or a list of guilds. For this request, we need the ID of the guild to which the bot has been added. You can get it by going to the guild page. The first set of digits in the address bar is the desired value. Insert the ID for the "guild_id" key:
For the "query" key, enter the username to search for it. The server will return the objects of the users satisfying the search.
