The Viscra Guide

A complete manual for setting up and mastering Viscra for your community.

1. Base Setup

Getting Viscra into your server is the first step. Ensure you have the correct permissions set up to avoid issues later.

Adding the Bot

Invite Viscra using the official invite link. You need Manage Server permissions to add bots.

White-labelling (Custom Bots)

Pro Feature: White-labelling is exclusive to PRO/Premium servers for resource management.

Viscra allows you to use your own custom bot identity (name, profile picture, banner) while still powered by our engine.

  1. Create a new application at the Discord Developer Portal or use an existing one.
  2. Go to the Bot tab and ensure Server Members Intent and Message Content Intent are both enabled.
  3. Head to the Installation tab. Change the Install Link from "None" to "Discord Provided Link".
  4. Under Default Install Settings, add "Bot" and "applications.commands" to scopes, and set permissions to Administrator.
  5. Copy your Application ID and Bot Token.
  6. In the Viscra Dashboard, navigate to your server settings, go to the Pro page, and enter these credentials.

Please ensure you have enabled intents under the Bot tab on the application page:

  • Server Members Intent
  • Message Content Intent
Tip: If you want to hide the original Viscra commands and only show your custom bot's commands, go to Server Settings > Integrations > Viscra. Set the permissions for "Roles & Members" and "Channels" to false. This will hide them for non-admins.

Recommended Permissions

We recommend giving Viscra Administrator permissions for ease of use. If you prefer granular control, ensure the bot has:

  • Manage Roles (to assign rank/verified roles)
  • Manage Nicknames (to update names to Roblox usernames)
  • Manage Channels (for tickets)
  • View Channels, Send Messages, Embed Links (basic functionality)
  • Moderate Members (for kicks/bans/timeouts)
Note: Viscra's role must be higher in the Discord role hierarchy than the roles it is trying to manage.

2. Verification System

Viscra uses Roblox's official OAuth2 for secure verification. No verification games or code phrases are required.

Setting Up Roles

Use /settings to configure the basic roles:

  • /settings set-verified-role: The role given to users who successfully verify.
  • /settings set-unverified-role: The role given to new members (removed upon verification).

The Verification Panel

Run /verifypanel in your verification channel. This creates a permanent button that users can click to link their account.

3. Rank & Group Binds

Connect your Roblox group ranks to Discord roles. This can be done via commands or the Dashboard.

Quick Setup

Run /setup groupid:YOUR_GROUP_ID. Viscra will fetch your group roles and offer to automatically create corresponding Discord roles and binds for them.

Manual Binds

  • Group Bind: Gives a role to anyone in the group.
    /groupbind add-role groupid:123 roles:@Member
  • Rank Bind: Gives a role to a specific rank ID.
    /rankbind add-role groupid:123 rankid:255 roles:@Owner
  • Rank Bind (ranged): Gives a role to a range of rank IDs.
    /rankbind add-role groupid:123 rankid:20-32 roles:@Officer

Naming Schemes

Optionally, you can enforce nickname formats per rank using the dashboard or /rankbind command. Use {roblox_username} as a placeholder.
Example: [E1] {roblox_username}

Sticky Roles

Sticky roles are roles that Viscra will not remove from a user, even if they no longer meet the requirements for it. This allows roles to be given via binds but not removed. Roles within this list will not be removed by the bot when /update, /updateall, or the verification panel is interacted with.

  • /stickyroles add role: - Add a role to the sticky role list.
  • /stickyroles list - List all currently configured sticky roles.
  • /stickyroles remove role: - Remove a role from the sticky role list.

4. In-Game Systems

Sync your game with Viscra to enable XP tracking, auto-promotions, and more. You will need the Viscra Handler script from our support server.

Installation

  1. Get the ViscraHandler_New script and ViscraConfigs ModuleScript.
  2. Place ViscraHandler_New in ServerScriptService.
  3. Place ViscraConfigs in ServerStorage.
  4. Enable HTTP Requests and Studio Access to API Services in Game Settings.

Configuration (ViscraConfigs)

serverId = "YOUR_SERVER_ID",
APIKey = "YOUR_GAME_API_KEY",
GroupId = 123456, -- Your Group ID
XPEarningTeams = {game.Teams.Red, game.Teams["Blue Team"]}, -- Teams that earn XP
XPSystemEnabled = true, 
statName = "XP", -- The leaderstat to track

API Key Configuration

Important: The legacy BotKey system is being deprecated in favour of a new API key system. You must generate a Game-Bot API key using /apikeys generate and include it in your ViscraConfigs. The legacy BotKey will remain functional until 10th of January 2026.

GameLink Authorisation

For Viscra to rank users on Roblox, you must authorise GameLink. Run /settings set-gamelink-auth and follow the OAuth flow. This replaces the old cookie system. GameLink is also required for the dashboard to view group icons and group rank names.

Extensions & Attributes

  • ProgressionBar: Add a Boolean attribute named ProgressionBar (set to true) to ReplicatedStorage to show a UI bar to players.
  • ProgressionBarTheme: Create a String attribute ProgressionBarTheme on ReplicatedStorage to customise the UI bar's appearance. Themes include: Default, SciFi, SciFi2, Tactical, and Custom (using a modified ViscraXPBar).
  • GamepassGifting: Set a Boolean attribute GamepassGifting on ReplicatedStorage to true to enable gamepass gifting.
  • 2xXP: Set a Boolean attribute 2xXP on a Player object to true to grant double XP.
  • CanEarnXP: Set to false on a Player to pause XP earning (useful for AFK zones).
  • Cmdr Commands: Supports XPAdd & XPRemove. Add the following to your Cmdr Initialize script: 
    game:GetService("ReplicatedStorage"):WaitForChild("ViscraExtensions"):WaitForChild("Assets"):FindFirstChild("CmdrCommands"):Clone().Parent = script.Parent.BuiltInCommands
  • EventSystem: Set EventSystem Boolean attribute on ReplicatedStorage to true to sync in-game players during events and handle private server teleports.
  • Certifications: Set Certifications Boolean attribute on ReplicatedStorage to true to enable certification checking via the in-game extension module.
  • GamepassGifting: Set GamepassGifting Boolean attribute on ReplicatedStorage to true to enable gamepass gift checking via the in-game extension module.

Gamepass Gifting

You can gift players gamepasses directly through Viscra. Setup involves:

  1. Run /gamepass configure universe_id: to setup your game's universeId.
  2. Enable the GamepassGifting extension attribute.
  3. Use the /api/getGiftedGamepasses endpoint to integrate it into your game systems.
  • /gamepass gift user: roblox_username/@Mention pass: [autofilled] - Gift a gamepass.
  • /gamepass view user: roblox_username/@Mention - View gifted gamepasses.
  • /gamepass revoke user: roblox_username/@Mention pass: [autofilled] - Revoke a gifted gamepass.

Manage who can gift using:

  • /settings gamepass-gifter-role view/add/remove

5. XP & Promotions

Once your game is connected, Viscra can track XP and promote users automatically.

Promotion Configuration

In your ViscraConfigs script, define the promotionReqs table:

promotionReqs = {
    [1] = { -- Starting rank, e.g., Cadet
        statReq = 0,     -- XP needed
        groupRoleId = 1 -- Rank ID to promote to
    },
    [2] = { -- Next rank, e.g., Trooper
        statReq = 15,
        groupRoleId = 2
    }
}

These requirements are synced to Viscra whenever a server starts.

Commands

  • /xp: View your own or another user's XP and progress to the next rank.
  • /topxp: View the server leaderboard (top 10). Cached for 5 minutes.
  • /xpchange add/remove/set: (Officer+) Modify a user's XP amount.

Manage officer roles using: /settings officer-role view/add/remove

6. LOA & EP/Quotas

The Quota/Event Point (EP) system is designed for activity tracking within divisions or units.

Setup

Run /ep setup to start the interactive configuration wizard. You can define units (Main, Sub1, Sub2, Sub3), quotas, and warning actions (Warn, Demote, or Exile/Kick).

LOA

Members can request Leave of Absence (LOA). Users on LOA are not counted during the weekly EP check.

  • /loa add/end/viewall: Manage individual or server-wide LOA status.
  • /loa set-role: Set the role assigned to users on LOA.

How it works

Viscra tracks EP earned via /ep add. Every week (Sunday 00:00 UTC), the bot checks if users met their unit's quota. If they fail, the configured warning action is applied automatically.

7. Medals & Warnings

Medals

Award custom medals to your members to recognise achievements.

  • /medal view/list/create/award/edit: Full medal management.
  • /whois: View a user's medals and other community info.

Medals can be displayed in-game via our integration for DarthKarim's mouse rank system or your own custom implementation.

Warnings

A robust warning system logged to your database.

  • /warn view/add/remove: Manage user warnings with reason logging and IDs.

Manage moderator roles using: /settings server-moderator-role view/add/remove

8. Certifications

Create and manage professional certifications for your server members. Perfect for trainings, qualifications, and skill verification.

Key Features

  • Reference Codes: Short 1-4 character codes (e.g., AFO, FTO, K9).
  • Full Management: Create, edit, award, revoke, and list certifications.
  • Bulk Operations: Award or revoke to multiple users at once.
  • API Integration: Full API support for Roblox games.

Common Commands

  • /certification create reference:AFO name:"..." description:"..."
  • /certification award users:@user1 reference:AFO
  • /certification revoke users:@user1 reference:AFO
  • /certification view user:@user

9. Tickets

Viscra provides an expansive ticket system with support for categories, custom naming schemes, and dedicated staff roles.
The ticket system also supports modmail, this allows users to DM the bot, select the server, and then opens a thread for staff in the server where all messages from the user & staff are forwarded between each.

Core Commands

  • /tickets create/delete/manage: Control ticket panels and content.
  • /add [user]: Add a user to an active ticket.
  • /close [reason]: Close the current ticket with a mandated reason prompt for staff.
  • /tickets modmail setup [channel] [enables]: Set up the modmail system.

Ticket Categories

Categories allow you to route tickets to specific departments with their own support roles, categories, and permissions.

  • /tickets category add/edit/list/remove

Naming Schemes

Customise how ticket channels are named (e.g., ticket-[username], support-[number], appeals-[username]) via /tickets settings naming scheme.

Settings & Staff

  • /settings server-moderator-role: Manage who can access and manage tickets.
  • /settings set-transcript-channel: Set the channel for ticket logs (clean transcripts excluding bot messages).

10. Server Announcements

Send important announcements directly to your members via DM. This is a Pro server exclusive feature with staff approval and member opt-in requirements.

Requirements

  • Pro Subscription is required.
  • Owner Only: Only the server owner can initiate /serverannounce.
  • Member Opt-In: Members must opt-in via /announcement-opt-in enabled:true to receive messages.
  • Approval Process: All messages are reviewed by Viscra staff for quality and safety.
  • 6-Hour Cooldown prevents spam.

11. Server Utilities

Powerful server management tools to streamline community operations.

Applications System

Create custom application forms with automatic group acceptance and rank assignment.

  • /applications manage/create/panel: Manage forms, questions, and panels.
  • Supports up to 7 active applications (14 for Pro) and 15 questions per form (30 for Pro).

Group Logs

Track Roblox group changes (promotions, demotions, leaves) in semi-real-time (60s scans).

  • /grouplogs add/view/delete: Track primary and sub-groups.
  • /grouplogs antiabuse: Configure thresholds to prevent "nuking".
  • /grouplogs rollback: (PRO) Restore group snapshots from the last 2 days.
  • /grouplogs sethicomrole/settoken: Set ping roles and required audit log permissions.

Command Groups

Disable specific features like Verification or Economy via /commandgroups list.

Server Backups

Create complete backups of roles, channels, and permissions.

  • /backupserver and /backuprestore (Owner only).
  • Restoration is destructive and removes all current configuration before applying the backup.

12. Chat Levelling System

The Viscra Levelling System is a comprehensive Discord engagement tracking system that rewards users for their activity through XP (chat or voice points, not to be confused with the XP from Roblox or the EP system) and levels. Users can earn XP through chat messages and voice channel participation, with customisable rewards and configurations.

Features

  • Chat XP: Earn XP by sending messages in text channels
  • Voice XP: Earn XP by participating in voice channels
  • Level Progression: Automatic level calculation based on total XP
  • Level-Up Announcements: Customisable notifications when users level up
  • Role Rewards: Automatically assign roles when users reach specific level milestones
  • Leaderboards: Track top users by XP
  • XP Decay: Optional XP reduction for inactive users
  • Channel Blacklisting: Exclude specific channels from XP earning
  • XP Multipliers: Boost XP gain server-wide

XP Earning

Chat XP:

  • Base XP: 1 XP per message
  • Bonus XP: 2 XP for messages with 50+ characters
  • Minimum Length: Messages must be at least 5 characters
  • Cooldown: 30 seconds between XP-earning messages (default)

Voice XP:

  • Base XP: 2.5 XP per interval
  • Interval: Every 2.5 minutes in voice channel
  • Requirements: User must not be muted or deafened (server or self)

Level Calculation

Levels are calculated using an exponential formula: XP Required = floor(50 × Level^1.5)

Base Level Requirements:

  • Level 1: 50 XP
  • Level 2: 141 XP
  • Level 5: 559 XP
  • Level 10: 1,581 XP
  • Level 25: 6,250 XP
  • Level 50: 17,677 XP
  • Level 100: 50,000 XP

Level Milestones

The system defines milestone levels for role rewards: 5, 10, 15, 25, 50, 75, 125, 175, 300, and 500.

Commands

All levelling commands require Administrator permissions in the server.

/levelling config

  • /levelling config toggle enabled:[true/false] - Enable or disable the levelling system
  • /levelling config set-channel channel:#channel - Set a dedicated channel for level-up announcements
  • /levelling config remove-channel - Remove the dedicated level-up channel
  • /levelling config set-multiplier multiplier:2.0 - Set an XP multiplier (0.1 to 10.0) for the entire server
  • /levelling config blacklist-channel channel:#channel action:[Add/Remove] - Add or remove channels from the XP blacklist
  • /levelling config decay enabled:[true/false] days:[7-365] percentage:[1-50] - Configure XP decay for inactive users
  • /levelling config view - View the current levelling configuration

/levelling roles

  • /levelling roles set level:[milestone] role:@role - Assign a role reward for a specific level milestone
  • /levelling roles remove level:[milestone] - Remove a role reward
  • /levelling roles create-all - Automatically create and assign roles for all level milestones
  • /levelling roles view - View all configured level roles

/levelling reset-user

  • /levelling reset-user user:@user - Reset a user's levelling data completely (irreversible)

XP Decay System

The decay system runs automatically every 24 hours and reduces XP for inactive users:

  • Only affects users inactive for the specified number of days
  • Reduces total XP by the specified percentage (1-50%)
  • Recalculates user level after decay
  • Default: 5% decay after 30 days of inactivity

Level Roles

By default, role stacking is enabled, meaning users keep all roles from lower milestones. For example, a Level 50 user would have roles for Level 5, 10, 15, 25, and 50.

The /levelling roles create-all command automatically creates 10 roles with unique colours and proper hierarchy:

  • Creates roles named "Level 5", "Level 10", etc.
  • Assigns vibrant, distinct colours to each role
  • Sets roles as hoisted (displayed separately in member list)
  • Creates roles in reverse order for proper hierarchy

Use Cases

Setting Up a New Server:

  1. Enable the system: /levelling config toggle enabled:true
  2. Create level roles: /levelling roles create-all
  3. Set announcement channel: /levelling config set-channel channel:#level-ups
  4. Blacklist bot channels: /levelling config blacklist-channel channel:#bot-commands action:Add

Running a Double XP Event:

  1. Set multiplier: /levelling config set-multiplier multiplier:2.0
  2. Announce to your community
  3. After event: /levelling config set-multiplier multiplier:1.0

Preventing XP Farming:

  • Blacklist spam channels
  • Enable XP decay for long-term inactive users
  • Keep default cooldown (30 seconds)
  • Monitor for suspicious activity

Configuration Options

Default configuration values:

  • enabled: true
  • chatXP: 1
  • chatXPBonus: 2 (for 50+ character messages)
  • voiceXP: 2.5
  • chatCooldown: 30000ms (30 seconds)
  • multiplier: 1.0
  • stackRoles: true
  • decayEnabled: false
  • decayDays: 30
  • decayPercentage: 0.05 (5%)

Troubleshooting

Users Not Earning XP:

  • Check if the system is enabled
  • Verify the channel is not blacklisted
  • Ensure messages are at least 5 characters
  • Check if the user is on cooldown (30 seconds default)

Roles Not Being Assigned:

  • Verify the role exists in the server
  • Ensure the bot's role is higher than the level roles
  • Check the bot has "Manage Roles" permission
  • Verify level roles are configured properly

Level-Up Announcements Not Appearing:

  • Check if a level-up channel is set
  • Verify the bot has permission to send messages in that channel
  • Confirm the user actually levelled up

12. Public API

Developers can use Viscra's public API to integrate server data into external tools or websites.

Getting Started

Generate a public API key using /apikeys generate. Include this key in your requests as an Authorization header.

Full Documentation

For a complete reference of all available endpoints, including XP, Group, and Certification management, visit our Dedicated API Guide.