Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/discord/discord-interactions-js

JS/Node helpers for Discord Interactions
https://github.com/discord/discord-interactions-js

Last synced: about 1 month ago
JSON representation

JS/Node helpers for Discord Interactions

Awesome Lists containing this project

README 

        
# discord-interactions



---

[![version](https://img.shields.io/npm/v/discord-interactions.svg)](https://www.npmjs.com/package/discord-interactions)

[![ci](https://github.com/discord/discord-interactions-js/actions/workflows/ci.yaml/badge.svg)](https://github.com/discord/discord-interactions-js/actions/workflows/ci.yaml)

![Downloads](https://img.shields.io/npm/dt/discord-interactions)



Types and helper functions that may come in handy when you implement a Discord Interactions webhook.



## Overview



This library provides a simple interface for working with slash commands and Discord.  You can build applications that allow users to use [Interactions](https://discord.com/developers/docs/interactions/overview) to send commands to your app.  When a user runs such a command, Discord will send an HTTP request to your web application.  This library makes it easier to:



- Verify that requests to your endpoint are actually coming from Discord

- Integrate verification with web frameworks that use [connect middleware](https://expressjs.com/en/guide/using-middleware.html) (like express)

- Use lightweight enums and TypeScript types to aid in handling request payloads and responses



To learn more about building on Discord, see [https://discord.dev](https://discord.dev).



## Installation



```sh

npm install discord-interactions

```



## Usage



Use the `InteractionType` and `InteractionResponseType` enums to figure out how to respond to a webhook.



Use `verifyKey` to check a request signature:



```js

 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');

 }

```



Note that `req.rawBody` must be populated by a middleware (it is also set by some cloud function providers).



If you're using an express-like API, you can simplify things by using the `verifyKeyMiddleware`.  For example:



```js

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',

      },

    });

  }

});

```



Make sure that you do not use other middlewares like `body-parser`, which tamper with the request body, for interaction routes.



### Interaction Types



The following enumerations are available to help working with interaction requests and responses. For more details, see the [examples](/examples/).



|                            |                                                                           |

|----------------------------|---------------------------------------------------------------------------|

| `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.                       |



### Message Components



This library contains lightweight TypeScript types and enums that are helpful when working with [Message Components](https://discord.com/developers/docs/interactions/message-components).  



|                         |                                                                                                                                                   |

|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|

| `MessageComponentTypes` | An enum of message component types that can be used in messages and modals.                                                                       |

| `ActionRow`             | Type for [Action Rows](https://discord.com/developers/docs/interactions/message-components#action-rows)                                           |

| `Button`                | Type for [Buttons](https://discord.com/developers/docs/interactions/message-components#buttons)                                                   |

| `ButtonStyleTypes`      | Enum of available [Button Styles](https://discord.com/developers/docs/interactions/message-components#button-object-button-styles)                |

| `StringSelect`          | Type for [String Selects](https://discord.com/developers/docs/interactions/message-components#select-menus)                                       |

| `StringSelectOption`    | Type for [String Select Options](https://discord.com/developers/docs/interactions/message-components#select-menu-object-select-option-structure)  |

| `InputText`             | Structure for `[Text Inputs](https://discord.com/developers/docs/interactions/message-components#text-inputs)                                     |

| `TextStyleTypes`        | Enum for [Text Style Types](https://discord.com/developers/docs/interactions/message-components#text-input-object-text-input-styles)              |



For a complete list of available TypeScript types, check out [discord-api-types](https://www.npmjs.com/package/discord-api-types) package.



## Learning more



To learn more about the Discord API, visit [https://discord.dev](https://discord.dev).