Help Guide
Getting Started
This guide is split into a few shorter sections so you can find what you need quickly during setup and on event day.
Start Here
Basic Setup Flow
Create an organization
Your organization is the main container for your events, admins, promos, queue settings, and retention rules.
Add the admins you will need
Add door staff and trusted helpers to the organization before event day. Do not wait until the line has already formed.
Create the event
Fill in the event details, capacity, queue type, time zone, invite message, and how many extra guests each attendee may bring.
Post the Telegram event message
Open the event, go to Settings, and copy the Telegram posting command. Send that command in the correct room so users can press Check or Join.
Open the event page on site
Once the event is running, have your on-site admins open that event in the browser and begin scanning people in as they are invited and arrive at the door.
Day Of Event
Checklist
- Make sure every admin who may need access has already been added to the organization and tested their login.
- Open the event page on the phones you plan to use and confirm the event appears correctly before the room opens.
- Check the room capacity, queue type, extra guest limit, and end-time offset before people start arriving.
- Make sure the Telegram event post is in the correct room and the bot is present where people will join.
- Take at least one real QR scan test before the door gets busy.
Working Live
The Event Page
Header color and sync badge
The top bar changes color to show connection health. Green means the event page is syncing well, yellow means there have been recent failures, and red means staff should assume the connection is struggling. The badge also shows how many actions are still waiting to sync.
Built for poor internet
The event tools are designed to keep working when service is weak. Changes are queued on the phone and retried when the connection comes back, so avoid reloading unless you really need to.
Tabs
Use Scan for admits, Headcount for manual counts, Stats for a quick room summary, and Settings for operational changes, Telegram posting info, and bulk commands.
Useful Tip
Handling an Emergency
- If something needs immediate attention, use Lock queue in the event bulk commands.
- While locked, new users cannot join, waiting users cannot be invited, and invited users cannot finish accepting.
- You can send a message to people who are already on their way so they know there is a delay or issue.
- After the situation is under control, unlock the queue and normal processing can continue.
Dangerous Settings
Before You Change Core Event Details
Dangerous settings let the event creator or system admin edit the original event definition. They are powerful, but they do not rewind messages that were already sent.
- Changing the event details later may not update Telegram messages people already received.
- If invites or QR codes were already sent, users may still be looking at the older information in chat.
- Use these settings carefully once the event is live, and prefer messaging attendees if something important changed.
On-Site Help
Jump To A Situation
On-Site Help
I posted the wrong event message
If the room post itself is wrong, you need to update the event and then post a fresh room message.
- Open the event and go to Settings.
- Scroll to Dangerous Settings and fix the event details that were wrong.
- Make sure the event status is still scheduled or running.
- Save the dangerous settings.
- On the same page, go to Telegram posting command and copy the room command.
- In Telegram, delete the old room message and send the copied command so the bot posts a new one.
On-Site Help
My invite message sent people to the wrong room
Freeze new invites first, warn the people already on the way, then fix the invite text.
- Open the event and go to Settings.
- In Bulk commands, press Lock queue.
- Write a bulk message warning attendees that the room was wrong and tell them where to go instead.
- Press Message all on the way.
- Scroll to Dangerous Settings, update the invite message, and save.
- Go back to Bulk commands and press Unlock queue when the fix is ready.
On-Site Help
An emergency happened and people must stop coming now
- Open the event and go to Settings.
- In Bulk commands, press Lock queue.
- Write a clear emergency message such as: Emergency issue. Do not come, do not knock, return to another area. More info will follow in the main chat.
- Press Message all on the way.
- If the issue resolves, send another update and unlock the queue when you are ready.
On-Site Help
My room is not filling up and I do not understand why
- Open the event post in Telegram and press Check.
- Look at On-site connection health. If it says offline, at least one on-site admin needs to keep the event page open and ready to scan users.
- If connection health is not offline, check whether the Headcount tab is flashing on the event page.
- Headcounts should be updated at least every 30 minutes. If the estimate is stale, the system may hold back invites.
- Open Stats and look at how many people the system thinks are on site, in queue, invited, and on the way.
- If many people are invited or on the way, the system assumes they may still arrive and may bring the full number of allowed guests.
- If needed, lower the allowed +1s or raise the room capacity in Settings.
On-Site Help
I need to end early or I do not want to unlock the queue again
- Open Settings and use Bulk commands to lock the queue if it is not already locked.
- Write a message for people who are already on the way and press Message all on the way.
- Write a message for people still waiting and press Message all waiting in queue.
- Press Cancel all waiting in queue.
- Press Cancel all on the way.
- You can leave the queue locked until it naturally expires, or change the end time in Dangerous Settings if you want the event to close right away.
- If needed, delete the event post in Telegram too.
On-Site Help
I want to run later than I originally planned
- Before the event ends, open the event Settings.
- Increase the End time offset by the number of extra minutes you want.
- Save the settings.
- Post your own follow-up message in Telegram, because the event card people already saw will not update itself.
On-Site Help
My events start slowly because the queue opens when the event starts
- You can invite people outside this system before the event starts if you want, but update the headcount before doors open.
- By default, users can only join when the event starts. Set a Pre-queue time if you want people to be able to join earlier.
- If your events are very large, consider a separate smaller pre-party event to create a stronger start.
On-Site Help
QR codes will not scan on my phone or I do not have a camera
- The code text shown underneath the attendee QR code can be typed in manually.
- If you have a computer and a USB barcode reader that supports QR codes, it should work too.
- If possible, set the scanner to send an Enter key after each scan.
On-Site Help
I need to admit VIPs without QR codes or a queue
- Open the event and go to the Scan tab.
- Use the Manual admit button at the bottom of the page.
- Record the guest count the same way you would for a normal admit.
On-Site Help
The internet is barely working
- If possible, tether to a hotspot from someone nearby who still has service.
- If nobody has internet, Telegram will also be affected, and this system depends on Telegram to communicate with attendees.
- Close other apps, including Telegram if needed, and use a normal phone browser if that works better than an in-app browser.
- Turn on low-data mode if your device supports it.
- Check the event status and last successful update. If the server has been reached within the last 5 to 10 minutes, you may still be usable.
On-Site Help
I need to ban someone who is drunk or causing problems
- If you know their Telegram identity, use /sqban @username or /sqban <telegram user id> in an associated Telegram room.
- If you can get access to their QR code for a moment, use Ban by scan from the event Scan tab.
- After that, direct them to staff as needed.
On-Site Help
I just need a break from the door
- Open the event Settings and use Bulk commands to press Lock queue.
- Go to Stats and check how many users are on their way.
- If needed, send them a bulk message letting them know to come now, wait a bit, or arrive at a specific time.
- Remember that people already on the way may still arrive while the queue is locked.
- Unlock the queue when you are ready to resume normal flow.
Selection Rules
Queue Types
FIFO
First in, first out. Users are invited in the same order they joined.
Random
Everyone currently waiting has the same chance each time the system selects a new person.
weightedNew
This mode gives better odds to people who have not already attended events in the same organization. It is useful when you want to favor newer attendees.
weightedOld
This mode gives better odds to people who have attended before. The more prior attended events they have in the organization, the more this can help them.
weightedChatty
This mode gives better odds to people with more chatty points in associated rooms. It is meant for communities that want room participation to matter.
weightedManual
This mode looks only at manually awarded and promo-based bonus points. It ignores attendance-history boosts and chatty boosts, so staff-controlled points decide the extra odds.
Weighted modes still use randomness
A weighted queue does not become first-come-first-served. It still picks randomly, but users with more relevant weight get better chances each time the system chooses someone.
Multiplier
What The Weight Multiplier Does
- The multiplier only matters for weighted queue types.
- Each user starts with a base weight of 1000.
- The base 1000 does not get multiplied. Extra points on top of that can be multiplied.
- A higher multiplier makes bonus and history-based advantages matter more.
- If you use a non-weighted queue, the multiplier is hidden because it has no effect.
Capacity
Headcount And Room Control
- The estimated headcount goes up when people are admitted, but it does not go back down when people leave.
- That is why manual headcounts matter. A fresh human count resets the estimate back to reality.
- The system uses the current room capacity plus the estimated headcount to decide whether there is room to invite more people.
- This behavior is intentionally conservative so you are less likely to overfill the room.
Queue Timing
Open, Running, And Close Times
- Queue open is when people are allowed to join. It can start before the event using the pre-queue setting.
- Event open is the event start time.
- Event close is the event end time plus any end-time offset you set.
- If the queue is locked, users cannot join and the queue will not move forward even if time and capacity would normally allow it.
Chatty Points
How Chat Activity Can Affect The Queue
Chatty points only matter if you turn them on for the organization and choose a queue type that uses them.
- A room starts contributing once it is associated with the organization or one of its events and the bot is present there.
- Text messages count when they are at least 10 characters long. Images and videos can count too.
- The system stores weekly point totals instead of keeping a message-by-message history in the database.
- Chatty activity is one possible source of bonus weight, not a guarantee that someone will be invited first.
Admin Commands
What Organization Admins Can Do In Telegram
/sendMessage <event key>
Send this in the room where you want people to join. It posts the event card with Check and Join buttons, and it also links that chat to the event.
/award <points> <reason>
Reply to a user's message in an associated room to give them bonus points. This is good for one-off recognition, such as helping with setup or donating supplies.
/sqban <@username or user id>
Use this in an associated room to ban someone from the organization. Their active queue entries for that organization will be closed so staff can handle the situation.
/orglink <org id>
Use this in a Telegram room to create or refresh a direct organization link for chatty tracking. This is helpful if an older link expired and the bot asked an admin to reconnect the room.
Important Rule
Where These Commands Work
- Admin commands are meant to be used by organization admins, owners, or the system admin.
- Most of them are for Telegram groups, not private chat.
- The bot must be in the room for room-based commands and associations to work.
- If a room is not linked to the organization or event yet, use the event posting command or /orglink to create that connection.
Attendee Flow
What Users Will Experience
- A user can tap Check first to see the estimated number of people on site, how many are waiting in queue, and how many are already on the way.
- A user sees the event post in Telegram and taps Join.
- The bot shows a summary of the event and asks whether they want to continue.
- At that step they can choose Yes, No, or Promo.
- If they choose Promo, the bot asks for a promo code before they finish joining.
- Once they join, they wait in queue until the system is ready to move them forward.
- When invited, they must confirm in Telegram. After they accept, they receive a QR code and can come to the event.
- If plans change after they have a QR code, they can send cancel in private chat and confirm that they want to give up the spot.
Promo Entry
When Promo Codes Can Be Used
- Promo codes are entered during the join confirmation flow, before the user fully joins the queue.
- A valid code can come from the organization or from a specific event.
- The same user cannot apply the same promo code more than once.
- If a code is expired, inactive, or already used by that person, it will not be applied.
Associations
How Telegram Rooms Become Linked
- Posting an event with /sendMessage links that room to the event.
- Using /orglink links the room directly to the organization.
- If a room is linked to an event, chatty activity in that room still rolls up to the organization behind the event.
- These links matter for chatty points, admin room commands, and knowing which organization a room belongs to.
If A Link Expires
What The Bot Will Say
- If chatty tracking is on and the last link between a room and an organization is about to disappear because of retention cleanup, the bot warns the room.
- That warning tells an organization admin to reconnect the room with /orglink <org id>.
- This keeps chatty tracking from silently stopping in a room that staff still expect to count.
Quick Tip
Using Telegram Smoothly On Event Day
- Use Telegram for queue posting, attendee communication, points, and room-level moderation.
- Use the web event page for scanning, headcounts, capacity changes, and bulk event operations.
- If staff are busy, keep at least one admin watching the Telegram room so invite problems, promo questions, and attendee questions do not get missed.
Points Basics
Base Weight And Bonus Weight
- Every user starts with a base weight of 1000.
- That base is always there in weighted modes, even if the user has never earned any bonus points.
- Bonus points sit on top of the base value and can come from promos, admin awards, attendance history, or chat activity depending on the queue type.
- If you are not using a weighted queue type, those point totals do not affect selection.
Decay
How Points Fade Over Time
- Organizations can choose how quickly bonus points expire in value.
- The system uses a gradual linear decay, so points slowly lose strength over time instead of disappearing all at once.
- If decay is set to Never, earned bonus points keep their full value until their retention period removes the stored record.
- This helps older boosts fade naturally so the queue does not stay permanently tilted forever.
Promos
Promo Codes And Common Uses
- Promo codes let you give a defined point boost to a group of people without manually editing each user.
- A promo can be helpful for things like convention staff, trusted volunteers, or other groups who need better odds when the room is likely to fill.
- Promos can belong to the whole organization or to a specific event.
- Each user can only apply the same promo once.
Manual Awards
Using /award
- Admins can reply to a user in an associated Telegram room with /award <points> <reason>.
- This is useful for rewarding an individual for helping at the door, donating supplies, cleaning up, or handling other support work.
- These awards follow the same retention and decay rules as other stored bonus-point records.
- Because the award includes a reason, it is easier to understand later why the points were granted.
Practical Advice
When To Use Points
- Use points when you want to improve someone's odds, not guarantee entry.
- Use promos for groups and use /award for one-off recognition.
- If you need a guaranteed operational result right now, use event tools like locking the queue, messaging attendees, or bulk accepting instead of trying to solve it with points.
Technical Notice
Technical Privacy and Data Storage Notice
This notice covers the main categories of data stored in the Stable Queue database, where that data comes from, how the system uses it, and when it is deleted.
The website user account section below applies only to people who sign in to the Stable Queue admin website. Attendees who only interact through Telegram queue flows do not get a normal website user account row unless they also log in to the website.
On-site admin devices may also keep temporary browser local-storage data such as cached event state, queued offline actions, and recent scans. That device-local cache is not part of the main database and can be cleared from the event settings screen.
Stored Category
Website user accounts
- Telegram numeric user id
- Telegram username and display name when provided
- System-admin flag
- Created, updated, and website-user retention timestamps
Taken from the Telegram website login payload when a person signs in to the web admin panel.
Used to create and update admin website accounts, identify organization owners and admins, and connect a Telegram identity to web permissions. This table is not the main attendee queue table.
A website user is scheduled for deletion 24 hours after creation unless that person is a system admin, an organization owner, or an active organization admin. If a person later loses their last owner/admin role, the row is scheduled for deletion 24 hours after that role change. Before deletion, username and display name are overwritten.
Stored Category
Organizations
- Organization name and slug
- Owner user ids and owner display name at creation time
- Retention, chatty-weighting, and point-decay settings
- Created and updated timestamps
Entered by an authenticated user when creating an organization in the web interface.
Used to group events, admins, promos, bans, chat links, and queue settings under one organization.
Organization rows are deleted when an owner or system admin deletes the organization. They are not currently age-deleted automatically.
Stored Category
Admin assignments and invites
- Organization id and inviter user id
- Invite target name if entered
- Bound admin user ids and Telegram external ids when an invite is accepted
- Invite secret, secret expiry, status, and timestamps
Created when an owner or system admin creates an admin invite and updated when the recipient logs in and binds the invite.
Used to grant, track, and revoke delegated access to an organization.
These rows are deleted when the organization is deleted. They are not currently removed by age-based retention.
Stored Category
Events
- Event name, description, invite message, and queue-join text
- Start time, end time, time zone, status, queue type, and retention setting
- Capacity settings, queue lock state, offsets, multiplier, and guest limit
- Operational counters such as estimated headcount, human headcount, heartbeat, and timestamps
Created from the web admin panel by an authorized user and updated later through event settings, headcount updates, and operational actions.
Used to run the queue, decide when joins and invites are allowed, calculate capacity, and drive on-site operations.
Automatically deleted after the event's retention window expires, or immediately if the parent organization is deleted. Before deletion, key free-text fields are overwritten with same-length replacement data.
Stored Category
Chat associations
- Telegram chat id
- Association type of organization or event
- Linked organization and event ids
- Created timestamp and retention-expiry timestamp
Created when an admin posts an event message with /sendMessage or links a room with /orglink.
Used to know which Telegram rooms belong to which event or organization, to support chatty points, and to authorize room-scoped bot admin commands.
Automatically deleted when the association retention timestamp expires, or immediately if the parent organization is deleted.
Stored Category
Queue entries and admissions
- Telegram user id when known
- Event id, organization id, join time, current state, and state-change timestamps
- QR secret code, invite timing fields, promo code used, and guest count admitted
- Manual-admit flag and optional manual label
Created when a user joins from Telegram or when staff perform a manual admit, and updated by bot invites, RSVPs, and door scans.
Used to run the queue state machine, issue and validate QR codes, track who is expected, and keep headcount estimates conservative.
Deleted when the parent event reaches its retention expiry or when the organization is deleted. Before deletion, manual labels and secret codes are overwritten.
Stored Category
Promo codes
- Promo code text and success message
- Point amount
- Organization or event scope
- Creator information, expiry time, and retention-expiry time
Created or edited by authorized admins in the web interface.
Used to grant reusable bonus-point boosts during the Telegram join flow.
Automatically deleted when promo retention expires, or immediately when the parent organization is deleted. Before deletion, the code and success message are overwritten.
Stored Category
Bonus-point awards
- Target user id and point amount
- Reason text
- Creator type and creator id
- Organization or event scope, optional promo id, created timestamp, and retention-expiry time
Created either by admin actions such as /award or automatically when a valid promo code is applied.
Used for weighted queue selection and for user point summaries in the admin interface.
Automatically deleted when the award retention timestamp expires, or immediately when the organization is deleted. Before deletion, the reason field is overwritten.
Stored Category
Chatty-point summaries
- Organization id
- Telegram user id
- Weekly points total
- Created timestamp and retention-expiry time
Built from Telegram activity in associated rooms only when chatty tracking is enabled. Message activity is first accumulated in memory and later written as weekly summary rows.
Used for weightedChatty queue selection and point summaries without storing a full permanent message log in the main database.
Automatically deleted when the summary retention timestamp expires, or immediately when the organization is deleted.
Stored Category
Bans
- Target user id and user type
- Creator user id
- Organization scope and optional event scope
- Ban time, optional unban time, and optional notes
Created from moderation actions such as ban-by-scan or /sqban.
Used to block users from joining or remaining active in an organization's queue.
Ban rows are deleted when the organization is deleted. They are not currently removed by age-based retention. Notes are overwritten during organization deletion before the row is removed.
Stored Category
Client action receipts
- Client-generated idempotency key
- Action type and event id
- Created timestamp and retention-expiry time
- Stored API response code and response body
Written by the web admin client when it submits event actions such as scans, headcount changes, and invite confirmations.
Used to safely deduplicate retried actions when the connection is weak or a client resends the same request.
Automatically deleted when the parent event reaches retention expiry or when the organization is deleted. Before deletion, the idempotency key is overwritten and the stored response body is cleared.
Stored Category
Bulk event command queue
- Requested-by user id, event id, and organization id
- Action type and optional message text
- Client-generated action key
- Status, timestamps, processed count, and result message
Created when an admin uses event bulk commands in the web interface.
Used to queue bot-side mass actions such as messaging or cancelling groups of attendees and to track whether those jobs completed.
Automatically deleted when the parent event reaches retention expiry or when the organization is deleted. Before deletion, the action key, message text, and result message are overwritten.
Deletion Process
How deletion is performed
- A separate retention worker runs daily and looks for rows whose retention_expires timestamp has passed.
- For tables with free text, secrets, codes, or stored API responses, the worker overwrites those fields with same-length replacement data or clears the stored JSON before deleting the row.
- The overwrite step is committed first. The delete step is committed separately after that.
- When an owner deletes an organization, the system performs the same overwrite-then-delete pattern immediately for the related series-linked data.
- After rows are deleted by the daily worker, the system attempts PURGE BINARY LOGS BEFORE NOW() on the database server.
- Some tables are intentionally not removed by the automatic age-based worker today, including organizations, admin invite rows, and bans. Those remain until an operator deletes the related organization or manually removes the rows.