Skip to content
Cloudflare API
Start here
API Reference
Waiting Rooms
Page

Create a custom waiting room page preview

waiting_rooms.page.preview(PagePreviewParams**kwargs) -> PagePreviewResponse
POST/zones/{zone_id}/waiting_rooms/preview

Creates a waiting room page preview. Upload a custom waiting room page for preview. You will receive a preview URL in the form http://waitingrooms.dev/preview/<uuid>. You can use the following query parameters to change the state of the preview:

  1. force_queue: Boolean indicating if all users will be queued in the waiting room and no one will be let into the origin website (also known as queueAll).
  2. queue_is_full: Boolean indicating if the waiting room's queue is currently full and not accepting new users at the moment.
  3. queueing_method: The queueing method currently used by the waiting room.
    • fifo indicates a FIFO queue.
    • random indicates a Random queue.
    • passthrough indicates a Passthrough queue. Keep in mind that the waiting room page will only be displayed if force_queue=true or event=prequeueing — for other cases the request will pass through to the origin. For our preview, this will be a fake origin website returning "Welcome".
    • reject indicates a Reject queue.
  4. event: Used to preview a waiting room event.
    • none indicates no event is occurring.
    • prequeueing indicates that an event is prequeueing (between prequeue_start_time and event_start_time).
    • started indicates that an event has started (between event_start_time and event_end_time).
  5. shuffle_at_event_start: Boolean indicating if the event will shuffle users in the prequeue when it starts. This can only be set to true if an event is active (event is not none).

For example, you can make a request to http://waitingrooms.dev/preview/<uuid>?force_queue=false&queue_is_full=false&queueing_method=random&event=started&shuffle_at_event_start=true 6. waitTime: Non-zero, positive integer indicating the estimated wait time in minutes. The default value is 10 minutes.

For example, you can make a request to http://waitingrooms.dev/preview/<uuid>?waitTime=50 to configure the estimated wait time as 50 minutes.

Security
API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
Accepted Permissions (at least one required)
Waiting Rooms Write
ParametersExpand Collapse
zone_id: str

Identifier.

maxLength32
custom_html: str

Only available for the Waiting Room Advanced subscription. This is a template html file that will be rendered at the edge. If no custom_page_html is provided, the default waiting room will be used. The template is based on mustache ( https://mustache.github.io/ ). There are several variables that are evaluated by the Cloudflare edge:

  1. {{waitTimeKnown}} Acts like a boolean value that indicates the behavior to take when wait time is not available, for instance when queue_all is true.
  2. {{waitTimeFormatted}} Estimated wait time for the user. For example, five minutes. Alternatively, you can use:
  3. {{waitTime}} Number of minutes of estimated wait for a user.
  4. {{waitTimeHours}} Number of hours of estimated wait for a user (Math.floor(waitTime/60)).
  5. {{waitTimeHourMinutes}} Number of minutes above the waitTimeHours value (waitTime%60).
  6. {{queueIsFull}} Changes to true when no more people can be added to the queue.

To view the full list of variables, look at the cfWaitingRoom object described under the json_response_enabled property in other Waiting Room API calls.

ReturnsExpand Collapse
class PagePreviewResponse: …
preview_url: Optional[str]

URL where the custom waiting room page can temporarily be previewed.

Create a custom waiting room page preview

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.waiting_rooms.page.preview(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
    custom_html="{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}",
)
print(response.preview_url)
{
  "result": {
    "preview_url": "http://waitingrooms.dev/preview/35af8c12-6d68-4608-babb-b53435a5ddfb"
  }
}
Returns Examples
{
  "result": {
    "preview_url": "http://waitingrooms.dev/preview/35af8c12-6d68-4608-babb-b53435a5ddfb"
  }
}