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

Create a waiting room via the API

Create a waiting room by appending the following endpoint in the Waiting Room API to the Cloudflare API base URL.

POST zones/{zone_identifier}/waiting_rooms

The Cloudflare API base URL is:

https://api.cloudflare.com/client/v4

For authentication instructions, see Getting Started: Requests in the Cloudflare API documentation.

For help with endpoints and pagination, see Getting Started: Endpoints.

Configure your waiting room with the following required parameters in the data field:

  • name - A unique name for the waiting room. Use only alphanumeric characters, hyphens, and underscores.
  • host - Host name for which you want to configure a waiting room.
  • total_active_users - The total number of active user sessions on the route at a point in time.
  • new_users_per_minute - The number of new users gaining entry into the route every minute.

The following parameters are optional:

  • path - The path within the host for which you want to configure a waiting room. The waiting room will be enabled for all subpaths as well.
  • description - A description of the the waiting room.
  • session_duration - Lifetime of a cookie (in minutes) set by Cloudflare for users who get access to the route.
  • custom_page_html - HTML code to customize the appearance of your waiting room. Cloudflare provides a sample HTML template that enables the display of estimated wait time on the waiting room page. The default waiting room is used if custom_page_html is not specified. See Waiting Room API properties.

Example

The following example API request configures a waiting room.

curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone-id}/waiting_rooms" \
-H "X-Auth-Email: user@example.com" \
-H "X-Auth-Key: xxxxxxxx" \
-H "Content-Type: application/json" \
--data '{"name":"shop_waiting_room",
"description":"Waiting room for webshop",
"host":"shop.example.com",
"path":"/shop",
"queue_all": true,
"new_users_per_minute":200,
"total_active_users":300,
"session_duration":1,
"disable_session_renewal": false,
"json_response_enabled": false,
"queueing_method": "FIFO",
"cookie_attributes": {
"samesite": "auto",
"secure": "auto"
},
}'

The response for the request above is:

{
"success": true,
"errors": [],
"messages": [],
"result": [
{
"id": "1111111111111111111111",
"created_on": "2014-01-01T05:20:00.12345Z",
"modified_on": "2014-01-01T05:20:00.12345Z",
"name": "shop_waiting_room",
"description": "Waiting room for webshop",
"host": "shop.example.com",
"path": "/shop",
"queue_all": true,
"new_users_per_minute": 200,
"total_active_users": 300,
"session_duration": 1,
"disable_session_renewal": false,
"json_response_enabled": false,
"queueing_method": "FIFO",
"cookie_attributes": {
"samesite": "auto",
"secure": "auto"
},
}
]
}

Customize a waiting room web page

You can use the Waiting Room API to customize the web page served to visitors when they are placed in a virtual waiting room.

In the following PATCH request, the custom_page_html field contains the HTML code for the customized waiting room:

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/{zone-id}/waiting_rooms/{waiting-room-id}"
-H "X-Auth-Email: user@example.com"
-H "X-Auth-Key: xxxxxxxx"
-H "Content-Type: application/json"
--data '{"custom_page_html":"<p>Include custom HTML here</p>"}'
{
"success": true,
"errors": [],
"messages": [],
"result": [
{
"id": "1111111111111111111111",
"name": "webshop-waiting-room",
"description": "Waiting room for webshop",
"host": "example.com",
"path": "/shop",
"suspended": false,
"queue_all": false,
"new_users_per_minute": 200,
"total_active_users": 300,
"session_duration": 1,
"disable_session_renewal": false,
"json_response_enabled": false,
"queueing_method": "FIFO",
"cookie_attributes": {
"samesite": "auto",
"secure": "auto"
},
"custom_page_html": "<p>Include custom HTML here</p>",
"created_on": "2014-01-01T05:20:00.12345Z",
"modified_on": "2014-01-01T05:20:00.12345Z"
}
]
}

Preview the HTML code for a customized waiting room

Before making an API request to configure a waiting room web page with customized HTML, you can preview your custom HTML by uploading it to a preview endpoint:

POST https://api.cloudflare.com/client/v4/zones/<zone_id>/waiting_rooms/preview

In the request body, include the customized HTML content in the custom_html field:

{
"custom_html": "<p>Include custom HTML here</p>"
}

Note that you pass HTML content to the preview endpoint in the custom_html field, but when you are using the API to configure a waiting room, you pass the HTML content in the custom_page_html field.

Example request:

curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone-id}/waiting_rooms/preview"
-H "X-Auth-Email: user@example.com"
-H "X-Auth-Key: xxxxxxxx"
-H "Content-Type: application/json"
--data '{"custom_html":"<p>Include custom HTML here</p>"}'

The preview endpoint returns a temporary URL in the response body where you can preview your custom page:

{
"result": {
"preview_url": "https://waitingrooms.dev/preview/111111111111"
},
"success": true,
"errors": [],
"messages": []
}

You do not have to have a Cloudflare account to access the preview link, so you can validate the waiting room webpage on multiple devices.

Preview the default or current waiting room web page

After generating a preview URL, use the following endpoint to generate a link to preview the currently configured web page for a waiting room, or the default page if no custom page is configured.

GET https://waitingrooms.dev/preview/{preview-id}

The link in the response displays the content of the custom_page_html field, rendered with mustache.

Use the optional force_queue query parameter to preview the waiting room web page when all traffic is force-queued.