> ## Documentation Index
> Fetch the complete documentation index at: https://botpress.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Discord

> Add your bot to Discord using the official integration.

[Open in Hub](https://studio.botpress.cloud/home?exploreHub=1\&hubItemId=intver_01KREWJHF8AZMBHH3JC5XFSFTB)
*v1.2.1*

The official Discord integration allows users to chat with your bot in Discord servers, threads, and direct messages.

## Setup

> [!NOTE]
>
> You will need:
>
> * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> * A [Discord account](https://discord.com/) with permission to create applications

**1. Install the integration in Botpress**

First, install the integration to your bot:

1. In Botpress Studio, select \*\* Explore Hub\*\* in the upper-right corner.
2. Search for the **Discord** integration.
3. Select **Install Integration**.

In the **Configuration** menu, you should see one field:

* **Bot Token**

Leave it empty for now—you'll come back to it after completing the setup in Discord.

**2. Create a Discord application**

Next, create a Discord application:

1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and sign in.
2. Select **New Application** in the top-right corner.
3. Give your application a name and select **Create**.

**3. Create a bot user**

Now, create a bot user for your application:

1. In your application's left sidebar, select **Bot**.
2. Under the bot's username, you can optionally set a custom avatar and display name.
3. Under **Privileged Gateway Intents**, enable the following:
   * **Server Members Intent**
   * **Message Content Intent**
4. Select **Save Changes**.

**4. Copy your bot token**

Next, copy your bot's token:

1. Still on the **Bot** page, below **Token**, select **Reset Token** (or **Copy** if a token is already visible).
2. Confirm the reset if prompted.
3. Copy the token and store it somewhere safe—you will not be able to see it again.

> [!WARNING]
>
> Never share your bot token publicly or commit it to version control. Anyone with access to this token can control your bot.

**5. Invite the bot to your server**

Now, invite the bot to your Discord server:

1. In the left sidebar, select **OAuth2** > **OAuth2 URL Generator**.
2. Under **Scopes**, select:
   * `bot`
   * `applications.commands`
3. Under **Bot Permissions**, select the permissions your bot requires. At minimum:
   * **View Channels**
   * **Send Messages**
   * **Create Public Threads**
   * **Create Private Threads**
   * **Send Messages in Threads**
   * **Pin Messages**
   * **Attach Files**
   * **Read Message History**
   * **Add Reactions**
   * **Create Polls**
4. Copy the generated URL at the bottom of the page and open it in your browser.
5. Select the server you want to add the bot to and select **Authorize**.

**6. Configure the integration in Botpress**

In your Botpress integration configuration, click "Connect with OAuth", then follow the instructions in the wizard to fill out the following fields:

1. In the integration's **Bot Token** field, paste your Discord bot token.
2. Select **Save Configuration**.

> [!TIP]
>
> Your Discord integration is ready—users can now chat with your Botpress bot in Discord servers, threads, and direct messages.

***

## Options

The Discord integration's **Configuration** menu offers a few additional options:

### Custom display name / avatar

* Fill in the **Bot Name** field to display a custom name as the sender in Discord conversations.
* Fill in the **Bot Avatar URL** field to set a custom image as the bot's Discord avatar.

> [!NOTE]
>
> The avatar URL must be publicly accessible. Supported formats include PNG, JPG, and GIF.

***

## Cards

{/* vale off */}

Here's a reference for all [Cards](https://botpress.com/docs/studio/concepts/cards/introduction.md) available with the integration:

### Add Member Role

Add a role to a guild member

**input** `object`

**guildId** `string` *required*

The ID of the guild

**userId** `string` *required*

The ID of the user

**roleId** `string` *required*

The ID of the role to add

**reason** `string`

Reason for adding the role (appears in audit log)

**output** `object`

This Card has no output.

### Add Reaction

Create a reaction for the message

**input** `object`

**channelId** `string` *required*

The id of the channel

**messageId** `string` *required*

The id of the message

**emoji** `string` *required*

Can be either the actual emoji or its id

**output** `object`

This Card has no output.

### Ban User

Ban a user from a guild

**input** `object`

**guildId** `string` *required*

The ID of the guild

**userId** `string` *required*

The ID of the user to ban

**deleteMessageSeconds** `number`

Number of seconds of messages to delete (0-604800)

**reason** `string`

Reason for the ban (appears in audit log)

**output** `object`

This Card has no output.

### Call API

Send a raw HTTP request to any Discord API endpoint

**input** `object`

**path** `string` *required*

The API path (e.g. /channels/123/messages)

**queryParams** `array`

The query parameters to send along with the request

**array item properties**

**key** `string` *required*

**value** `string` *required*

**method** `enum\<string\>` *required*

The HTTP method to use

Available options: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`

**body** `string`

JSON string to send as the request body

**output** `object`

**success** `boolean` *required*

Whether the request was successful

**body** `string`

The response body as an object if the request was successful

**error** `string`

The error message if the request was not successful

**status** `number`

The HTTP status code of the response

### Create Channel

Creates a new channel in a guild.

**input** `object`

**guildId** `string` *required*

The ID of the guild to create the channel in

**name** `string` *required*

The name of the channel

**type** `number`

Channel type. Defaults to Guild Text (0).

**topic** `string`

Channel topic

**position** `number`

Sorting position of the channel

**nsfw** `boolean`

Whether the channel is NSFW

**parentId** `string`

ID of the parent category

**output** `object`

**id** `string` *required*

Channel ID

**type** `number` *required*

Channel type

**name** `string`

Channel name

**position** `number`

Sorting position of the channel

**parentId** `string | null`

**topic** `string | null`

**nsfw** `boolean`

Whether the channel is NSFW

### Create Poll

Creates a poll in a Discord channel.

**input** `object`

**channelId** `string` *required*

The ID of the channel to create the poll in

**question** `string` *required*

The question of the poll

**answers** `array` *required*

The answers available in the poll (1-10)

**array item properties**

**text** `string` *required*

The text of the answer

**emoji** `string`

An optional emoji for the answer

**duration** `number`

Number of hours the poll should be open for, up to 768 (32 days). Defaults to 24

**allowMultiselect** `boolean`

Whether a user can select multiple answers. Defaults to false

**output** `object`

**messageId** `string` *required*

The ID of the message containing the poll

**answers** `array` *required*

The poll answers with their Discord-assigned IDs

**array item properties**

**answerId** `number` *required*

The ID of the answer

**text** `string` *required*

The answer text

### Create Role

Create a new role in a guild

**input** `object`

**guildId** `string` *required*

The ID of the guild

**name** `string`

Name of the role

**color** `number`

RGB color value of the role

**hoist** `boolean`

Whether the role should be displayed separately in the sidebar

**mentionable** `boolean`

Whether the role can be mentioned

**reason** `string`

Reason for creating the role (appears in audit log)

**output** `object`

**id** `string` *required*

The ID of the created role

**name** `string` *required*

Name of the role

**color** `number` *required*

RGB color value of the role

**hoist** `boolean` *required*

Whether the role is displayed separately in the sidebar

**position** `number` *required*

Position of the role in the hierarchy

**permissions** `string` *required*

Bitwise permissions value of the role

**mentionable** `boolean` *required*

Whether the role can be mentioned

### Delete Channel

Deletes a channel from a guild.

**input** `object`

**channelId** `string` *required*

The ID of the channel to delete

**output** `object`

This Card has no output.

### Delete Reaction

Delete a reaction the current user has made for the message

**input** `object`

**channelId** `string` *required*

The id of the channel

**messageId** `string` *required*

The id of the message

**emoji** `string` *required*

Can be either the actual emoji or its id

**output** `object`

This Card has no output.

### Delete Role

Delete a role from a guild

**input** `object`

**guildId** `string` *required*

The ID of the guild

**roleId** `string` *required*

The ID of the role to delete

**reason** `string`

Reason for deleting the role (appears in audit log)

**output** `object`

This Card has no output.

### End Poll

Immediately end a poll in a channel

**input** `object`

**channelId** `string` *required*

The ID of the channel containing the poll

**messageId** `string` *required*

The ID of the message containing the poll

**output** `object`

**messageId** `string` *required*

The ID of the message with the ended poll

**poll** `object | null` *required*

### Get Channel Pins

Returns all pinned messages in the channel.

**input** `object`

**channelId** `string` *required*

The ID of the channel to retrieve pinned messages for

**output** `object`

**messages** `array` *required*

**array item properties**

**id** `string` *required*

Message ID

**channelId** `string` *required*

Channel ID

**guildId** `string | null`

**author** `object` *required*

**id** `string` *required*

User ID

**username** `string` *required*

Username

**discriminator** `string` *required*

User discriminator

**globalName** `string | null`

**avatar** `string | null`

**bot** `boolean`

Whether the user is a bot

**content** `string | null`

**timestamp** `string` *required*

When the message was sent (ISO8601)

**type** `number` *required*

Type of message

### Get Guild

Returns the guild object for the given ID

**input** `object`

**guildId** `string` *required*

The ID of the guild to retrieve

**withCounts** `boolean` (default: false)

When true, will return approximate member and presence counts for the guild

**output** `object`

**id** `string` *required*

Guild ID

**name** `string` *required*

Guild name

**icon** `string | null` *required*

**description** `string | null` *required*

**splash** `string | null` *required*

**discoverySplash** `string | null` *required*

**features** `array` *required*

Enabled guild features

**banner** `string | null` *required*

**ownerId** `string` *required*

ID of the guild owner

**region** `string | null`

**afkChannelId** `string | null` *required*

**afkTimeout** `number` *required*

AFK timeout in seconds

**verificationLevel** `number` *required*

Verification level required for the guild

**defaultMessageNotifications** `number` *required*

Default message notification level

**mfaLevel** `number` *required*

Required MFA level for the guild

**explicitContentFilter** `number` *required*

Explicit content filter level

**maxPresences** `number | null`

**maxMembers** `number`

Maximum number of members

**vanityUrlCode** `string | null` *required*

**premiumTier** `number` *required*

Premium tier (Server Boost level)

**premiumSubscriptionCount** `number`

Number of boosts

**systemChannelId** `string | null` *required*

**systemChannelFlags** `number` *required*

System channel flags

**rulesChannelId** `string | null` *required*

**publicUpdatesChannelId** `string | null` *required*

**safetyAlertsChannelId** `string | null`

**preferredLocale** `string` *required*

Preferred locale

**approximateMemberCount** `number`

Approximate number of members (only present when withCounts is true)

**approximatePresenceCount** `number`

Approximate number of online members (only present when withCounts is true)

**roles** `array` *required*

**array item properties**

**id** `string` *required*

The role ID

**name** `string` *required*

The role's name

**color** `number` *required*

RGB color value of the role

**hoist** `boolean` *required*

Whether the role is displayed separately in the sidebar

**position** `number` *required*

The role's position in the hierarchy

**permissions** `string` *required*

Bitwise permissions value of the role

**mentionable** `boolean` *required*

Whether the role can be mentioned

### Get Guild Channels

Returns a list of guild channel objects. Does not include threads.

**input** `object`

**guildId** `string` *required*

The ID of the guild to retrieve channels for

**output** `object`

**channels** `array` *required*

**array item properties**

**id** `string` *required*

Channel ID

**type** `number` *required*

Channel type

**name** `string`

Channel name

**position** `number`

Sorting position of the channel

**parentId** `string | null`

**topic** `string | null`

**nsfw** `boolean`

Whether the channel is NSFW

**lastMessageId** `string | null`

### Get Guild Member

Returns a guild member object for the specified user.

**input** `object`

**guildId** `string` *required*

The ID of the guild

**userId** `string` *required*

The ID of the user to retrieve

**output** `object`

**user** `object` *required*

**id** `string` *required*

User ID

**username** `string` *required*

Username

**discriminator** `string` *required*

User discriminator

**globalName** `string | null`

**avatar** `string | null`

**bot** `boolean`

Whether the user is a bot

**nick** `string | null`

**avatar** `string | null`

**roles** `array` *required*

Array of role IDs

**joinedAt** `string` *required*

When the user joined the guild (ISO8601)

**deaf** `boolean` *required*

Whether the user is deafened in voice channels

**mute** `boolean` *required*

Whether the user is muted in voice channels

### getOrCreateChannelConversation

Gets or Creates a botpress conversation from a discord channel

**input** `object`

**conversation** `object` *required*

**channelType** `enum\<string\>` *required*

The type of the discord channel

Available options: `dm`, `guildText`, `guildAnnouncement`, `announcementThread`, `publicThread`, `privateThread`

**channelId** `string` *required*

The discord channel id

**channelTitle** `string` *required*

The discord channel title

**guildId** `string`

The discord guild the channel is in

**output** `object`

**conversationId** `string` *required*

The Botpress ID of the created conversation

### Get or Create a User

Proactively create a user from a bot

**input** `object`

**name** `string`

The name of the user

**pictureUrl** `string`

The URL of the user profile picture

**email** `string`

The email of the user

**user** `object` *required*

**id** `string` *required*

The Discord user ID

**output** `object`

**userId** `string` *required*

The Botpress ID of the created user

### List Guild Members

Returns a list of guild member objects that are members of the guild.

**input** `object`

**guildId** `string` *required*

The ID of the guild to retrieve members for

**limit** `number`

Max number of members to return (1-1000), default 1

**after** `string`

The highest user id in the previous page, default "0"

**output** `object`

**members** `array` *required*

**array item properties**

**user** `object` *required*

**id** `string` *required*

User ID

**username** `string` *required*

Username

**discriminator** `string` *required*

User discriminator

**globalName** `string | null`

**avatar** `string | null`

**bot** `boolean`

Whether the user is a bot

**nick** `string | null`

**avatar** `string | null`

**roles** `array` *required*

Array of role IDs

**joinedAt** `string` *required*

When the user joined the guild (ISO8601)

**deaf** `boolean` *required*

Whether the user is deafened in voice channels

**mute** `boolean` *required*

Whether the user is muted in voice channels

### Pin Message

Pins a message in a channel.

**input** `object`

**channelId** `string` *required*

The ID of the channel containing the message

**messageId** `string` *required*

The ID of the message to pin

**output** `object`

This Card has no output.

### Remove Member Role

Remove a role from a guild member

**input** `object`

**guildId** `string` *required*

The ID of the guild

**userId** `string` *required*

The ID of the user

**roleId** `string` *required*

The ID of the role to remove

**reason** `string`

Reason for removing the role (appears in audit log)

**output** `object`

This Card has no output.

### Unban User

Remove a ban for a user from a guild

**input** `object`

**guildId** `string` *required*

The ID of the guild

**userId** `string` *required*

The ID of the user to unban

**reason** `string`

Reason for the unban (appears in audit log)

**output** `object`

This Card has no output.

### Unpin Message

Unpins a message in a channel.

**input** `object`

**channelId** `string` *required*

The ID of the channel containing the pinned message

**messageId** `string` *required*

The ID of the message to unpin

**output** `object`

This Card has no output.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.