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))
1

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.

Stash BETA

If 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:
Last Updated: 11/21/2020, 7:45:40 PM