Core concepts

Widget.

The Campfire messenger is a single async script. It renders a launcher, manages conversation state for the visitor, and speaks to Campfire over a signed channel. No build step required.

Install

Paste the snippet into any page that should show the messenger. Replace YOUR_ORG_ID with your workspace UUID. The script is async; it does not block your first paint.

index.htmlhtml

<script
  async
  src="https://campfire.is/campfire.js"
  data-widget-id="YOUR_ORG_ID"
  data-position="bottom-right"
  data-color="hsl(142 71% 45%)"
  data-theme="auto"
></script>

If you need runtime control, load the same script withoutdata-widget-id and initialize the widget yourself after the script has loaded.

index.htmlhtml

<script async src="https://campfire.is/campfire.js"></script>
<script>
  window.Campfire.init({
    widgetId: 'YOUR_ORG_ID',
    position: 'bottom-right',
    primaryColor: 'hsl(142 71% 45%)',
    theme: 'auto',
  });
</script>

Configuration

Core options can be set as data-* attributes on the script tag. Advanced options and callbacks are available through window.Campfire.init(...).

Option	Type	Default	Notes
`widgetId / data-widget-id`	string	required	Your organization UUID.
`apiKey / data-api-key`	string	null	Optional. Only set when scoping the messenger to a specific integration.
`baseUrl / data-base-url`	string	auto-detected	Override the widget host for local, staging, or regional deployments.
`position / data-position`	"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"	"bottom-right"	Launcher and panel corner.
`offset / data-offset-x/y`	{ x: number; y: number }	{ x: 20, y: 20 }	Distance from the selected viewport edges.
`zIndex / data-z-index`	number	2147483000	Stacking order, clamped to a safe browser range.
`primaryColor / data-color`	string (CSS color)	hsl(217 91% 60%)	Accent used for the launcher and forwarded into the iframe runtime.
`brandProfile / data-brand-profile`	object	null	JSON brand payload forwarded into the iframe runtime.
`showLauncher / data-launcher`	boolean	true	Set data-launcher="false" for API-only or custom-launcher installs.
`customLauncherSelector / data-custom-launcher-selector`	string	null	CSS selector for a site-owned launcher element.
`autoOpen / data-auto-open`	boolean	false	Open the widget as soon as the iframe is ready.
`theme / data-theme`	"auto" \| "light" \| "dark"	auto	Theme hint forwarded into the iframe runtime.
`size / data-size`	"small" \| "medium" \| "large"	"medium"	Internal widget density hint forwarded into the iframe runtime.
`companyName / data-company-name`	string	workspace name	Override the brand label shown in the widget.
`welcomeMessage / data-welcome-message`	string	workspace default	First message shown to a new visitor.
`locale / data-locale`	string	browser locale	Preferred locale hint for the iframe runtime.
`visibilityRules`	object	null	Programmatic-only rules for URL and device targeting.

Runtime API

Once loaded, the messenger exposes window.Campfire. Use it to open or close the panel programmatically, update config, identify a visitor, or tear the widget down on logout.

browser consolejs

window.Campfire.open();
window.Campfire.close();
window.Campfire.toggle();

window.Campfire.update({
  primaryColor: 'hsl(243 75% 59%)',
  welcomeMessage: 'Need help choosing a plan?',
});

window.Campfire.identify({
  email: 'ada@example.com',
  name: 'Ada Lovelace',
  userId: 'user_123',
});

// Tear the widget out of the page entirely.
window.Campfire.shutdown();

Lifecycle hooks are passed during initialization:onReady, onOpen,onClose, and onUnreadCount.

Theming

The messenger ships with three theming knobs, in decreasing order of impact:

Primary color. Set primaryColor to any CSS color string. The loader uses it for the launcher and forwards it into the iframe runtime.
Size. The desktop shell is 420 × 600 px and becomes full-screen on narrow mobile viewports.size is forwarded to the iframe runtime for internal density.
Theme. auto is the default; it follows the visitor’s system preference. Set it explicitly when the host page is locked to a single mode.

Identify visitors

For authenticated surfaces you can attach visitor identity so the messenger recognises the same person across sessions and devices. Treat browser-provided identity as a display hint unless your backend also verifies it for privileged workflows. Full walkthrough — coming soon.