discord-interactions-js

To run the provided examples, build the project, export your Discord App Public Key, and run the desired example file using Node.js.

npm run build 
export CLIENT_PUBLIC_KEY=${Your Discord App Public Key} 
node examples/express_app.js # or choose a different example

Install the library via npm to use its types and helper functions for Discord webhooks, interactions, and events.

npm install discord-interactions

To ensure requests to your endpoint are actually coming from Discord, use the verifyKey function. You must provide the raw request body, the X-Signature-Ed25519 header, the X-Signature-Timestamp header, and your Discord App Public Key.

Important: req.rawBody must be populated by a middleware. Do not use middlewares like body-parser on interaction routes as they can tamper with the raw body and cause verification to fail.

const signature = req.get('X-Signature-Ed25519');
const timestamp = req.get('X-Signature-Timestamp');
const isValidRequest = await verifyKey(req.rawBody, signature, timestamp, 'MY_CLIENT_PUBLIC_KEY');
if (!isValidRequest) {
  return res.status(401).end('Bad request signature');
}

To verify real-time notifications (Webhook Events) from Discord, use verifyKey with the same parameters as interaction verification. For Express-like APIs, use verifyWebhookEventMiddleware to simplify the process.

app.post(
	'/events',
	verifyWebhookEventMiddleware(process.env.CLIENT_PUBLIC_KEY),
	(req, res) => {
		console.log("📨 Event Received!")
        console.log(req.body);
	},
);

If you are using an Express-like framework, you can use verifyKeyMiddleware to automatically handle signature verification for interaction routes. This simplifies your route handlers by abstracting the signature check.

app.post('/interactions', verifyKeyMiddleware('MY_CLIENT_PUBLIC_KEY'), (req, res) => {
  const message = req.body;
  if (message.type === InteractionType.APPLICATION_COMMAND) {
    res.send({
      type: InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE,
      data: {
        content: 'Hello world',
      },
    });
  }
});

Use these enums to process incoming event webhooks.

| Enum | Description |
|---|---|
| `WebhookType` | An enum of interaction types that can be POSTed to your webhook endpoint. |
| `WebhookEventType` | An enum of response types you may provide in reply to Discord's webhook. |

These enumerations help identify the type of interaction received and the type of response your application should provide to Discord.

| Enum | Description |
|---|---|
| `InteractionType` | An enum of interaction types that can be POSTed to your webhook endpoint. |
| `InteractionResponseType` | An enum of response types you may provide in reply to Discord's webhook. |
| `InteractionResponseFlags` | An enum of flags you can set on your response data. |

Use verifyKey to manually validate that an incoming request payload from Discord is authentic. This is useful if you are not using the provided Express middleware.

Parameters:

• rawBody: The raw payload data (can be Uint8Array, ArrayBuffer, Buffer, or string).
• signature: The signature string from the X-Signature-Ed25519 header.
• timestamp: The timestamp string from the X-Signature-Timestamp header.
• clientPublicKey: Your Discord application's public key (as a hex string or a CryptoKey).

Returns: A Promise<boolean> which is true if the signature is valid, false otherwise.

import { verifyKey } from 'discord-interactions';

const isValid = await verifyKey(
  rawBody,
  signatureHeader,
  timestampHeader,
  CLIENT_PUBLIC_KEY
);

The TextInput component is used to collect text input from a user (typically within a Modal).

Key properties:

• custom_id: Unique identifier for the input.
• style: Either TextStyleTypes.SHORT or TextStyleTypes.PARAGRAPH.
• label: The label displayed above the input.
• min_length / max_length: Constraints on the input size.
• required: Whether the input must be filled.
• placeholder: Hint text shown in the input.

const textInput: TextInput = {
  type: MessageComponentTypes.INPUT_TEXT,
  custom_id: 'user_feedback',
  style: TextStyleTypes.PARAGRAPH,
  label: 'Your Feedback',
  placeholder: 'Please enter your thoughts...',
  required: true
};