# Discord

{% hint style="info" %}
The following documentation is for **Discord v1.1.3** *(BDK)*.
{% endhint %}

## Overview

Discord is a communication platform featuring voice, video, and text messaging for communities and teams. This integration allows automated message sending, channel management, and bot interactions within Discord servers. Enhance team communication and automate Discord community management tasks.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **Discord**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

### Connect using Token

Connects to the Discord API using a token.

| Label | Description                                                                                                   | Type        |
| ----- | ------------------------------------------------------------------------------------------------------------- | ----------- |
| Token | The bot token used to authenticate with Discord's API. You can obtain this from the Discord Developer Portal. | `sensitive` |

## Procedures

### to get some (channels) from a guild

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Retrieves all channels from a specific guild.

**Input Concepts**

| Concept                   | Description                                                    | Type                                | Required | Default Value |
| ------------------------- | -------------------------------------------------------------- | ----------------------------------- | -------- | ------------- |
| [`guild`](#discord-guild) | The Guild object representing the server to get channels from. | `discord guild` or `discord server` | Yes      | (no default)  |

**Output Concepts**

| Concept                        | Description                                                          | Type                                         |
| ------------------------------ | -------------------------------------------------------------------- | -------------------------------------------- |
| [`channels`](#discord-channel) | A list of Channel objects containing information about each channel. | `discord channel` or `discord guild channel` |

**Examples**

Get all channels from a specific guild:

```generic
get some guilds
use the first guild
get some channels from the guild
```

Get channels by name:

```generic
get the guild's channels whose name is "general"
```

### to get some (guilds)

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Retrieves all guilds (servers) that the bot is a member of.

**Output Concepts**

| Concept                    | Description                                                             | Type                                |
| -------------------------- | ----------------------------------------------------------------------- | ----------------------------------- |
| [`guilds`](#discord-guild) | A list of Guild objects representing the servers the bot has access to. | `discord guild` or `discord server` |

**Examples**

Get all guilds the bot is in:

```generic
get some guilds
```

Get guilds and use them in further operations:

```generic
get some guilds
use the above as the servers
for each server in servers:
    get some channels from the server
```

Get the guilds with specific names:

```generic
get some guilds whose name is "Kognitos Discord Test Secret Server"
```

### to get some (members) from a guild

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Retrieves all members from a specific guild.

**Input Concepts**

| Concept                   | Description                                    | Type                                | Required | Default Value |
| ------------------------- | ---------------------------------------------- | ----------------------------------- | -------- | ------------- |
| [`guild`](#discord-guild) | The reference to the Guild that the bot is in. | `discord guild` or `discord server` | Yes      | (no default)  |

**Output Concepts**

| Concept                            | Description                                                             | Type                                       |
| ---------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------ |
| [`members`](#discord-guild-member) | A list of GuildMember objects containing information about each member. | `discord guild member` or `discord member` |

**Examples**

Get all members from a specific guild:

```generic
get some guilds
use the second guild as the guild
get some members from the guild
```

Get members by nick:

```generic
get the guild's member whose nick is "Integrations-Test"
```

### to send a (new message) to a channel

Sends a message to a specific channel.

**Input Concepts**

| Concept                                | Description                                                           | Type                                         | Required | Default Value |
| -------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------- | -------- | ------------- |
| [`channel`](#discord-channel)          | The Channel object representing where to send the message.            | `discord channel` or `discord guild channel` | Yes      | (no default)  |
| [`new message`](#discord-message-body) | The MessageBody object containing the message content and any embeds. | `discord message body`                       | Yes      | (no default)  |

**Output Concepts**

| Concept                           | Description                                     | Type              |
| --------------------------------- | ----------------------------------------------- | ----------------- |
| [`new message`](#discord-message) | A Message object representing the sent message. | `discord message` |

**Examples**

Get channels and send a message:

```generic
get some guilds
use the first guild as the guild
get some channels from the guild
use the first channel as the channel
get '{"content": "Hi Discord Channel!"}' as a json
use the above as the body
send the body to the channel
```

## Concepts

### Discord guild

Represents a Discord guild (server) with its basic properties.This class encapsulates information about a Discord server including its ID, name, ownership status, permissions, features, and visual elements like icons and banners.

ALSO : `discord server`

| Field Name                  | Description                                         | Type             |
| --------------------------- | --------------------------------------------------- | ---------------- |
| `id`                        | The unique identifier of the guild.                 | `text`           |
| `name`                      | The name of the guild.                              | `text`           |
| `owner`                     | Whether the current user is the owner of the guild. | `boolean`        |
| `permissions`               | The permissions the current user has in the guild.  | `text`           |
| [`features`](#list-of-text) | List of guild features enabled for this guild.      | `list of text`   |
| `icon`                      | Hash of the guild's icon image.                     | `optional[text]` |
| `banner`                    | Hash of the guild's banner image.                   | `optional[text]` |

### Discord channel

Represents a Discord channel within a guild.This class encapsulates information about a Discord channel including its ID, type, name, guild association, position in the channel list, and parent channel if applicable.

ALSO : `discord guild channel`

| Field Name  | Description                                              | Type               |
| ----------- | -------------------------------------------------------- | ------------------ |
| `id`        | The unique identifier of the channel.                    | `text`             |
| `type`      | The type of the channel as an integer.                   | `number`           |
| `name`      | The name of the channel.                                 | `optional[text]`   |
| `guild_id`  | The ID of the guild this channel belongs to.             | `optional[text]`   |
| `position`  | The position of the channel in the guild's channel list. | `optional[number]` |
| `parent_id` | The ID of this channel's parent category.                | `optional[text]`   |

### Discord guild member

Represents a member of a Discord guild (server).This class encapsulates guild\_member\_json specific to a user's membership in a guild, such as their nickname, roles, join date, and the base User object.

ALSO : `discord member`

| Field Name                     | Description                                                    | Type                 |
| ------------------------------ | -------------------------------------------------------------- | -------------------- |
| `user`                         | The User object containing the member's base user information. | `json`               |
| `nick`                         | The member's guild-specific nickname.                          | `optional[text]`     |
| `avatar`                       | The member's guild-specific avatar hash.                       | `optional[text]`     |
| [`roles`](#list-of-text)       | List of role IDs the member has in the guild.                  | `list of text`       |
| `joined_at`                    | Timestamp when the user joined the guild.                      | `datetime`           |
| `premium_since`                | Timestamp when the user started boosting the guild.            | `optional[datetime]` |
| `deaf`                         | Whether the member is deafened in voice channels.              | `boolean`            |
| `mute`                         | Whether the member is muted in voice channels.                 | `boolean`            |
| `flags`                        | The member's guild flags.                                      | `number`             |
| `pending`                      | Whether the member has passed membership screening.            | `optional[boolean]`  |
| `communication_disabled_until` | Timestamp when timeout will be removed.                        | `optional[datetime]` |
| `banner`                       | The member's guild-specific banner hash.                       | `optional[text]`     |
| `unusual_dm_activity_until`    | Timestamp for unusual DM activity timeout.                     | `optional[datetime]` |

### Discord user

Represents a Discord user with their profile information.This class encapsulates information about a Discord user including their ID, username, global name, discriminator, and various profile customization elements like avatars, banners, and decorations.

| Field Name               | Description                              | Type               |
| ------------------------ | ---------------------------------------- | ------------------ |
| `id`                     | The unique identifier of the user.       | `text`             |
| `username`               | The user's username on Discord.          | `text`             |
| `global_name`            | The user's global display name.          | `optional[text]`   |
| `discriminator`          | The user's discriminator number.         | `text`             |
| `accent_color`           | The user's profile accent color.         | `optional[number]` |
| `avatar`                 | Hash of the user's avatar image.         | `optional[text]`   |
| `avatar_decoration_data` | Data for the user's avatar decorations.  | `optional[any?]`   |
| `banner`                 | Hash of the user's profile banner image. | `optional[text]`   |
| `banner_color`           | The user's banner color.                 | `optional[text]`   |
| `clan`                   | Information about the user's clan.       | `optional[any?]`   |
| `collectibles`           | The user's collectible items.            | `optional[any?]`   |
| `flags`                  | The user's account flags.                | `optional[number]` |
| `primary_guild`          | The ID of the user's primary guild.      | `optional[text]`   |
| `public_flags`           | The user's public account flags.         | `optional[number]` |

### Discord message body

Represents the content of a message to be sent to Discord.This class provides a simplified structure for constructing message payloads, supporting both plain text content and rich embeds.

| Field Name | Description                                                  | Type                     |
| ---------- | ------------------------------------------------------------ | ------------------------ |
| `content`  | The text content of the message to be sent.                  | `optional[text]`         |
| `embeds`   | List of embedded rich content to be included in the message. | `optional[list of json]` |

### Discord message

Represents a Discord message with its core properties.This class encapsulates information about a Discord message including its ID, content text, and any rich embeds that may be part of the message.

| Field Name | Description                                   | Type                     |
| ---------- | --------------------------------------------- | ------------------------ |
| `id`       | The unique identifier of the message.         | `text`                   |
| `content`  | The text content of the message.              | `optional[text]`         |
| `embeds`   | List of embedded rich content in the message. | `optional[list of json]` |