Serverless Embed

Overview

The standard widget embed gives you full control — you mint participant tokens on your server and pass them to the widget. The serverless embed removes that step entirely. You provide a deploymentId and Chatterfly handles everything: creating anonymous runs, issuing tokens, and connecting the WebSocket — all in a single client-side call.

This is ideal for public-facing use cases like surveys, lead qualification forms, onboarding flows, and support triage — anywhere you want a workflow live on a page without writing server code.

How it works

1. You create a deployment in the Chatterfly dashboard and enable survey_mode.
2. Copy the deployment ID (e.g. dep_abc123).
3. Drop the <ChatterflyWidget> component into your page with the deploymentId prop.
4. When the component mounts, it calls the public survey-start endpoint automatically. Chatterfly creates an anonymous run, mints a participant token, and the widget connects — all behind the scenes.
5. The user completes the workflow. No login, no token plumbing, no server-side code on your end.

Quick start

Install the widget package:

npm install @chatterfly/widget

Import styles and render the widget — that's it:

import "@chatterfly/widget/dist/style.css";
import { ChatterflyWidget } from "@chatterfly/widget";

export default function SurveyPage() {
  return (
    <ChatterflyWidget
      deploymentId="dep_abc123"
      apiBase="https://your-chatterfly.example.com"
      onCompleted={() => console.log("Survey complete!")}
    />
  );
}

Three lines of meaningful code. The widget handles the rest.

Chatterfly-hosted page

Need it even simpler? Every deployment with survey_mode enabled gets a hosted page at:

https://your-chatterfly.example.com/survey/<tenant-slug>/<survey-slug>

Share the link directly — no code needed. Chatterfly creates an anonymous run server-side when the page loads, renders the widget, and collects responses. You can customise the page slug and branding in the deployment settings.

This is the zero-infrastructure path: no npm install, no React, no hosting. Just a URL.

Self-hosted embed

If you want the widget on yourdomain but still don't want to run a backend, the deploymentId prop calls the public survey-start endpoint automatically:

POST /api/public/surveys/{deploymentId}/start
→ { "run_id": "run_xyz789", "participant_token": "eyJ..." }

The widget makes this call internally when you pass deploymentId instead of runId / participantToken. You never interact with the endpoint directly.

Static site / plain HTML

If your site isn't React-based, you can load the widget from a CDN and initialise it with a script tag:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@chatterfly/widget/dist/style.css">
<script type="module">
  import { mount } from "https://cdn.jsdelivr.net/npm/@chatterfly/widget/dist/mount.js";
  mount(document.getElementById("cf-root"), {
    deploymentId: "dep_abc123",
    apiBase: "https://your-chatterfly.example.com",
  });
</script>

<div id="cf-root"></div>

Configuration & props

When using the serverless embed, pass deploymentId instead of runId and participantToken:

Theming

Theming works identically to the full widget — override CSS custom properties on any ancestor:

.survey-wrapper {
  --cf-primary:  #5B4AE4;
  --cf-accent:   #F28B30;
  --cf-bg:       #fafafa;
  --cf-fg:       #0f172a;
  --cf-border:   #e2e8f0;
  --cf-radius:   12px;
}

Serverless vs. full widget

Start with the serverless embed to get up and running immediately. You can switch to the full widget embed later if you need authenticated participants, custom run input, or server-side control over when runs are created.