# Discord Integration

The Discord integration lets users raise support tickets directly from your Discord server. When a ticket is created, the bot opens a dedicated thread or channel, posts a rich embed, and keeps it in sync with the web dashboard.

## Overview

* Users click a **Raise a Ticket** button posted by the bot in your support channel
* A modal collects the subject and description
* The bot creates a ticket in the dashboard and opens a private thread or channel
* Staff can claim, close, and update tickets from either Discord or the web dashboard
* Replies made in the web dashboard are posted back to the Discord thread

## 1. Create a Discord application and bot

{% stepper %}
{% step %}

### Go to the Discord Developer Portal

Go to [discord.com/developers/applications](https://discord.com/developers/applications) and click **New Application**.
{% endstep %}

{% step %}

### Name the application

Give it a name (e.g. `DrakoTickets`) and click **Create**.
{% endstep %}

{% step %}

### Add a bot

Open the **Bot** tab and click **Add Bot**.
{% endstep %}

{% step %}

### Copy the bot token

Under **Token**, click **Reset Token** and copy the token — you will need this shortly.
{% endstep %}

{% step %}

### Enable privileged gateway intents

Scroll down to **Privileged Gateway Intents** and enable:

* **Server Members Intent**
* **Message Content Intent**
  {% endstep %}

{% step %}

### Save changes

Click **Save Changes**.
{% endstep %}
{% endstepper %}

## 2. Set the bot token in your environment

Add the token to your `.env.local` (or Vercel environment variables):

```env
DISCORD_BOT_TOKEN=your-discord-bot-token
```

Restart the application after adding this variable.

## 3. Invite the bot to your server

{% stepper %}
{% step %}

### Open the URL Generator

In the Developer Portal, open the **OAuth2 → URL Generator** tab.
{% endstep %}

{% step %}

### Select the required scopes

Under **Scopes**, select `bot` and `applications.commands`.
{% endstep %}

{% step %}

### Select bot permissions

Under **Bot Permissions**, select:

* Manage Channels
* Send Messages
* Embed Links
* Read Message History
* Manage Threads
* Create Public Threads
* Create Private Threads
  {% endstep %}

{% step %}

### Invite the bot

Copy the generated URL and open it in your browser to invite the bot to your server.
{% endstep %}
{% endstepper %}

## 4. Enable Developer Mode in Discord

You need Developer Mode on to copy IDs.

{% stepper %}
{% step %}

### Enable Developer Mode

Open Discord → User Settings → Advanced → Enable **Developer Mode**.
{% endstep %}

{% step %}

### Copy IDs

You can now right-click any server, channel, or role and select **Copy ID**.
{% endstep %}
{% endstepper %}

## 5. Configure the bot in the dashboard

Go to **Settings → Discord** and fill in the following fields.

### Bot Configuration

| Field                        | How to get it                                                                  |
| ---------------------------- | ------------------------------------------------------------------------------ |
| Guild (Server) ID            | Right-click your server name → Copy Server ID                                  |
| Support Channel ID           | Right-click the channel where the ticket button will appear → Copy Channel ID  |
| Support Role ID *(optional)* | Right-click the role that should have access to ticket channels → Copy Role ID |

### Ticket Channel Mode

Choose how new tickets are created in Discord:

* **Thread** — creates a private thread inside the support channel (recommended, keeps the channel tidy)
* **Channel** — creates a new channel inside a category

If you choose **Channel**, also fill in the **Ticket Category ID** (right-click the category → Copy ID).

## 6. Post the support panel

Once the bot configuration is saved, click **Post Panel** in the dashboard. The bot will post an embed with a **Raise a Ticket** button to your support channel. Users click this button to open the ticket creation modal.

{% hint style="info" %}
You only need to post the panel once. If you update the embed appearance, click **Update Embed** to refresh the existing message without re-posting.
{% endhint %}

## Customising the embeds

### Support panel embed

This is the message that sits in your support channel with the button.

| Field              | Description                               |
| ------------------ | ----------------------------------------- |
| Title              | Heading of the embed, e.g. `Support`      |
| Description        | Body text shown below the title           |
| Colour             | Hex colour of the embed's left border     |
| Image URL          | Optional large image shown in the embed   |
| Footer Text / Icon | Optional footer line at the bottom        |
| Author Name / Icon | Optional author line at the top           |
| Button Label       | Text on the button, e.g. `Raise a Ticket` |
| Button Emoji       | Emoji shown on the button, e.g. `🎫`      |

### Ticket embed

This is the embed posted inside each new ticket thread or channel.

| Field           | Description                                                  |
| --------------- | ------------------------------------------------------------ |
| Title           | Heading, e.g. `🎫 New Support Ticket`                        |
| Colour          | Hex colour of the embed                                      |
| Description     | Template for the embed body — supports variables (see below) |
| Footer / Author | Same as the panel embed                                      |
| Show Thumbnail  | Shows the requester's Discord avatar in the top-right corner |

#### Available template variables

| Variable          | Description                                            |
| ----------------- | ------------------------------------------------------ |
| `{user}`          | The Discord username of the requester                  |
| `{ticket_number}` | The ticket number, e.g. `TK-0042`                      |
| `{subject}`       | The ticket subject entered in the modal                |
| `{description}`   | The ticket description entered in the modal            |
| `{response_time}` | Expected response time (from SLA policy if configured) |
| `{claimed_by}`    | The technician who claimed the ticket, or `Unclaimed`  |

## Troubleshooting

**The bot is online but the panel button does nothing**

* Make sure `APP_PROTOCOL`, `APP_HOST`, and `APP_PORT` are set correctly so the bot can reach the web app's interaction endpoint at `/api/discord/interaction`.
* Check that the bot has the **applications.commands** scope.

**Ticket channels are not being created**

* Verify the bot has **Manage Channels** permission in the category or server.
* If using Channel mode, confirm the **Ticket Category ID** is correct.

**Replies from the dashboard are not appearing in Discord**

* Ensure `DISCORD_BOT_TOKEN` is set and the bot is still in the server.
* Check the server logs for `[discord/update-embed]` errors.