Using Community Invites

Community invites extend Discord's invite system with two API-powered features: the role_ids parameter for automatic role assignment, and the target_users_file parameter for restricting which users can accept an invite.

This tutorial will walk you through using community invites programmatically in your bot or app. By the end, you'll know how to:

• Create invites that assign roles through the API
• Create targeted invites for specific groups of users through the API

Community invites extend Discord's existing invite system with two powerful features designed for game integrations:

When using the API, the role_ids parameter lets you specify one or more Discord roles that will be automatically assigned when a player accepts the invite. No manual role management needed.

Example use cases:

• Giving roles to supporters
• Giving roles related to characters or achievements from your game
• Giving roles that have permissions to access channels

Setting which users that are allowed to accept an invite can only be done through the Discord API. The target_users_file parameter accepts a CSV file containing Discord user IDs. Only users in that list can see and accept the invite.

Example use cases:

• Preventing invite sharing for exclusive achievements (for example, create a unique invite for a player with a 100% completion role)
• When combined with roles to give out mod/admin privileges
• Combined with roles to give special roles/channel access to paying supporters

These features work with all standard invite parameters like max_age, max_uses, and more.

In this example, we'll show you how to grant roles as part of an invite using the channel invite API. We'll take a look at what a game developer could do to connect their game back to their Discord server.

Before you begin, make sure you have:

• A Discord server for testing
• Developer Mode enabled on your account (so you can copy role, channel, and user IDs)
• A Discord app with a bot token (create one in the Developer Portal)
• Node.js installed, or the ability to make HTTP requests from your bot or app
• Bot permissions for:
  • Create Instant Invite (required to create invites)
  • Manage Roles (required for automatic role assignment with role_ids)

When players join your Discord server from your game, you can give them a Player role for access to game-specific channels. Here's how to create an invite that does this automatically:

// IMPORTANT: Never hardcode tokens or commit them to version control
// Use environment variables or a secure configuration management system
// Replace the placeholder below with your actual bot token, channel ID, and role ID
const BOT_TOKEN = 'REPLACE_WITH_YOUR_BOT_TOKEN_FROM_THE_DEV_PORTAL';
const CHANNEL_ID = '1234567890123456789';
const ROLE_ID = '9876543210987654321';

const response = await fetch(
    `https://discord.com/api/v10/channels/${CHANNEL_ID}/invites`,
    {
        method: 'POST',
        headers: {
        'Authorization': `Bot ${BOT_TOKEN}`,
        'Content-Type': 'application/json'
        },
        body: JSON.stringify({
        role_ids: [ROLE_ID]
        })
    }
);

if (!response.ok) {
const error = await response.json().catch(() => ({
    message: `HTTP ${response.status}`
}));
throw new Error(
    `Failed to create invite: ${error.message}${error.code ? ` (code: ${error.code})` : ''}`
);
}

const invite = await response.json();
console.log(`Created invite: https://discord.gg/${invite.code}`);

1. role_ids array: Contains the Discord role IDs to assign when the invite is accepted (we're only assigning one in this example, but you can assign any number of roles using this array)
2. Response: Returns an invite object with a code you can share

In this example, we'll show you how to only allow specific users to accept an invite using the channel invite API. We'll take a look at what a game developer or streamer could do to grant special roles and channels in their community for supporters.

Before you begin, make sure you have:

• A Discord server for testing
• Developer Mode enabled on your account (so you can copy role, channel, and user IDs)
• A Discord app with a bot token (create one in the Developer Portal)
• Node.js installed, or the ability to make HTTP requests from your bot or app
• Bot permissions for:
  • Create Instant Invite (required to create invites)
  • Manage Guild (required for targeted invites with target_users_file)
  • Manage Roles (required for automatic role assignment with role_ids)

If you run a subscription service for your game or community, you can create exclusive invites that only your paying supporters can accept. Those roles can grant access to channels that other users in the server can't see. Here's how to create an invite that grants a role to specific users:

// IMPORTANT: Never hardcode tokens or commit them to version control
// Use environment variables or a secure configuration management system
// Replace the placeholder below with your actual bot token, channel ID, and role ID
const BOT_TOKEN = "REPLACE_WITH_YOUR_BOT_TOKEN_FROM_THE_DEV_PORTAL";
const SUPPORTER_CHANNEL_ID = '1234567890123456789';
const SUPPORTER_ROLE_ID = '1111222233334444555';

// In production you would fetch this from your subscription database
// Replace these example user IDs with actual Discord user IDs of your test accounts
const activeSupporterIds = [
    '111111111111111111',
    '222222222222222222',
    '333333333333333333',
];

// Create CSV content with user IDs
const csvContent = activeSupporterIds.join('\n');
const csvBlob = new Blob([csvContent], { type: 'text/csv' });

// Use FormData for multipart/form-data request
const formData = new FormData();
formData.append('target_users_file', csvBlob, 'supporters.csv');

formData.append('payload_json', JSON.stringify({
    role_ids: [SUPPORTER_ROLE_ID]
}));

const response = await fetch(
`https://discord.com/api/v10/channels/${SUPPORTER_CHANNEL_ID}/invites`,
{
    method: 'POST',
    headers: {
    'Authorization': `Bot ${BOT_TOKEN}`
    },
    body: formData
}
);

if (!response.ok) {
    const error = await response.json().catch(() => ({
        message: `HTTP ${response.status}`
    }));

    let errorMessage = `Failed to create invite: ${error.message || response.statusText}`;

    if (error.code) {
        errorMessage += ` (code: ${error.code})`;
    }

    if (error.errors) {
        errorMessage += '\nDetailed errors:\n' + JSON.stringify(error.errors, null, 2);
    }

    throw new Error(errorMessage);
}

const invite = await response.json();

console.log(`Share this link with supporters: https://discord.gg/${invite.code}`);

1. target_users_file: A CSV file containing Discord user IDs of paying supporters. Only these users can see and accept the invite.
2. role_ids array: Assigns the Supporter role automatically, giving them access to exclusive channels
3. FormData: Required when uploading files, the other parameters go in payload_json

For the best experience, configure your Supporter role with these permissions:

1. Create a Supporter role in your Discord server
2. Create a private channel (#supporter-polls or #supporter-chat)
3. Right click the channels and "Edit Channel" to set the channel permissions so only users with the Supporter role can view and message in it
   • View Channel for the supporter exclusive channels
   • Send Messages and Add Reactions

For complete API reference details, check out the invite and channel API documentation.