Set up Moji Tournament Bot

First-time setup

Before you start

Ask these people to help with setup. One person can do both if they have the required access.

• Discord server admin: invites the bot and sets up its roles and announcement channel. You need Manage Server and Manage Roles. The bot never requests Administrator; see bot permissions for what it requests and why.
• CalicoTab tournament admin: gets the tournament URL and API token, then enters them in the bot’s private setup form. The steps below show where to find them.

Required setup

8 required steps. Step 2 is the one-time 250,000 VND activation, and step 8 confirms the server is ready.

1. Invite the bot. The person with Discord access opens Add Moji Tournament Bot to Discord, chooses the tournament server, and completes one Discord authorization.
   • Command access: prepares Bot Manager command permissions. No profile or email access is requested.
   • Standard roles and Command Log: setup creates or reuses CAP, Tab, Equity, Adjudicator, Debater, and OrgComm roles with no extra Discord permissions. It also creates a private, read-only #moji-command-log for Bot Managers. Staff do not need to create either beforehand.
2. Activate the server. The server appears as Pending, so operational commands stay unavailable until payment activation.
   • One-time payment: the browser returns to Moji Tournament Bot for a one-time 250,000 VND payment hosted by PayOS. To return to payment later, open Pay and activate.
   • Automatic activation: a securely verified payment activates an eligible pending server. Wait until the activation page says the server is active before you continue. If confirmation is pending, refresh and do not pay again.
   • Problems: duplicate payments and restricted servers need owner review, and refunds are not automatic. Contact Support; manual approval remains an administrative fallback.
3. Set the role order. In Server Settings → Roles, place Moji Tournament Bot above every role it needs to update.
   See the Discord role order

   

4. Find your API token. Sign in to CalicoTab as an administrator and open Site Home. Select Get API Token / Change Password and copy the token at the top. You do not need to change your password.
   Find Site Home in CalicoTab

   

   See where to copy the API token

   

   

5. Connect the tournament. After payment activation, run /setup bot. Enter your tournament URL and API token in the private form. Use the URL of the specific tournament, not Site Home. If Site Home lists several tournaments, each has its own URL ending in a different slug. Never post the token in chat or a support message. The bot then creates and secures its private Command Log.

   Replacing an existing setup? Changing the tournament clears participant links and scheduled work. Read Change tournament credentials before you run /setup bot again.

   See the private setup form

   

6. Give staff access. Assign trusted tab staff to Tab. Tab and CAP are the default Bot Manager roles for staff commands. The bot assigns CAP automatically to linked Core Adjudicators. To keep or revoke CAP, see staff roles and CAP.
7. Choose the announcement channel. Run /config announcement and select its required channel option. In that channel, allow the bot to view and send messages, embed links and mention everyone. When a draw or motion is released in CalicoTab, the bot posts the corresponding release notice in this channel. The saved channel is confirmed privately.
8. Check you are ready. Run /config status and resolve every Action needed item. Approval, connection, roles, Command Log, announcement channel and Bot Manager commands must be ready. Optional settings can wait.

   If the bot joined this server before it requested its current permissions, a server administrator may first need to grant Manage Channels, Create Instant Invite and Manage Nicknames. Then run /setup bot again. See bot permissions.

   The same reply shows Runtime health for this server.

   See a ready status reply

   

Ready? Continue to participant onboarding.

Optional settings

• Online tournament: run /config meeting and enter your actual HTTPS Zoom or Google Meet URL in the required link option. A configured Bot Manager runs this, and it saves immediately. The link appears in linking confirmation DMs, private /room replies, and participant draw DMs. In draw DMs and updates, the room name and Join Your Debate button both open this link.
• Language: run /config language mode:<vi|en> (default English). See what the language setting covers.
• Institution roles: run /config institution enabled:true to group participants in Discord by their CalicoTab institution.

Role maintenance

/update

Apply recent CalicoTab changes to Discord names and roles, including CalicoTab institution roles and CAP for linked Core Adjudicators.

Before a long break, check automatic cleanup deadlines. Stuck? See Recovery.

Participant onboarding

Participants link in one of two ways. You can use both: email most people, then use Discord for anyone who did not receive or cannot use an invitation.

• Email invitation: Moji emails each participant a personal link. This needs participant emails in CalicoTab and the operator’s email setting.
• Discord onboarding: you post /onboard, and participants connect with their CalicoTab Private URL. Jump to Discord steps.

Send personal email invitations

Before you send, check:

• CalicoTab has each individual participant with a correct email address and team. Purchase confirmations alone are not enough. The API token needs participant-contact permission.
• The bot has Create Instant Invite, Manage Roles and Manage Nicknames. Its role is above the roles it manages (see step 3 above).
• The bot operator has enabled invitation email. You cannot enable it yourself. If /invite replies that email invitations are disabled, contact Support and use Discord onboarding instead.
• The email language is set. Run /config language mode:<vi|en> before you preview. Changing it afterwards needs a new preview, and queued emails keep their original language.

1. Find missing emails: run /invite status. Below the delivery counts, it lists participants (name, role, team) whose CalicoTab email is missing or invalid. Fix them in CalicoTab. Nothing is sent.
2. Review: run /invite send audience:all, or choose debaters or adjudicators in the audience option. Review the private server, recipient count, exclusions and sample email details. No email is sent until you confirm.
3. Send: select Send invitations within five minutes. Each confirmation queues at most 1,000 participants. Repeat the preview for the remaining people. Already invited or linked people are skipped.
4. Send order: emails go out in waves, at about one per second. The first member of every team goes first, then the second member of every team, and so on. Adjudicators go last. Every team is reached before any team gets a second email.
5. Check: run /invite status again and compare the counts with the invitation status table. Counts overlap: a participant who confirmed appears under both SMTP accepted and Claimed.

Moji reads each participant’s roster email, name, role and team from CalicoTab to send the invitation. See the Privacy Policy for retention.

Fix a missing or wrong invitation

Correct the email address in CalicoTab first. Then run /invite resend, type at least two letters in the participant option, select the roster person, and confirm. Sending revokes their previous invitation.

To invalidate a link without removing the member or their account link, run /invite revoke and confirm Revoke invitations.

What participants do

Each seven-day invitation identifies one participant. They sign in with Discord and check the tournament name and their own name, role and team. Then they select Confirm and join server. Shared mailboxes receive separate invitations, and guardians are not CC’d. If Discord membership screening is pending, roles wait until the participant finishes it and confirms again. Point participants to the participant guide.

Help participants through Discord

Use this when email invitations are disabled, or for participants who did not receive or cannot use theirs.

1. Post instructions: run /onboard in the participant channel. It posts immediately and mentions @everyone, with no confirmation. The message includes the participant guide.
2. Let participants connect: they select Connect your account on the onboarding message and paste their complete Private URL into the private form. Or they use /connect with the URL from their email. Never collect these URLs in a public channel.
3. Check coverage: run /link coverage for a private report. Follow up with unlinked participants. Review the confirmation buttons before you repair role mismatches.

Language: the connect button, private form and onboarding text follow /config language. Repost /onboard after you change the language to update its visible text.

Unlinked participants: every time an unlinked participant runs /room or /tab, the bot privately asks them to use /connect with this tournament’s Private URL. This applies to new and returning users, even with closed DMs. Only the caller sees the reply.

Returning participants: people who used /connect before may receive one welcome-back DM when they join an approved, configured server for a new tournament. Rejoining does not repeat it, and old links or roles do not transfer. Join reminders need the Server Members intent, which the bot operator enables. A reminder does not mean someone is linked, so keep the onboarding steps above for everyone.

See the /onboard message

Help a participant link

/link forThen select a member in Discord

Help a member link. Select the required member option in Discord, then submit the command. A private form opens for that person’s complete CalicoTab Private URL. Keep the URL private.

/link removeThen select a member in Discord

Correct a mistaken link. Select the required member option in Discord and check the person before you submit. Removal is immediate, with a private reply and no confirmation. Then use /link for to link the correct identity.

/link status

See whether one member or everyone in the server is linked, without showing anyone’s Private URL.

If participants cannot see /connect, /room, or /tab, open Server Settings → Integrations → Moji Tournament Bot → Commands and allow those commands for @everyone or participant roles. Also check that the channel allows Use Application Commands.

See participant command access settings

Illustrative settings, not interactive controls. Discord’s layout may vary. Discord command-permission help.