Getting started with Opal

Opal is a hosted Discord bot for staff management and day-to-day staff operations. After adding Opal to a server, configuration is handled through Discord with /setup.

1. Add Opal

Use the official Opal installation link and select the server where you want to use it. The person installing the app needs Discord Manage Server permission.

Opal should have:

• View Channels
• Send Messages
• Embed Links
• Manage Roles

Manage Roles is required for staff-role changes and verification.

2. Place the Opal role correctly

Discord only lets a bot manage roles below its highest role. A typical hierarchy is:

Owner
Opal
Management
Senior Staff
Moderator
Trial Staff
Verified
@everyone

Opal only needs to sit above roles it must assign or remove.

3. Run /setup

/setup requires Discord Manage Server and opens a private configuration panel.

The main sections are:

• Access — staff and management roles
• Features — enable or disable Opal workflows
• Logging — choose audit-log destinations
• General — timezone, terminology, coverage target
• Leave requests — configure the request/review channel and leave log
• Verification — configure and publish the verification panel

4. Configure Access

Staff roles

Select every Discord role that represents a staff position Opal may assign or use for promotions/demotions.

Example:

Trial Moderator
Moderator
Senior Moderator
Support

Management roles

Select roles that should be able to use Opal's management commands. Discord Administrator and Manage Server also grant management access.

/setup itself always requires native Manage Server permission.

5. Choose features

Opal's operational features can be enabled independently:

• Staff directory
• Internal notes
• Staff warnings
• User reviews
• Staff availability
• Coverage scheduling
• Leave requests
• Management analytics
• Verification

Disable workflows your team does not use.

6. Configure logging

Logging categories can be routed independently:

• Staff changes
• Notes & warnings
• Reviews
• Scheduling
• Leave requests
• Bot access
• Configuration
• Verification

Opal needs View Channel, Send Messages, and Embed Links in configured log channels.

7. Configure leave requests

Open /setup → Leave requests.

Choose:

• Primary channel — receives the detailed request card with Accept and Deny buttons.
• Log channel — receives compact request and decision audit messages.

When management presses Accept or Deny, Opal opens a modal and requires a decision reason. The detailed request message is updated with the final decision.

8. Configure verification (optional)

Open /setup → Verification and choose:

• verification channel;
• role to grant;
• panel title/body/button label.

Publish the panel when ready. Members press Verify and Opal assigns the configured role.

9. Add staff

Use:

/staff add member:@Alex role:@Moderator

10. Manage the staff lifecycle

Use:

/staff promote
/staff demote
/staff remove

Promotion/demotion changes the tracked Discord role and staff position together. Removal records the departure date and changes the position to Former-Staff.

11. Reviews

Members can submit one review for each eligible staff member. Reviewers cannot edit or delete their own review. If management deletes the review, that does not open a new submission slot for the same reviewer/staff pair.

Management can permanently remove an inappropriate review with:

/reviews delete member:@Staff review_id:3

If a member abuses reviews or another user-facing Opal feature, use /access ban to restrict their access.

12. Availability and leave

Staff can submit recurring weekly availability and leave requests. Management can:

• view one staff member's availability with /availability staff;
• view coverage with /schedule coverage;
• approve or deny leave directly from the leave-request message.

13. Support

Use /opal-about for Opal's public links, including the official support Discord when configured.

Configuration

All normal configuration is handled through /setup.

Access

Staff roles

Choose the Discord roles Opal may use as staff positions. These roles are used by:

• /staff add
• /staff promote
• /staff demote
• staff recognition for applicable features

Opal validates role hierarchy and assignability when roles are configured and again when role-changing commands run.

If a configured staff role is deleted, Opal removes it from configuration automatically. Historical staff records are preserved.

Management roles

Configured management roles can use management-only Opal commands. Discord Administrator and Manage Server also grant management access.

/setup itself requires Discord Manage Server.

Features

The feature panel controls:

Disabling a feature blocks its workflow without deleting existing records.

Logging

Each audit category can be disabled or routed to a selected channel:

General

Timezone

Used for scheduling and automatic leave-status handling.

Minimum coverage

Sets the target used by /schedule coverage.

Terminology

Changes selected display wording. It does not rename slash commands or alter permissions.

Leave requests

The Leave requests setup panel has two destinations:

Primary channel

Detailed leave requests are posted here with Accept and Deny buttons. Management must provide a reason for either decision.

Log channel

Compact leave-submission and leave-decision events are sent here.

The primary channel is required before staff can submit leave requests.

Verification

Configure:

• channel;
• role;
• title;
• message body;
• button label.

Supported message placeholders:

{server}  Discord server name
{role}    configured verification role
{button}  configured button label

Publishing the panel enables Verification. Opal must have Manage Roles and its role must be above the verification role.

If the configured verification role or channel is deleted, Opal clears the stale configuration and disables Verification until it is configured again.

Permissions

Access levels

Manage Server

Native Discord Manage Server permission. Required for /setup.

Management

A member has Opal Management access when any of these is true:

• Discord Administrator;
• Discord Manage Server;
• they have a role configured under /setup → Access → Management roles.

Tracked staff

A member with a current Opal staff-directory record. Used for staff self-service workflows such as availability and leave requests.

Member

A normal server member. User-facing feature switches and /access restrictions still apply.

Command permission matrix

/access restrictions

Management can restrict user-facing Opal features with /access ban.

Supported scopes:

• all
• user_reviews
• availability
• leave
• verification

Management users cannot be restricted until their management access is removed.

Discord bot permissions

Opal normally needs:

• View Channels
• Send Messages
• Embed Links
• Manage Roles

Manage Roles is needed for staff roles and verification. Opal can only manage roles below its highest Discord role.

Complete command reference

This page documents every public slash command in Opal.

Access labels

• Manage Server — Discord's native Manage Server permission.
• Management — Discord Administrator, Discord Manage Server, or a configured Opal Management role.
• Tracked staff — member with a current Opal staff record.
• Member — normal server member; enabled features and access restrictions still apply.

Core

/setup

Opens the interactive configuration dashboard.

/setup

Use it to configure Access, Features, Logging, General settings, Leave requests, and Verification.

/opal-about

Shows a short explanation of Opal and any configured public links.

/opal-about

Bot access

/access ban

Restricts a member from selected user-facing Opal features.

/access ban member:@User scope:user_reviews reason:"Repeated review abuse"

Bots, the caller, and current Opal managers cannot be restricted.

/access unban

Removes an Opal access restriction.

/access status

Shows one member's active Opal restrictions, who created them, and any recorded reason.

/access list

Shows recent active Opal access restrictions.

/wipe

Permanently removes Opal-held data tied to a selected user after a confirmation modal.

The confirmation modal requires the exact word WIPE and optionally accepts an internal reason.

The wipe removes the user's staff profile and owned staff records, reviews they wrote or received, availability, leave requests, access restrictions, and record counters. Manager/actor references on unrelated records are anonymized where needed.

Discord roles and historical Discord messages are not modified.

Staff directory

/staff add

Adds or re-adds a staff member and assigns a configured staff role.

/staff add member:@Alex role:@Moderator

New staff members start as Active. Approved leave temporarily changes the displayed status to Leave for the approved dates.

/staff remove

Removes the tracked staff role when possible and marks the member as former staff.

The departure date is recorded and the displayed position becomes Former-Staff.

/staff promote

Moves a staff member to a higher configured Staff role.

Role direction is determined by Discord's role hierarchy.

/staff demote

Moves a staff member to a lower configured Staff role.

/staff profile

Opens a navigable staff profile with employment information and links to Notes, Warnings, Reviews, and History when those features are enabled.

The status is reconciled before display so current approved leave is reflected automatically.

/staff list

Lists tracked staff grouped by status.

/staff history

Shows recent staff lifecycle and record-history events.

Internal notes

/notes add

Opens a modal to add a private management note to a staff member.

The created note receives the next note ID for that staff member.

/notes list

Shows recent notes and their IDs.

/notes delete

Permanently deletes a note. Both the staff member and note ID are required.

/notes delete member:@Alex note_id:3

Deleted note IDs are not reused.

Staff warnings

/warnings issue

Opens a modal to issue a warning.

The warning reason is entered in the modal and the warning receives the next warning ID for that staff member.

/warnings list

Shows warnings recorded for one staff member.

/warnings revoke

Revokes an active warning. Both the staff member and warning ID are required. A modal allows management to record a revocation reason.

/warnings revoke member:@Alex warning_id:2

User reviews

/reviews submit

Opens a modal to submit a 1–5 rating and feedback for an eligible staff member.

A reviewer can submit only one review for a particular staff member and cannot edit or delete it themselves. A management deletion removes the review content but does not reopen that reviewer's submission slot.

/reviews staff

Shows the average rating and recent reviews for one staff member.

/reviews mine

Shows reviews submitted by the caller.

/reviews delete

Permanently deletes a review. Both the staff member and review ID are required. The reviewer still cannot submit a replacement review for that staff member.

/reviews delete member:@Alex review_id:4

If a reviewer is abusing the feature, management can combine deletion with /access ban.

Availability and scheduling

/availability add

Adds one recurring weekly availability window.

Overlapping windows are rejected.

/availability clear

Clears the caller's availability for one weekday or the whole week.

/availability mine

Shows the caller's recurring weekly availability.

/availability staff

Shows one staff member's recurring weekly availability.

Former staff cannot be used for this view.

/schedule coverage

Shows availability coverage for a selected weekday against the configured minimum staffing target.

Leave requests

/leave request

Submits a leave request to management.

The primary leave-request channel must be configured in /setup first.

After submission, Opal posts a detailed request card to that channel with Accept and Deny buttons. Management presses a button and must provide a reason before the decision is stored.

Approved leave automatically changes the staff member's status to Leave during the approved dates.

/leave mine

Shows the caller's recent leave requests, IDs, dates, reasons, and current decision status.

Management decisions are handled from the request message itself.

Analytics

/analytics

Shows a compact management snapshot based on enabled features, including staff statuses, warnings, recent notes/reviews, pending leave, and active Opal access restrictions.

Feature guide

Staff directory

Staff records track:

• current role-backed position;
• status;
• join date;
• departure date for former staff;
• notes;
• warnings;
• user reviews;
• staff history.

Staff roles, promotions and demotions

/staff add assigns a configured staff role. /staff promote and /staff demote replace the tracked staff role and update the stored position/history together.

/staff remove removes the tracked role when possible, records the departure date, and sets the position to Former-Staff.

Internal notes

Notes are private management records. Each staff member has their own note numbering:

Alex: Note #1, #2, #3
Jordan: Note #1, #2

This is why destructive commands use both the staff member and note ID:

/notes delete member:@Alex note_id:2

Deleted numbers are not reused.

Staff warnings

Warnings include:

• warning ID;
• severity;
• reason;
• issuer;
• active/revoked state;
• revocation information.

Warning numbering is tied to the staff member, so /warnings revoke requires the staff member and warning ID.

User reviews

Members can submit one 1–5 review for each eligible staff member.

Reviewer rules:

• cannot review themselves;
• cannot review bots;
• can submit only one review for the same staff member;
• cannot edit or delete their own review.

Review IDs are tied to the staff member. Management permanently deletes a review with:

/reviews delete member:@Staff review_id:4

If review access is abused, management can restrict the reviewer with /access ban.

Staff availability

Tracked staff can add recurring weekly windows with /availability add and view their own schedule with /availability mine.

Management can inspect one staff member directly with:

/availability staff member:@Staff

Coverage scheduling

/schedule coverage compares recurring availability against the configured minimum coverage target and highlights under-covered periods.

Leave requests

Staff submit leave with /leave request.

A request is posted to the configured primary leave channel with:

• requester;
• dates;
• reason;
• status;
• Accept and Deny buttons.

Management presses a button and must enter a reason. The request message is then updated with the decision and decision reason. A compact event is also sent to the configured leave log channel.

Approved leave automatically controls the staff member's Leave status during the approved date range.

Management analytics

/analytics gives a compact view of staff statuses, warnings, notes, reviews, pending leave, and active Opal access restrictions according to enabled features.

Verification

Verification publishes a persistent button that grants a configured role. The message can be customized from /setup.

Access restrictions

/access ban can disable all user-facing Opal features for a member or only a selected workflow. This is useful for review spam, leave-request abuse, verification abuse, and similar behavior.

User data wipe

/wipe is a destructive Management-only command that removes Opal-held records tied to a selected user after an explicit WIPE confirmation.

It removes their staff record, reviews, availability, leave requests, access restrictions, and associated record counters, while anonymizing their manager/actor ID on unrelated records that must remain. It does not remove Discord roles or historical messages already posted in channels.

Logging

Logging is configured through /setup → Logging, with an additional leave-specific shortcut under /setup → Leave requests.

Categories

Leave channels

Leave requests use two different channels when configured:

• Primary leave channel — detailed request cards with Accept/Deny controls.
• Leave log channel — compact audit entries for submissions and decisions.

Channel permissions

Opal needs these permissions in configured channels:

• View Channel
• Send Messages
• Embed Links

If a configured log channel is deleted, Opal removes the stale route automatically. If the primary leave channel is deleted, Opal clears that setting and staff cannot submit new leave requests until management selects another channel.

Audit behavior

Audit logging is best-effort. A temporary failure to write an audit message does not roll back an otherwise successful staff-management action.