Skip to content
Waiting Room
Visit Waiting Room on GitHub
Set theme to dark (⇧+D)

Create scheduled events

When you want to customize the behavior of a waiting room for a specific period of time — such as changing the queueing method or increasing the total active users — set up a scheduled event.

Any properties set on the event will override the default property on the waiting room for the duration of the event.

Create an event

At the moment, you can only create an event using the API.

To create an event, make a POST request including required and optional parameters. Any properties set on the event will override the default property on the waiting room for the duration of the event.

If you are using a custom template, you may want to add relevant variables to your template (listed under the json_response_enabled parameter).


Though most properties are identical to those on a regular waiting room, there are a few unique to creating an event:

  • name (required): Unique name with alphanumeric characters, hyphens, and underscores.
  • event_start_time (required): ISO 8601 timestamp that marks the start of the event. At this time, queued users will be processed with the event's configuration. Must occur at least 1 minute before event_end_time.
  • event_end_time (required): ISO 8601 timestamp that marks the end of the event.
  • shuffle_at_event_start: If true and prequeue_start_time is not null, users in the prequeue will be shuffled randomly at the event_start_time. Commonly used to ensure fairness if your event is using a FIFO queueing method.
  • prequeue_start_time: ISO 8601 timestamp that marks when to begin queueing all users before the event starts. Must occur at least 5 minutes before event_start_time.
  • description: A text description providing more detail about the event.
  • suspended: If true, the event is ignored and traffic is handled based on the waiting room's normal configuration.

Queueing methods

When setting up events, you may want to also adjust the default queueing methods for your waiting room.

Set the waiting room's queueing method to Passthrough when you want to allow traffic normally, but then restrict traffic during a scheduled event.

Set the waiting room's queueing method to Reject when you want to block all traffic normally, but then allow traffic during special events like signups or ticket sales.

Set up a "lottery"

Set up a "lottery" system to reward all users who enter into the queue prior to your event start time.

Users who reach your application during the prequeue period are randomly assigned a place in line when the event starts. If the event uses FIFO ordering, users who reach your application after the prequeue period are assigned places after users from the prequeue.

To set up a "lottery", include the following parameters in your API request:

  • prequeue_start_time
  • shuffle_at_event_start

Preview an event configuration

Since some properties set on an event will override the default property of a waiting room for the duration of an event, you should use the API to preview an event configuration before it begins.

This command shows you the event's configuration as if it were active, meaning that inherited fields from the waiting room will display their current values.

Edit an event

To edit an event, use a PATCH request.

Disable events

You can disable an event by setting its suspended parameter to true.

Additionally, events will not become active if a waiting room itself is Disabled.

Other API commands

Get event detailsGET
List scheduled eventsGET
Delete eventDELETE