[CustomAPI] Queue system


I’ve been asked to create a queue system/command for a channel, even though on the forums we have a couple queue systems available, through for example the creative usage of the quote system, I thought this would be a fun little project to play around with various stuff, Nightbot headers, Nightbot API, OAuth.

The code behind the system is available at: GitHub - xgerhard/nbqueue: Queue script for Nightbot
If you have improvements or issues feel free to post them there, or let me know in the comments here.


A basic queue system for Nightbot. The usage is pretty straight forward, !join and !leave for users to enter or leave the queue, the user can check their position in the queue with !position. Moderators can !open or !close the queue and pick a user from the queue with !next.

The command supports multiple queues, but there can only be one active. Only the active channel is joinable. Moderators can manage queues by using !q add $queueName or !q del $queueName, to switch to a different queue use !q set $queueName. To empty the queue a moderator can use !q clear, or remove one user by using !q remove $position, where $position is the position of the user in that specific queue (this position can be found by using !q list).

User commands

  • join $message - Joines the current queue with optional message “$message”, this message is displayed when the user will be picked from the queue
  • leave - Leaves the current queue
  • position - Displays the position from the user in the current active queue
  • list - Displays a link to a webpage with the full list of users in the queue
  • info - Displays the current queue information, if the queue is open and how many people are in it
  • who $x - Displays the next $x people that are in the queue

Moderator commands

  • open - Opens the current queue
  • close - Closes the current queue
  • next $x - Picks and removes the first $x users from the queue, the $x is optional
  • random $x - Picks and removes $x random users from the queue, the $x is optional
  • clear - Clears the current queue
  • add $name - Creates a new queue with the name $name
  • del $name - Deletes the queue with name $name (the default queue can’t be deleted)
  • set $name - Will set the queue with name $name as active queue.
  • remove $position - Will remove the user with position $position from the queue
  • userlevel $userlevel - Will set the userlevel of current active queue, so you can create for example sub only queues. Available userlevels: moderator, vip, regular, subscriber, everyone.
  • ul $userlevel - Short version of the userlevel command
  • promote $position - Will promote the user with position $position to first position of the queue (next person)
  • setlimit $number - Will set a limit of users that can join the current active queue
  • adduser $name - Will add user $username to the current active queue (Twitch only)


Sign in with Nightbot here, the installer will add the selected commands to Nightbot: https://nbq.gerhard.dev/install/auto

Changelog, December 8, 2018 - userlevel option added

This will give you the option to set your current queue open for a specific group of users.
The userlevel option is available directly from the !q command, for example: !q userlevel subscriber.
If you want a separate !userlevel command, it is now included in the automatic installation. If you have installed before this date you can add the alias command yourself:
!commands add !userlevel -a=!q userlevel $(query)

Changelog, April 29, 2019 - random, promote commands added

These commands can be used to pick random users from your queue, or reward a user by promoting the user to the first position of the queue. They are available through the !q command, for example: !q random or !q promote 2 (where 2 is the queue position of the user).
If you want separate commands for these functions, they are now included in the automatic installation. If you have installed before this date, you can add the alias commands yourself:
Random: !commands add !random -a=!q random $(query)
Promote: !commands add !promote -a=!q promote $(query)

Changelog, Feb 21, 2021 - Manual add users

For Twitch channels, moderators can now add users manually to the queue.
Usage is: !q adduser $username for example !q adduser xgerhard


Hello, I would like to thank you for your work on this. I have implemented this on a channel I mod. The streamer uses restream to stream on Youtube, Twitch, and Mixer. Nightbot is setup on only youtube as that is where the majority of his audience participates. The queue system works great until a Twitch or Mixer user tries to join. Is it possible to have a mod manually insert a username in the list? Sorry if this sounds like a noobish question, but I am a noob at all this lol… Or would it be easy to modify or add any command to allow this?
Thank you again for this queue system you have created.

Heya, thanks! Unfortunately this is not possible at the moment. The system is currently setup that only the user who types the command can join, in the background Nightbot will send that user’s ID which I link to the queue.

Edit: this feature is possible now


Ok, thanks again for your help!


i am mod in my friend’s channel and i am having issues using this command… whenever i use any of them commands the nightbot returns me the message “Remote Server Returned Code 500”. Do u know what is happening or what am i doing wrong ?

Thanks in advance.

@Yamihiken Heya, sorry about that, could you try again, the error should be resolved.

Hey, thanks for making the API! Really loving it and making it easier to play with people on Twitch. I have one thing I need to ask, whenever I open up a queue and I type !list, for some reason the list seems to be empty. It just says “Queue: Default Status: Open” but nothing else. I have it on both Youtube and Twitch, is it possible it can’t do both?

Heya! If you click/tap on that sentence “Queue: Default Status: Open” the list of users that are in that queue will show. If you click/tap on it again the list will be hidden again.

It should work for both Youtube and Twitch however they most likely will be treated as seperated channels. So Youtube users can’t join the Twitch queue, and vice versa.

is it synonymous in German thanks in advance.

You mean if there is a German version? Currently only English. However you can change the commandcodes manually to German during the installation.

okay thanks i’ll try it

could you please do that for me, I did not know how.

If I now have a Custom Waiting Room, how can I activate it?

You can use this, just replace queuename with the name you gave the room.
!set queuename

okay thanks for the help

When my subs join, the position always states they are all $1 in queue. A way to fix it?

This is fixed, thanks for reporting!

Is it possible to translate the responses of Nightbot ?

Heya, this is currently not possible.

Ich raff das hier nicht mit dem Token, was da so schlimm dran sein soll.

Zwei Stunden meiner Zeit verschwendet um dann zu sagen, komm lass es sein … wäre nice zu haben, aber wenn will ich es schick haben, sodass man den Quote wie folgt hätte mit !addquote - [name] [ID] [Quote] [Game] [Time]