Skip to Content
nyx logonyx guide

HTTP Overview

Reading time:3 min read

The @nyx-discord/http package lets an @discordjs/core bot receive interactions and webhook events over HTTP, instead of through a gateway connection.

Discord sends each interaction as a POST request to your app's Interactions Endpoint URL, so a bot that only handles commands and components doesn't need a long-lived connection at all. It can run on a regular server, or on serverless platforms like Cloudflare Workers or Vercel.

The framework doesn't ship a server and never opens a port. Our client takes a request and returns a response, and you pass requests to it from the server you already use: node:http, Express, Fastify, Hono, Next.js, Bun, Deno, Workers...

Installation

Installing

npm i @nyx-discord/http @discordjs/core

The package re-exports @nyx-discord/djs-core, so commands, events, schedules and everything else are imported from @nyx-discord/http. Everything in this guide that applies to @discordjs/core applies here too.

Creating the bot

HttpBot.create() works like @nyx-discord/djs-core's Bot.create(), but takes your application's ID and public key (both on the Developer Portal) instead of a client, and creates the client for you. Bot from @nyx-discord/http is HttpBot, so examples using Bot.create() or the Bot type work as-is:

import {  } from '@nyx-discord/http';

const  = .(() => ({
  : .APP_ID,
  : .DISCORD_PUBLIC_KEY,
  : .TOKEN,
  : ,
  : true,
}));

await .();

const client = .();
const client: HttpNyxClient

Requests are answered with 503 until bot.start() finishes, so nothing reaches your commands before they're registered.

Mounting the client

Pass incoming requests to the client from your server. See Mounting for each backend:

import {  } from 'node:http';
import {  } from '@nyx-discord/http';

((.())).(3000);

Setting the endpoint

On the Developer Portal, set your app's Interactions Endpoint URL to the public URL of that route. Discord sends a PING to check it, which the client answers by itself.

What's different from the gateway

  • Only interactions (InteractionCreate) and webhook events are emitted. Subscribers to any other gateway event (messages, members, guilds...) never fire.
  • Commands work unchanged: they reply through api.interactions.reply() and friends, as they do on the gateway. See Handling requests.
  • Schedules run while the process is alive. On serverless platforms, triggering them (e.g. with Workers cron triggers) is up to you, see Serverless.
  • Only the @discordjs/core adapter is supported, since discord.js structures need a gateway-backed Client.

Getting the bot

Inside commands, subscribers and schedules, TypedFields.getBot() gets the bot from the metadata, typed so its client is the HttpNyxClient (a shorthand for TypedFields.HttpBot.get(meta, true)):

import { , , type  } from '@nyx-discord/http';

class  extends  {
  protected readonly  = '0 * * * *';

  public async (: ) {
    const  = .();
    const client = .();
const client: HttpNyxClient
// Shorthand for bot.getClient().getApi(), the REST API const = .(); } }

@nyx-discord/http exports its own TypedFields, without @nyx-discord/djs-core's GatewayCoreBot and getClient(), since HTTP bots have no gateway client.

Edit on GitHub

Last updated on

On this page