Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sidebar:

---

import { Details } from "~/components"
import { Details, APIRequest } from "~/components"

Because of how a waiting room [tracks visitor progress](#background), you need to [specify certain cookie attributes](#allow-cookies-to-pass-through-iframes) to properly embed a waiting room in an iFrame.

Expand Down Expand Up @@ -47,28 +47,27 @@ If you are embedding a waiting room in an iFrame, specify the following values o

<Details header="Request">

```bash
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/waiting_rooms" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "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": "none",
"secure": "auto"
}
}'
```
<APIRequest
path="/zones/{zone_id}/waiting_rooms"
method="POST"
json={{
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: "none",
secure: "auto"
}
}}
/>


</Details>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sidebar:

---

import { Details } from "~/components"
import { Details, APIRequest } from "~/components"

A Waiting Room Bypass Rule is a type of Waiting Room Rule built on Cloudflare’s Ruleset Engine and managed via the Waiting Room API. A Waiting Room Bypass Rule allows you to indicate specific traffic or areas of your site or application that you do not want a waiting room to apply to. Each bypass rule is created and managed at the individual waiting room level for precise control over your waiting room traffic.

Expand Down Expand Up @@ -88,31 +88,30 @@ Configure your bypass rule with the following required and optional parameters:

If your waiting room is configured at `example.com/` and you would like all traffic visiting `example.com/bypassme` and all of its subpaths. In this example, we also want to ensure any subrequests of `js`, `css`, or `png` from also bypass the waiting room to ensure all assets are loaded properly on the paths being bypassed. Note that in this example, all requests ending in `js`, `css` or `png` will bypass the waiting room regardless of the subpath. If this is not your intended use case, please alter the expression to suit your specific requirements and site architecture.

```bash
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/waiting_rooms/{room_id}/rules" \
--header "Authorization: Bearer <API_TOKEN>" \
--data '{
"description": "subpath bypass",
"expression": "starts_with(http.request.uri.path, \"/bypassme\") or ends_with(http.request.uri.path, \".js\") or ends_with(http.request.uri.path, \".css\") or ends_with(http.request.uri.path, \".png\")",
"action": "bypass_waiting_room"
}'
```

<APIRequest
path="/zones/{zone_id}/waiting_rooms/{waiting_room_id}/rules"
method="POST"
json={{
description: "subpath bypass",
expression: "starts_with(http.request.uri.path, \"/bypassme\") or ends_with(http.request.uri.path, \".js\") or ends_with(http.request.uri.path, \".css\") or ends_with(http.request.uri.path, \".png\")",
action: "bypass_waiting_room"
}}
/>

</Details>


<Details header="Allow a defined list of IPs to bypass the waiting room">

```bash
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/waiting_rooms/{room_id}/rules" \
--header "Authorization: Bearer <API_TOKEN>" \
--data '{
"description": "ip list bypass",
"expression": "ip.src in $bypass_ip_list",
"action": "bypass_waiting_room"
}'
```
<APIRequest
path="/zones/{zone_id}/waiting_rooms/{waiting_room_id}/rules"
method="POST"
json={{
description: "ip list bypass",
expression: "ip.src in $bypass_ip_list",
action: "bypass_waiting_room"
}}
/>


</Details>
Expand Down
47 changes: 23 additions & 24 deletions src/content/docs/waiting-room/how-to/create-waiting-room.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ head:
content: Create a waiting room
---

import { TabItem, Tabs } from "~/components";
import { TabItem, Tabs, APIRequest } from "~/components";

You can create a waiting room from the dashboard or via API.

Expand Down Expand Up @@ -37,29 +37,28 @@ To create a Waiting Room using the API, send a [`POST` request](/api/resources/w
- For authentication instructions, refer to [Create an API token](/fundamentals/api/get-started/create-token/).
- For help with endpoints and pagination, refer to [Make API calls](/fundamentals/api/how-to/make-api-calls/).

```json title="Request"
curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_identifier}/waiting_rooms" \
--header 'Authorization: Bearer REDACTED' \
--header '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",
"queueing_status_code": 202,
"cookie_attributes": {
"samesite": "auto",
"secure": "auto"
}
}'
```
<APIRequest
path="/zones/{zone_id}/waiting_rooms"
method="POST"
json={{
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",
queueing_status_code: 202,
cookie_attributes: {
samesite: "auto",
secure: "auto"
}
}}
/>

The response contains the complete definition of the newly created Waiting Room.

Expand Down
35 changes: 22 additions & 13 deletions src/content/docs/waiting-room/how-to/customize-waiting-room.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ sidebar:

---

import { APIRequest } from "~/components";

You can customize your waiting room from the dashboard or via API.

## Customize a waiting room from the dashboard
Expand Down Expand Up @@ -167,13 +169,19 @@ You can use the Waiting Room API to customize the web page served to visitors wh

In the following `PATCH` request, the `custom_page_html` field contains the HTML code for the [customized waiting room](/waiting-room/how-to/customize-waiting-room/):

```bash
curl --request PATCH \
"https://api.cloudflare.com/client/v4/zones/{zone_id}/waiting_rooms/{waiting_room_id}" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{"custom_page_html": "<p>Include custom HTML here</p>"}'
```
<APIRequest
path="/zones/{zone_id}/waiting_rooms/{waiting_room_id}"
method="PATCH"
json={{
name: "webshop-waiting-room",
host: "example.com",
new_users_per_minute: 200,
total_active_users: 300,
custom_page_html: "<p>Include custom HTML here</p>"
}}
/>

Response:

```json
{
Expand Down Expand Up @@ -227,12 +235,13 @@ Note that you pass HTML content to the preview endpoint in the `custom_html` fie

Example request:

```bash
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/waiting_rooms/preview" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{"custom_html": "<p>Include custom HTML here</p>"}'
```
<APIRequest
path="/zones/{zone_id}/waiting_rooms/preview"
method="POST"
json={{
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:

Expand Down
37 changes: 27 additions & 10 deletions src/content/docs/waiting-room/how-to/edit-delete-waiting-room.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ sidebar:

---

import { APIRequest } from "~/components";

You can manage your waiting rooms using the [Waiting Room dashboard](/waiting-room/how-to/waiting-room-dashboard/) or the [API](/waiting-room/reference/waiting-room-api/).

:::note
Expand Down Expand Up @@ -35,22 +37,37 @@ For details about updating an active waiting room, refer to [Best practices](/wa

[Replace](https://api.cloudflare.com#waiting-room-update-waiting-room) a configured waiting room by appending the following endpoint to the Cloudflare API base URL.

```bash
PUT zones/{zone_identifier}/waiting_rooms/{identifier}
```
<APIRequest
path="/zones/{zone_id}/waiting_rooms/{waiting_room_id}"
method="PUT"
json={{
name: "webshop-waiting-room",
host: "example.com",
new_users_per_minute: 200,
total_active_users: 300
}}
/>

[Update](https://api.cloudflare.com#waiting-room-patch-waiting-room) a configured waiting room by appending the following endpoint to the Cloudflare API base URL.

```bash
PATCH zones/{zone_identifier}/waiting_rooms/{identifier}
```
<APIRequest
path="/zones/{zone_id}/waiting_rooms/{waiting_room_id}"
method="PATCH"
json={{
name: "webshop-waiting-room",
host: "example.com",
new_users_per_minute: 200,
total_active_users: 300
}}
/>

You only need to include the parameters that you want to update in the `data` field of the PATCH request.

You only need to include the fields you want to update in the payload of the PATCH request.
### Delete a waiting room

Delete a waiting room by appending the following endpoint in the [Waiting Room API](https://api.cloudflare.com#waiting-room-delete-waiting-room) to the Cloudflare API base URL.

```bash
DELETE zones/{zone_identifier}/waiting_rooms/{identifier}
```
<APIRequest
path="/zones/{zone_id}/waiting_rooms/{waiting_room_id}"
method="DELETE"
/>
16 changes: 10 additions & 6 deletions src/content/docs/waiting-room/how-to/monitor-waiting-room.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ sidebar:

---

import { APIRequest } from "~/components";

You can monitor the status of your waiting rooms using the [dashboard](#status-in-the-dashboard) or the [API](#status-in-the-api).

Note that the **Total active users** and **Queued users** shown in the dashboard, as well as through API endpoints are estimates. That data corresponding to each of these metrics is cached for around 30 seconds after the time it takes to be synced from all data centers globally. Therefore, the status will range between 20-50 seconds in the past, depending on the exact moment the data was queried, aggregated, as well as the age of the cache.
Expand Down Expand Up @@ -34,9 +36,10 @@ The **Status** column displays the current state of the waiting room:

[Check whether traffic is queueing in a configured waiting room](/api/resources/waiting_rooms/subresources/statuses/methods/get/) by appending the following endpoint to the Cloudflare API base URL:

```bash
GET zones/{zone_identifier}/waiting_rooms/{identifier}/status
```
<APIRequest
path="/zones/{zone_id}/waiting_rooms/{waiting_room_id}/status"
method="GET"
/>

The response is:

Expand All @@ -45,9 +48,10 @@ The response is:

To check whether a configured waiting room is suspended or whether the traffic is force-queued to the waiting room, append the following endpoint to the Cloudflare API base URL.

```bash
GET zones/{zone_identifier}/waiting_rooms/{identifier}
```
<APIRequest
path="/zones/{zone_id}/waiting_rooms/{waiting_room_id}"
method="GET"
/>

The endpoint above [fetches all settings](/api/resources/waiting_rooms/methods/get/) for a configured waiting room:

Expand Down