Invites (/invite_resident, /invite_guard, /invite_admin)

Invites

Invite links are the only way to assign a role to a new user. Each link is single-use and valid for 24 hours. Since TG-009, role assignment requires a two-step confirmation.

Invite Flow (Two-Step)

sequenceDiagram
  participant Admin
  participant Bot
  participant User as New User
  Admin->>Bot: /invite_resident
  Bot->>Admin: Link t.me/bot?start=inv_abc123
  Admin->>User: Forwards the link
  User->>Bot: /start inv_abc123
  Bot->>User: Request sent, awaiting confirmation
  Bot->>Admin: User wants resident role. Confirm?
  Admin->>Bot: Confirm
  Bot->>Admin: Invite confirmed. Role granted.
  Bot->>User: Your request was confirmed. Welcome!

Creating a Resident Invite

/invite_resident

Bot response:

Invite link for resident:
https://t.me/terma_bot?start=inv_abc123456789
Valid for 24 hours.

Copy the link and send it to the future resident.

Creating a Guard Invite

/invite_guard

Same as /invite_resident but grants the guard role.

Creating an Admin Invite

/invite_admin

Super-admin only. Regular admins will receive: You don't have access to this command.

What Happens When a User Follows the Link

1. The user clicks the link or sends /start inv_<code> to the bot.
2. The bot validates the token and sets the invite to pending status.
3. The user receives: “Request sent, awaiting confirmation from the invite creator.”
4. You (the invite creator) receive a confirmation request:

   @username wants the resident role. Confirm?
   [✅ Confirm] [❌ Reject]

How to Confirm or Reject

Press one of the inline buttons in the received message:

• ✅ Confirm — role is granted, user is notified.
• ❌ Reject — role is not granted, user is notified of the rejection.

What the Invited User Sees

Result	User Message
Confirmed	✅ Your request for the resident role was confirmed. Welcome!
Rejected	❌ Your role request was rejected by the invite creator.

Possible Errors When Following the Link

Error	Cause
Link is invalid or already used	Token expired or already in use
You already have the resident role	User already has this role
Cannot use your own link	Admin trying to activate their own invite

View Active Invites

Use /requests to see all active (unused) invitations.

Important Limitations

• A link cannot be used twice. Once followed, it enters pending status.
• If the 24-hour expiry passes before confirmation, the confirmation attempt will fail.
• The bot must be able to send you a message — make sure you have previously started a conversation with the bot via /start.