Add the Whiteboard plugin

The Whiteboard plugin is a collaborative whiteboard that Cloudflare hosts and operates. Participants draw, write, and diagram together on a shared board inside the meeting, and see each other's cursors and names as they work.

You add the Whiteboard plugin with the same plugins API you use for your own plugins. There is nothing to deploy or operate.

• Draw shapes, arrows, lines, freehand strokes, and text on a shared board.
• See every participant's cursor and RealtimeKit display name in real time.
• Join late or reconnect and continue with the current board.
• Export the board as an image.

Each meeting has one board. The board stays the same across all sessions of that meeting, so participants continue where they left off when the meeting starts again. For details, refer to Board data.

The Whiteboard plugin does not support images, frames, embedded web content, or importing board files. Participants who try to add these see a message that they are not available.

• Read the Plugins guide. This guide builds on it.
• Get the participant's auth token: the token returned when you add a participant to a meeting. This is the same token you pass to the SDK when you initialize it.

Each participant loads the Whiteboard plugin from the following URL, with their auth token in the URL fragment after #:

https://whiteboard-v2.plugins.realtime.cloudflare.com/#authToken=<auth_token>

The Whiteboard plugin verifies the token with RealtimeKit, then opens the board for the token's meeting with the participant's display name. You do not pass a meeting ID or participant name.

Browsers do not send the URL fragment to servers or include it in Referer headers, so the token stays out of request logs. The plugin also removes the token from its address as soon as it loads.

Select your platform to see the code for each step.

const WHITEBOARD_URL = "https://whiteboard-v2.plugins.realtime.cloudflare.com/";

function createWhiteboard(authToken: string): HTMLIFrameElement {
	const iframe = document.createElement("iframe");
	iframe.style.width = "100%";
	iframe.style.height = "100%";
	iframe.style.border = "none";
	// Lets participants copy and paste on the board.
	iframe.allow = "clipboard-read; clipboard-write";
	// The plugin does not need your page's address.
	iframe.referrerPolicy = "no-referrer";
	iframe.src = `${WHITEBOARD_URL}#authToken=${encodeURIComponent(authToken)}`;
	return iframe;
}

const whiteboardElement = createWhiteboard("<auth_token>");

Register the Whiteboard plugin when you initialize the SDK.

RealtimeKitClient.init({
	authToken: "<auth_token>",
	defaults: {
		plugins: [
			{
				id: "whiteboard",
				name: "Whiteboard",
				icon: "https://example.com/whiteboard.png",
				permissions: {
					canActivate: true,
					canDeactivate: true,
				},
				component: whiteboardElement,
			},
		],
	},
});

val authToken = "<auth_token>"

val meetingInfo = RtkMeetingInfo(
	authToken = authToken,
	pluginConfigs = listOf(
		RtkClientPluginConfig(
			id = "whiteboard",
			name = "Whiteboard",
			icon = "https://example.com/whiteboard.png",
			url = "https://whiteboard-v2.plugins.realtime.cloudflare.com/#authToken=$authToken",
			permissions = RtkClientPluginPermissions(
				canActivate = true,
				canDeactivate = true,
			),
		),
	),
)

let authToken = "<auth_token>"

let meetingInfo = RtkMeetingInfo(
	authToken: authToken,
	pluginConfigs: [
		RtkClientPluginConfig(
			id: "whiteboard",
			name: "Whiteboard",
			icon: "https://example.com/whiteboard.png",
			url: "https://whiteboard-v2.plugins.realtime.cloudflare.com/#authToken=\(authToken)",
			permissions: RtkClientPluginPermissions(
				canActivate: true,
				canDeactivate: true
			)
		)
	]
)

const authToken = "<auth_token>";
const [meeting, initMeeting] = useRealtimeKitClient();

await initMeeting({
	authToken,
	defaults: {
		plugins: [
			{
				id: "whiteboard",
				name: "Whiteboard",
				icon: "https://example.com/whiteboard.png",
				permissions: {
					canActivate: true,
					canDeactivate: true,
				},
				component: {
					src: `https://whiteboard-v2.plugins.realtime.cloudflare.com/#authToken=${authToken}`,
				},
			},
		],
	},
});

For a description of every configuration field, refer to Register a plugin.

If you use the UI Kit, the Whiteboard plugin appears in the plugins panel, and participants open and close it from there.

To control the whiteboard from your own UI, activate or deactivate the plugin. Both apply to every participant in the session. For examples, refer to Activate and deactivate a plugin.

• Who can open the board: Only participants with a valid auth token for the meeting can open its board. The token's meeting decides which board opens, so a participant cannot open another meeting's board.
• Who can edit: Every participant who has the board open can edit it. Presets do not control whiteboard editing.
• Who can open or close the plugin: Use the plugin's permissions to control who can activate or deactivate it for the session.
• Where you can embed it: The Whiteboard plugin works on any domain. You do not need to register your app's origin.

A participant's auth token stays valid until it expires, even after you remove them from the meeting, so they can still open the board until then.

To restore a board when a new session of the same meeting starts, Cloudflare stores all board content for the meeting on Cloudflare infrastructure. Board content includes every shape, line, freehand stroke, and piece of text that participants add.

• Board content is kept indefinitely and is not deleted when a session ends.
• There is currently no API to clear or delete a board.
• Participant cursors and display names are shared only with participants who have the board open. They are not stored with the board.

For retention periods of other RealtimeKit data, refer to Data retention.

The Whiteboard plugin is designed for collaborative meetings, not large broadcasts. Keep the following limits in mind when you plan its use:

• Participants on a board: A board supports a limited number of participants connected at the same time. Participants who join a full board cannot connect and see a Reconnect button. For webinars and other large audiences, let a small group edit the board, and share it with everyone else through screen sharing.
• Board size: Each board has a maximum size. Boards with many elements or very long freehand strokes can reach it. When a board is full, new changes are not saved and participants see a message.
• Element size: A single element, such as a very long continuous freehand stroke or a large block of text, can be too large to share. Participants see a message, and the change is not saved.
• Connection attempts: Repeated connection attempts from the same network in a short time are rate limited. Participants see Too many attempts and can try again after a minute.

When the board cannot load, the plugin shows a message instead of the board. Use the following table to resolve these messages and other common problems.

• Review the Plugins API for the complete Plugin and Plugins reference.
• Listen to plugin events to react when participants open or close the whiteboard.
• Build your own plugin for other collaborative experiences.