Install the widget

There are two ways to install the Patchrooms widget. Use the loader for a plain one-liner; use programmatic init when you need to pass options in code.

Primary: the loader (key in the URL)

<script src="https://room.patchrooms.com/v1/patchrooms/pr_xxx.js"></script>

Swap pr_xxx for your project key and drop the tag into your page.

The server bakes your project’s widget config (mascot, shape, anchor, offsets, size, trigger style) and its channels into the loader it serves for your key. So the widget renders with the right theme and channels straight away — no extra request for config, and no flash of an unstyled launcher. It auto-initializes; you don’t call anything.

Note

Config changes you make in the dashboard’s Widget tab propagate to the loader within a few minutes (the loader is cached for 5 minutes).

Programmatic init (SPAs and custom config)

Load the shared bundle, then call Patchrooms.init(...) yourself. Use this when you want to pass options that aren’t baked into the loader — a userId, extra context, a different locale, and so on — or to control the widget’s lifecycle in a single-page app.

<script src="https://room.patchrooms.com/v1/patchrooms.js"></script>
<script>
  Patchrooms.init({ projectKey: 'pr_xxx' });
</script>

Tip

init() is idempotent — calling it again tears down and rebuilds the widget. That’s what you want in an SPA that re-mounts the widget when navigating between views. If you call init() yourself, your call wins; the loader’s auto-init won’t double-mount.

data-* attributes on the script tag

If you embed the shared bundle directly, the widget can also configure itself from data-* attributes on its own <script> tag — no inline init() call needed:

<script src="https://room.patchrooms.com/v1/patchrooms.js" data-project-key="pr_xxx"></script>

Only these attributes are read from the script tag:

Attribute	Maps to	Notes
data-project-key	projectKey	Your public pr_ key.
data-api-url	apiUrl	Override the ingest base URL (rarely needed).
data-locale	locale	en or ru.

init() options

These are the options accepted by Patchrooms.init({ ... }).

Option	Type	Default	Description
projectKey	string (required)	—	Public project key from the dashboard.
locale	'en' | 'ru'	auto-detect from navigator.language	Widget UI language.
apiUrl	string	the widget script’s origin	Ingest API base URL.
userId	string	—	Optional user identifier, forwarded with every report.
extra	Record<string, unknown>	—	Extra fields attached to context.extra on every submission.
captureConsoleErrors	boolean	true	Hook console.error so the last 10 errors auto-attach to reports.
mascot	MascotId	'fox'	Mascot character. See JavaScript widget for the set.
shape	ShapeId	'bubble'	Container shape glued to the viewport edge.
anchor	WidgetAnchor	'middle-right'	Anchor corner/edge of the viewport.
triggerVariant	'frame-tab' | 'devwidget'	'frame-tab'	Trigger launcher style.
size	number	44	Trigger size in px (square), clamped to 32–64.
offsetX	number	0	Horizontal offset from the anchor in px (positive = inward).
offsetY	number	0	Vertical offset from the anchor in px (positive = inward).
widgetId	string	auto-generated	Unique id for cross-widget collision avoidance.
attributes	Record<string, unknown>	—	Initial host attributes, copied into custom.* at init time.
onChannelChange	(next, prev) => void	—	Called whenever the active channel changes (including to null).
pushToTalkKey	string	—	Hotkey (KeyboardEvent.key) for push-to-talk audio capture while open.

Note

Most projects only ever need projectKey. Visual options like mascot, shape, anchor, size, and offsets are also configurable per project in the dashboard’s Widget tab, and the loader bakes those in — so you usually don’t set them in code.