Skip to Content
nyx logonyx guide

Handling requests

How the client answers Discord, and how commands reply.

Reading time:4 min read

Responses

Every request goes through the same checks before it reaches your bot:

RequestResponse
Before bot.start() finishes503
Missing or invalid signature401
Timestamp older (or newer) than maxTimestampAge401
Body that isn't valid JSON400
Interaction PING (Discord checking your URL)200 with a PONG
Any other interaction202 with no body
Webhook event or its PING204 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 = ..();
const request: HttpEndpointRequest | null | undefined
// 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.

Edit on GitHub

Last updated on

On this page