Handling requests
How the client answers Discord, and how commands reply.
Responses
Every request goes through the same checks before it reaches your bot:
| Request | Response |
|---|---|
Before bot.start() finishes | 503 |
| Missing or invalid signature | 401 |
Timestamp older (or newer) than maxTimestampAge | 401 |
| Body that isn't valid JSON | 400 |
Interaction PING (Discord checking your URL) | 200 with a PONG |
| Any other interaction | 202 with no body |
Webhook event or its PING | 204 with no body |
Rejecting old timestamps protects against replayed requests: someone who captured a valid request can't send it again later. The window is 5 minutes by default, see Configuration.
Replying to interactions
Over the gateway, commands reply by calling Discord's REST API, like api.interactions.reply(). Over HTTP they do exactly the same: Discord accepts interaction responses through the REST callback endpoint, as long as the HTTP request itself is answered with a 202.
This means commands, components and autocompletes written for @discordjs/core work unchanged:
import { } from '@nyx-discord/http';
class extends {
public async ({ , }: <>) {
await ..(., ., { : 'Pong!' });
}
}The client doesn't answer Discord's request right away. It waits until the interaction is acknowledged (any reply, defer, update, modal or autocomplete response), until the handlers finish without acknowledging it (for example, when no command matches), or until acknowledgeTimeout passes (3 seconds by default), and then returns the 202. Discord requires the first response within 3 seconds, so slow commands should defer first, exactly like on the gateway.
Reading the request
TypedFields.HttpRequest gets the HTTP request an interaction or webhook event came from, from the metadata of commands, components and subscribers. Its raw property is the original request from your server or runtime, so you can read anything else from it, like headers:
import { , , type } from '@nyx-discord/http';
class extends {
public async ({ , }: <>, : ) {
const request = ..();
// raw is a fetch Request with toFetchHandler, or a node:http IncomingMessage with toNodeListener
const = ?. instanceof ? ...('cf-ipcountry') : null;
await ..(., ., { : `You're in ${ ?? 'somewhere'}` });
}
}HttpBot sets this up for you. If you create the HttpNyxClient yourself, add the field to the client event bus once the bot is created:
import { } from '@nyx-discord/http';
.().().(., () => .());The client only knows which request it's emitting while its listeners are being called, so this relies on the bus creating its metadata as soon as it receives an event, before awaiting anything. nyx's default buses do. A custom bus that doesn't would see null.
Serverless platforms
On serverless platforms, the runtime may stop once the response is sent. Anything your command does after its first reply (follow-ups, edits, other API calls) can then be cut off.
Every result from the client has a handled promise, which settles once the request's handlers finish: your commands, components and subscribers. Pass it to your platform's tool for keeping work alive, like ctx.waitUntil() on Cloudflare Workers or after() on Next.js.
toFetchHandler() does it for you when you pass a context with waitUntil as its second argument, see Mounting. When calling handle() yourself:
const = await .();
.(.);Webhook events need this the most: the client answers them right away, before any subscriber runs.
Last updated on
