Discord Integration

The Discord integration allows you to connect Discord bot for server management and link user Discord accounts for notifications and verification.

Overview

Bounty’s Discord integration provides:

User Account Linking: Connect Discord accounts to Bounty profiles
Bot Installation: Add the Bounty bot to your Discord server
Webhook Notifications: Send bounty updates to Discord channels
Guild Management: Track which servers have the bot installed

Prerequisites

Discord account with server management permissions
Discord Application with OAuth2 and Bot configured

Discord Application Setup

Create Discord Application

Go to the Discord Developer Portal and click New Application.Give your application a name (e.g., “Bounty Bot”).

Configure OAuth2

In your application settings, navigate to OAuth2 → General.Add redirect URLs:

Development: http://localhost:3000/api/auth/callback/discord
Production: https://your-domain.com/api/auth/callback/discord

Copy your Client ID and Client Secret.

Configure Bot

Navigate to the Bot section in your application.Click Add Bot if you haven’t already.Configure bot settings:

Public Bot: Enable if you want others to add your bot
Requires OAuth2 Code Grant: Disable
Privileged Gateway Intents: Enable as needed

Set Bot Permissions

The Bounty bot requires the following permissions:

Send Messages - Post notifications
Embed Links - Rich embeds for bounty updates
Read Message History - Context for commands

Permission integer: 2147485696

Configure Environment Variables

Add the following to your .env file:

# Discord OAuth
DISCORD_CLIENT_ID="your_discord_client_id"
DISCORD_CLIENT_SECRET="your_discord_client_secret"

# Discord Server
DISCORD_INVITE_URL="https://discord.gg/your_server"

# Discord Webhooks
DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."
BOUNTY_FEED_WEBHOOK_URL="https://discord.com/api/webhooks/..."

Setting Up Webhooks

Discord webhooks allow Bounty to send notifications to specific channels.

Navigate to Server Settings

In your Discord server, go to Server Settings → Integrations → Webhooks.

Create New Webhook

Click New Webhook and configure:

Name: Bounty Notifications
Channel: Select the channel for bounty updates
Avatar: Upload a logo (optional)

Copy Webhook URL

Click Copy Webhook URL and add it to your environment variables:

DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/123.../abc..."

For bounty-specific feeds:

BOUNTY_FEED_WEBHOOK_URL="https://discord.com/api/webhooks/456.../def..."

You can create multiple webhooks for different notification types (e.g., one for general updates, one for high-value bounties).

User Account Linking

Users can link their Discord accounts to their Bounty profiles.

Linking Process

Navigate to Account Settings

Users go to their Bounty profile settings.

Click Connect Discord

The system redirects to Discord’s OAuth authorization page.

Authorize Application

Users grant permission to:

Identify their Discord account
Access basic profile information

Account Linked

After authorization, the Discord account is linked and visible in settings.

Viewing Linked Account

API endpoint: discord.getLinkedAccount

const { linked, account } = await trpc.discord.getLinkedAccount.query();

if (linked && account) {
  console.log(account.username);     // Discord username
  console.log(account.globalName);   // Display name
  console.log(account.discordId);    // Discord user ID
  console.log(account.avatar);       // Avatar URL
  console.log(account.linkedAt);     // When linked
}

Unlinking Account

API endpoint: discord.unlinkAccount

await trpc.discord.unlinkAccount.mutate();
// Removes Discord account connection

Bot Installation

Add the Bounty bot to your Discord server to enable notifications and commands.

Getting the Bot Install URL

API endpoint: discord.getBotInstallUrl

const { url, configured } = await trpc.discord.getBotInstallUrl.query();

if (configured && url) {
  // Redirect user to install URL
  window.location.href = url;
}

The install URL includes:

Client ID from DISCORD_CLIENT_ID
Required permissions (2147485696)
OAuth scopes: bot and applications.commands

Manual Installation

To manually construct the bot install URL:

https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=2147485696&scope=bot%20applications.commands

Replace YOUR_CLIENT_ID with your Discord application’s client ID.

Guild Management

Track which Discord servers (guilds) have the Bounty bot installed.

Viewing Connected Guilds

API endpoint: discord.getGuilds

const { guilds, userGuildIds } = await trpc.discord.getGuilds.query();

// guilds: Servers where the bot is installed AND user is a member
// userGuildIds: All servers the user is in

guilds.forEach(guild => {
  console.log(guild.name);         // Server name
  console.log(guild.icon);         // Server icon URL
  console.log(guild.memberCount);  // Number of members
  console.log(guild.installedAt);  // When bot was added
});

How It Works

Fetches user’s Discord guilds from Discord API using their OAuth token
Queries the database for guilds where:
- Bot is installed (removedAt is null)
- User is a member (guild ID matches)
- Guild belongs to the active organization
Returns the intersection of bot-installed servers and user’s servers

Webhook Notifications

Bounty sends Discord webhook notifications for key events.

Bounty Created/Funded

When a bounty is funded, a notification is sent:

{
  "embeds": [{
    "title": "🎯 New Bounty: Fix Authentication Bug",
    "description": "A detailed description of the bounty...",
    "fields": [
      { "name": "Amount", "value": "$500 USD", "inline": true },
      { "name": "Deadline", "value": "2026-04-01", "inline": true },
      { "name": "Repository", "value": "owner/repo", "inline": true }
    ],
    "url": "https://bounty.new/bounty/abc123",
    "color": 5814783
  }]
}

Configured via BOUNTY_FEED_WEBHOOK_URL or DISCORD_WEBHOOK_URL.

Implementation

Webhooks are sent from the Stripe webhook handler after successful payment:

// Triggered when bounty becomes funded
await sendBountyCreatedWebhook({
  webhookUrl: env.BOUNTY_FEED_WEBHOOK_URL,
  bounty: {
    id: bountyRecord.id,
    title: bountyRecord.title,
    amount: bountyRecord.amount,
    currency: bountyRecord.currency,
    bountyUrl: `${baseUrl}/bounty/${bountyRecord.id}`,
    // ... additional fields
  },
});

Webhook failures are logged but don’t affect payment processing. They’re fire-and-forget to prevent payment delays.

Permissions Reference

The bot requires specific Discord permissions:

Permission	Value	Purpose
Send Messages	`2048`	Post notifications
Embed Links	`16384`	Rich embeds
Read Message History	`65536`	Context for commands
Total	2147485696	Combined permissions integer

To calculate custom permissions, use Discord’s Permission Calculator.

Troubleshooting

Bot Install URL Not Working

Cause: DISCORD_CLIENT_ID not configured. Solution: Ensure DISCORD_CLIENT_ID is set in your environment variables.

const { configured } = await trpc.discord.getBotInstallUrl.query();
if (!configured) {
  // Show error: Discord bot not configured
}

User Guilds Not Loading

Cause: Discord OAuth token expired or user hasn’t linked Discord. Solution:

Check if user has linked Discord account
If linked, token may have expired - ask user to reconnect
Verify guilds scope is included in OAuth flow

Webhook Not Sending

Checklist:

Verify DISCORD_WEBHOOK_URL or BOUNTY_FEED_WEBHOOK_URL is set
Check webhook URL is valid and channel exists
Ensure webhook wasn’t deleted in Discord server settings
Review server logs for webhook errors

”Failed to fetch user guilds”

Causes:

Access token expired
User revoked access
Discord API downtime

Solution:

Ask user to reconnect Discord account
Check Discord API status: https://discordstatus.com
Verify OAuth scopes include guilds

API Reference

`getBotInstallUrl`

Generates the Discord bot installation URL. Returns: { url: string | null, configured: boolean }

`getLinkedAccount`

Retrieve the user’s linked Discord account. Returns: { linked: boolean, account: DiscordAccount | null }

`unlinkAccount`

Remove the Discord account connection. Returns: { success: boolean }

`getGuilds`

Get Discord servers where the bot is installed and the user is a member. Scoped to: Active organization Returns: { guilds: Guild[], userGuildIds: string[] }

Security Considerations

Never expose your Discord Client Secret or webhook URLs publicly. Store them securely in environment variables.

OAuth tokens are stored encrypted in the database
Webhook URLs should be treated as secrets
Bot tokens (if used) must never be committed to version control
Use HTTPS for all webhook endpoints in production

Get Started

Core Features

Integrations

Self-Hosting

Discord Integration

Overview

Prerequisites

Discord Application Setup

Setting Up Webhooks

User Account Linking

Linking Process

Viewing Linked Account

Unlinking Account

Bot Installation

Getting the Bot Install URL

Manual Installation

Guild Management

Viewing Connected Guilds

How It Works

Webhook Notifications

Bounty Created/Funded

Implementation

Permissions Reference

Troubleshooting

Bot Install URL Not Working

User Guilds Not Loading

Webhook Not Sending

”Failed to fetch user guilds”

API Reference

`getBotInstallUrl`

`getLinkedAccount`

`unlinkAccount`

`getGuilds`

Security Considerations

Build docs developers (and LLMs) love

Get Started

Core Features

Integrations

Self-Hosting

​Overview

​Prerequisites

​Discord Application Setup

​Setting Up Webhooks

​User Account Linking

​Linking Process

​Viewing Linked Account

​Unlinking Account

​Bot Installation

​Getting the Bot Install URL

​Manual Installation

​Guild Management

​Viewing Connected Guilds

​How It Works

​Webhook Notifications

​Bounty Created/Funded

​Implementation

​Permissions Reference

​Troubleshooting

​Bot Install URL Not Working

​User Guilds Not Loading

​Webhook Not Sending

​”Failed to fetch user guilds”

​API Reference

​getBotInstallUrl

​getLinkedAccount

​unlinkAccount

​getGuilds

​Security Considerations

Build docs developers (and LLMs) love

Overview

Prerequisites

Discord Application Setup

Setting Up Webhooks

User Account Linking

Linking Process

Viewing Linked Account

Unlinking Account

Bot Installation

Getting the Bot Install URL

Manual Installation

Guild Management

Viewing Connected Guilds

How It Works

Webhook Notifications

Bounty Created/Funded

Implementation

Permissions Reference

Troubleshooting

Bot Install URL Not Working

User Guilds Not Loading

Webhook Not Sending

”Failed to fetch user guilds”

API Reference

`getBotInstallUrl`

`getLinkedAccount`

`unlinkAccount`

`getGuilds`

Security Considerations