Special Roles Documentation

special_roles.md

Special Roles Documentation

This document provides a detailed overview of special roles in the system, outlining their properties and offering guidance on how to classify them based on specific attributes.

---

Booster Role

Overview

Booster roles are managed roles associated with server boosters. They include specific tags to identify their type.

Example

{
  "id": "858948433755111477",
  "name": "Booster Role",
  "managed": true,
  "tags": {
    "guild_connections": false,
    "premium_subscriber": null
  }
}

---

Server Product Role

Overview

Server product roles are managed roles associated with one-time purchases or other non-subscription products.

Example

{
  "id": "1148718581102690394",
  "name": "Server Product Role",
  "managed": true,
  "tags": {
    "guild_connections": false,
    "premium_subscriber": false
  }
}

---

Premium Subscriber Role (General)

Overview

Premium subscriber roles are managed roles linked to a server subscription integration.

Example

Integration Type: guild_subscription

{
  "id": "1067670547611258943",
  "name": "Premium Subscriber Role",
  "managed": true,
  "tags": {
    "guild_connections": false,
    "premium_subscriber": false,
    "integration_id": "1067670547611258941"
  }
}

---

Premium Subscriber Tier Role

Overview

Premium subscriber tier roles are managed roles tied to specific subscription tiers and integrations.

Example

{
  "id": "1067670551717482592",
  "name": "Premium Tier Role",
  "managed": true,
  "tags": {
    "guild_connections": false,
    "integration_id": "1067670547611258941",
    "subscription_listing_id": "1067670551717482588",
    "available_for_purchase": null
  }
}

---

Twitch/YouTube Subscriber Role

Overview

Twitch/YouTube subscriber roles are managed roles linked to either Twitch or YouTube integrations, applicable to all subscriber tiers.

Examples

Twitch Integration

Integration Type: twitch

{
  "id": "1029796404278853684",
  "name": "Twitch Subscriber Role",
  "managed": true,
  "tags": {
    "integration_id": "1029796400961175562"
  }
}

YouTube Integration

Integration Type: youtube

{
  "id": "1029796404278853685",
  "name": "YouTube Subscriber Role",
  "managed": true,
  "tags": {
    "integration_id": "1029796400961175563"
  }
}

---

Role Connection Role

Overview

Role connection roles are managed roles associated with external connections, identified by specific tag attributes.

Example

{
  "id": "1055234125637886022",
  "name": "Role Connection Role",
  "managed": true,
  "tags": {
    "guild_connections": null
  }
}

---

Role Classification Guide

Identifying Special Roles

• Special Role: managed is true.
• Normal Role: managed is false.

Identifying Bot Roles

• Bot Role: tags contain a bot_id field.

Identifying Role Connection Roles

• Role Connection Role: tags include only guild_connections with null.

Identifying Paid Roles

General

• Paid Role: tags include guild_connections as false.

Types

• Booster Role: tags have guild_connections as false and premium_subscriber as null.
• Server Product Role: tags have guild_connections as false and premium_subscriber as false.

Identifying Subscription Roles

General

• Subscription Role: tags include guild_connections and integration_id.

Types

• Base Subscription Role: tags have guild_connections as false, premium_subscriber as false, and an integration_id.
• Subscription Role: tags have guild_connections as false, premium_subscriber absent, subscription_listing_id, and an integration_id.
• Draft Subscription Role: tags meet the criteria for a subscription role, but available_for_purchase is false.

Identifying Twitch/YouTube Roles

• Twitch/YouTube Role: tags contain only an integration_id.