Configure a claim process that fits your community.
This guide covers installation, dashboard settings, templates, approvals, dynamics, commands, and the safeguards Claims-bot applies to roles and users.
Getting started
Install Claims-bot, place its role correctly, and choose the text channel where members will submit claims.
- Add Claims-bot to your server. You need permission to manage the server during installation.
- Position the bot role. In Discord’s role list, move Claims-bot above every completion role it should grant or remove.
- Check channel access. The bot needs to view the claims channel, send messages, create and manage public threads, read message history, and add reactions.
- Open the dashboard. Choose a server, select the claims channel, configure at least one completion role, and save.
- Test with two members. Submit a claim, complete the participant requirements, and confirm that the roles and thread behave as expected.
Dashboard settings
Claim location
Choose one text channel and customize thread titles with {claimant}, {claimed}, and {server}. The default title is {claimant} + {claimed}.
Approval
Auto approves as soon as all requirements are complete. Manual waits for authorized staff to approve or decline.
Completion roles
Configure a claimant role, a claimed-partner role, or both. At least one is required before claims can be approved.
Claimant access
Whitelist roles limit who may initiate a claim. Blacklisted roles prevent matching claimants. Both lists are optional.
Required roles
Optional roles that both participants must hold when a claim begins and when it is approved.
Dashboard administrators
Delegate Claims-bot settings and staff actions to selected roles without granting Discord’s Manage Server permission.
User blacklist
Prevent selected users from participating on either side of a claim. Adding a user cancels their open claims and ends their acknowledged dynamics.
Hierarchy
Use Discord’s role order, create a custom highest-to-lowest role order, or disable hierarchy checks.
Deadlines and limits
Set claim completion time in minutes, hours, or days. Dynamics limits default to one on each side; zero means unlimited.
Templates and variables
The initial claim template validates the message posted in the claims channel. Participant templates become guided forms opened from buttons in the claim thread.
| Variable | Behavior |
|---|---|
{claimant} | Filled with the message author. It is optional in the initial template and automatic in participant forms. |
{claimed} | Identifies the claimed partner. It is required exactly once in the initial template. |
{server} | Filled with the Discord server name. |
{text} | Creates a required multiline response field. |
{status} | Creates an Open or Closed choice. |
{approval} | Creates a Yes or No choice. No declines or withdraws the claim. |
{list} | Accepts one item per line and returns a bulleted list. |
{num_list} | Accepts one item per line and returns a numbered list. |
Example initial claim
**Superior Template:**
**Claiming Superior:** {claimant}
**Claimed Participant:** {claimed}
**Brief History:** {text}
**Open or Closed Dynamic:** {status}
**Rules for the inferior:**
> {text}Example claimed-partner template
**Claimed Participant:** {claimed}
**Consent to Dynamic:** {approval}
**Rules for the Superior:**
> {list}
**Pledges:**
> {text}Discord markdown is removed from form labels so prompts stay readable, then reapplied when the completed template is posted. Forms with more than five interactive fields are split into sequential pages and retain progress between pages.
Approval and staff actions
Automatic approval
Claims-bot approves once the configured participant templates or acceptance step are complete, both users still satisfy required roles, and neither user exceeds the server’s dynamics limits. Servers may optionally require the claimant template first; the claimed partner’s template or Accept button remains disabled until the claimant finishes.
An optional claimant cooldown limits how often the same person can open a valid claim. Invalid posts do not start a cooldown, and Discord shows the claimant when they may try again.
Manual approval
When the thread says the claim is ready for staff approval, authorized staff can use /claims approve with the original claim message ID or add the configured approval emoji to that message. Staff can decline with /claims decline or the configured declined emoji.
The approval announcement includes the approving staff member. A staff reaction is not duplicated by the bot.
Dynamics and role safety
Claimant and claimed-partner limits default to one. Setting either limit to zero makes that side unlimited. A member cannot bypass limits by alternating between the claimant and claimed positions; when they participate on both sides, the stricter applicable limit governs their combined active dynamics.
When participant ending is enabled, either participant can use /claims end [partner] or add the configured ended-dynamic emoji to the original claim. The command remains available when channel permissions prevent members from adding reactions.
Claims-bot removes a completion role only when it originally introduced that role and no other active dynamic still needs it. If staff remove a bot-managed completion role, affected dynamics end after a short recheck instead of the bot forcing the role back onto the member.
Staff may end one dynamic by message ID, end every dynamic involving a member, or use the ended-dynamic reaction on the original claim. Deleting the original approved claim also ends its dynamic.
Command reference
Everyone can see /claims, but configuration and staff actions are privately restricted to members with Manage Server or a configured Claims-bot administrator role.
/claims setupConfigure several common settings at once./claims channelSet the claims channel; defaults to the current text channel./claims threadSet or reset the claim thread title./claims templatesConfigure templates and optional claimant-first response ordering./claims completion-rolesSet or clear roles granted after approval./claims approvalChoose auto/manual approval and customize the announcement./claims approve · /claims declineResolve ready manual claims as staff./claims access whitelist|blacklist|showManage claimant access roles./claims users add|remove|showManage users blocked from Claims-bot./claims admins add|remove|showDelegate Claims-bot administration./claims required-roles add|remove|clear|showManage roles required for both participants./claims hierarchy custom|discord|off|showConfigure who may claim whom./claims timeoutSet a completion deadline such as 24h, 3d, or off./claims cooldownLimit how often each claimant can open a valid claim, or turn the limit off./claims dynamics limits|participant-ending|showConfigure active dynamics and participant ending./claims dynamics staff-end|staff-end-allEnd active dynamics as staff./claims end [partner]End one of your own dynamics when enabled./claims reactions · /claims invalidCustomize reactions and invalid-post handling./claims status · /claims helpReview configuration or show Discord usage help.Troubleshooting
The bot cannot grant or remove a role.
Give Claims-bot Manage Roles and move its Discord role above the completion roles. Discord does not allow a bot to manage roles positioned above its own.
A valid-looking claim is rejected.
Compare the message with the initial template, including fixed punctuation and headings. Whitespace may vary, but required text must match and {claimed} must resolve to exactly one partner.
A participant cannot use the ended reaction.
Confirm participant ending is enabled. If Add Reactions is disabled in the claims channel, use /claims end instead.
The dashboard does not list a server.
The bot must be installed in that server, and your Discord account must have Manage Server or one of its configured dashboard administrator roles.
A claim cannot be approved.
Check completion roles, required roles, dynamics limits, hierarchy, participant requirements, and the bot’s role position. The claim thread normally explains the unmet condition.