Queue System
A fully-featured, comprehensive queue system, designed to power community streams.
For easy-to-read setup instructions, click here.
URL
https://api.thefyrewire.com/twitch/queue/:action/:token/:user
Required Parameters
Name | Type | Description |
---|---|---|
action | string | A valid queue action. Supported actions include generate , join , leave , position , info , list and queue . |
token | string | A 16 character string. This must be kept secret. It is strongly recommended to use the generate endpoint to create this. |
user | string | The name of the user. In the case of the list action, this becomes the name of the channel. For the queue action, this parameter becomes option (see below). |
option | string | If action is set to queue , a valid queue management option is required: open , close , clear , add , delete , rename , set , next , stash , remove , purge , superpurge , promote , demote or id |
Optional Query String Parameters
Name | Type | Description |
---|---|---|
query | string | A context-dependent query to make to the queue action. Should be URL-encoded. |
priority | boolean | Can be specified as true for the join action, which will give the user priority placement in the queue. Default: false. |
msglimit | integer | The maximum number of characters allowed for the join message. Default: 280. Maximum: 280. |
WARNING
Fully inactive queues may be removed after three months, but interacting with the queue in any way will reset this period. If a queue is removed, a new token does not need to regenerated, and the same, previous token can be re-used. The queue ID will be regenerated, however.
Setup
This will walk you through the process of setting up the queue system for your channel. Currently, the easiest bot to use with the system is StreamElements.
Step 1
Visit the setup page to generate the required links.
Step 2
Visit your commands dashboard and click + New Command. Name the command appropriately, ensuring it does not conflict with any existing commands. Although recommended command names are given, any word can be used. Copy and paste the corresponding customapi link into the response field.
KEEP IN MIND
You may add a usage cost to the command, but keep in mind that the cost is associated with the command's usage and bears no relevance to the queue itself. For example, you may place a cost of 25 points on the !join command, so that when a user uses it, they spend 25 points.
However, if they were to then use the command again, they would spend another 25 points and the response would be 'User is already position #1 in the queue!'. To prevent users incurring additional costs, it would be recommended to place a user cooldown on the command and instruct users to check their position in the queue before attempting to join, in the event they have already joined. Placing a cooldown on the !position command would then also be necessary.
Step 3
Set the appropriate permission level of the command. Ensure that the moderator permission is set for the !queue command. This command is responsible for managing the queue. Save the command and repeat the step above for each of the other commands.
ALIAS COMMANDS
Occasionally, you may find yourself using one queue sub-option more than others. For example, !queue next
. You can create an alias command and reduce this to simply !next
. To do this, follow the format below (for convenience, the setup page has an alias command selector, but make sure to replace the token with your own).
$(customapi.https://api.thefyrewire.com/twitch/queue/OPTION/TOKEN?query=$(queryencode $(1:)|null))
Replace OPTION
with the queue sub-option, for example, next
and replace TOKEN
as necessary. Ensure that the alias command's permission is set to moderator!
The queue is now fully set up and ready to be used. Below is a closer look at each of the queue actions and available options.
Actions
There are six core queue actions: join
, leave
, position
, info
, list
and queue
. Of the six, only queue
requires moderator permissions. In the example below, each of the commands will assume the original command name is used.
Join
Allows a user to join a queue, if it is currently open.
Usage | Response | Notes |
---|---|---|
!join | thefyrewire has joined the queue! Position: #1 | If multi-join is enabled, the current highest position that the user holds will also be given. |
!join hello world | thefyrewire has joined the queue! Position: #1 | This message is recalled when the user is selected later. The optional parameter msglimit can be used to limit the number of characters of the message. By default, a message of up to 280 characters is permitted. |
!subjoin | thefyrewire has joined the queue with priority! Position: #1 | The optional parameter priority can used to create a secondary join command, the permission of which can be set to subscribers only. Those joining with this command will stack at the top of the queue. As with the regular join command, a message can be given. |
Leave
Allows a user to leave a queue, even if it is currently closed. If the user has joined multiple times in the same queue, all of their positions will be removed. If the user only wishes to remove their highest position and leave their other places intact, they should ask a moderator to use the remove
sub-option.
Usage | Response |
---|---|
!leave | thefyrewire has left the queue! |
Position
Allows a user to see their position in the queue, find another user's position, see the next N users in the queue or which user is in a specific position. If the user has joined multiple times in the same queue, the number of other positions they hold in the queue is also given.
Usage | Response |
---|---|
!position | thefyrewire is in position #1! |
!position AndrewOscarDelta | AndrewOscarDelta is in position #2! |
!position 3 | Next 3 users: #1. thefyrewire, #2. AndrewOscarDelta, #3. Albastter |
!position #5 | AsahiZuru is in position #5! |
Info
Returns information about the queue. If multi-join is enabled, the number of permitted joins per user is also shown.
Usage | Response |
---|---|
!info | Current queue: default [OPEN] - Users currently in queue: 1 |
List
Allows a user to leave a queue, even if it is currently closed.
Usage | Response | Notes |
---|---|---|
!list | https://thefyrewire.com/pog/q/thefyrewire | Associates the queue with the Queue Viewer webpage. This command must be used at least once to generate the queue page. |
!list queues | Queues: default | Returns a list of the queues in chat. |
Queue Options
A variety of options allows the broadcaster and moderators to manage the queue: open
, close
, clear
, new
, delete
, rename
, set
, next
, stash
, add
, remove
, purge
, superpurge
, promote
, demote
and id
. Each of the options here can be made into alias commands for convenience.
Open
Opens the queue and allows users to join. Multi-joins can be enabled to allow users to join multiple times.
Usage | Response | Notes |
---|---|---|
!queue open | The queue has been opened! | Returns an error if the queue is already opened. |
!queue open multi | The queue has been opened! Each user can join up to 5 times. | If multi is specified on its own, by default the queue will allow users to join up to 5 times each. To change the number of permitted joins, the queue should first be closed, then re-opened with the desired number. |
!queue open multi 10 | The queue has been opened! Each user can join up to 10 times. | If a number is specified after multi , the queue will allow users to join that many times. The maximum is 20. Exceeding this amount will default to 20. |
Close
Closes the queue, but users are still able to leave. Multi-joins will be reset to false. If the queue is re-opened, the multi-join amount will need to be specified again. Closing the queue only prevents users from joining. All other queue options remain functional.
Usage | Response |
---|---|
!queue close | The queue has been closed! |
Clear
Clears the current queue. If the queue is currently open, it will remain open.
Usage | Response |
---|---|
!queue clear | The queue has been cleared! |
New
Creates a new, custom-named queue. The active queue will be switched to this new queue. A maximum of 5 custom queues can be created. The queue name has a limit of 50 characters. To later modify the capitalisation of the queue name, use the rename option.
Usage | Response |
---|---|
!queue new My awesome queue | My awesome queue has been created. Current queue switched. |
Delete
Deletes a custom-named queue. This will remove all users in that queue and the active queue will be switched back to the default queue. The default queue cannot be removed. The query is not case-sensitive.
Usage | Response |
---|---|
!queue delete my awesome queue | My awesome queue has been deleted! |
Rename
Renames the current queue. Can be used to change the capitalisation of the queue name or can be used to rename the queue to something entirely different. The default queue cannot be renamed. The queue name has a limit of 50 characters.
Usage | Response |
---|---|
!queue rename MY AWESOME QUEUE | My awesome queue has been renamed to MY AWESOME QUEUE. |
Set
Sets the active queue. By default, the queue that is switched to will be closed. The query is not case-sensitive.
Usage | Response |
---|---|
!queue set my awesome queue | The active queue has been switched to MY AWESOME QUEUE! |
Next
Selects the user(s) from the queue. The selected users are subsequently removed from the queue. If the user has attached a message, it will also be shown when they are selected.
This may be especially useful as an independent alias command.
Usage | Response | Notes |
---|---|---|
!queue next | Selected next: thefyrewire | Returns the next user in the queue. |
!queue next 3 | Selected next: #1. thefyrewire, #2. Cazzler, #3. Scribbleh | Returns the next 3 users in the queue. |
!queue next random | Selected random: #3. Scribbleh | Returns a random user from the queue. |
!queue next 3 random | Selected next: #2. Cazzler, #3. Scribbleh, #1. thefyrewire | Returns 3 random users from the queue. |
!queue next priority | Selected next priority: thefyrewire | Returns the next priority user in the queue. |
!queue next 3 priority | Selected next priority: #1. thefyrewire, #2. Cazzler, #3. Scribbleh | Returns the next 3 priority users from the priority stack. |
!queue next random priority | Selected random priority: #2. Cazzler | Returns a random priority user from the priority stack. |
!queue next 3 random priority | Selected next priority: #1. thefyrewire, #3. Scribbleh, #2. Cazzler | Returns 3 random priority users from the priority stack. |
PRIORITY SELECTION
When specifying priority
for selection, an error will be returned if there aren't enough priority users. Useful for indicating when the end of the priority stack has been reached. For instance, if there are two subscribers at the top of the queue, doing !queue next 3 priority
will return an error. The broadcaster could then attempt to find another subscriber/VIP to join the stack before asking other regular viewers.
Aliases include: sub
, subs
, vip
and vips
.
BETA
StashIf the last selected user was sequential, then they may be stashed. This stores the user back at the top of the queue and automatically returns the next user.
This may be useful where the newly selected user may be AFK or otherwise unresponsive. They can then be safely and temporarily stashed at the top of the queue while another user is selected.
Usage | Response |
---|---|
!queue stash | Stashed thefyrewire and selected next: AndrewOscarDelta |
EXPERIMENTAL
This option is experimental and its functionality may change or break without notice.
Add
Adds a user to the active queue, even if it's currently closed. The user will be inserted at the back of the queue. An optional position can be specified to add them at a specific place.
Usage | Response |
---|---|
!queue add thefyrewire | thefyrewire was added to the queue! Position: #5 |
!queue add AndrewOscarDelta 1 | AndrewOscarDelta was added to the queue! Position: #1 |
Remove
Removes a user (or their highest position) from the queue. If the user has other positions in the queue, the number of remaining positions will also be given.
To remove all of a user's positions, use either purge
or superpurge
.
Usage | Response |
---|---|
!queue remove thefyrewire | #1. thefyrewire has been removed from the queue. |
Purge
Purges all of a user's positions from the active queue.
To remove a user from all queues use superpurge
or use remove
to only remove a user's highest position.
Usage | Response |
---|---|
!queue purge thefyrewire | thefyrewire has been purged from the queue! (Positions #1, #2) |
Superpurge
Purges all of a user's positions from all queues. The equivalent of a Thanos snap.
To only remove all of a user's positions from the active queue, use purge
or remove
to only remove a user's highest position.
Usage | Response |
---|---|
!queue superpurge thefyrewire | thefyrewire has been purged from all queues: default (#1, #2), my awesome queue (#1) |
Promote
Boosts a user to the top of the queue. Does not work for users who have joined multiple times. The promoted user will take precedence over priority users.
Usage | Response |
---|---|
!queue promote thefyrewire | thefyrewire has been promoted to the front of the queue! |
Demote
Sends a user to the back of the queue. Does not work for users who have joined multiple times.
Usage | Response |
---|---|
!queue demote thefyrewire | thefyrewire has been demoted to the back of the queue! |
ID
Returns the queue ID.
Usage | Response |
---|---|
!queue id | Queue ID: |