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 choose Public access in the Deploy dialog (Deploy → Access → Public).
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/style.css";
import { ChatterflyWidget } from "@chatterfly/widget";

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

Three lines of meaningful code. The widget handles the rest. Prefer workflowId over deploymentId — it always targets the workflow's latest live deployment, so you never edit embed code when you redeploy. Use deploymentId only to pin a specific snapshot.

Chatterfly-hosted page

Need it even simpler? Every deployment deployed with Public access and a survey slug 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.

Application embed

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

POST /api/public/workflows/{workflowId}/start
→ { "run_id": "run_xyz789", "participant_token": "eyJ...", "deployment_id": "dep_abc123" }

The widget makes this call internally when you pass workflowId (or deploymentId to pin a snapshot) instead of runId / participantToken. It resolves to the latest live public deployment, so you never interact with the endpoint directly and never update the embed on redeploy.

Static site / plain HTML

If your site doesn't use a React build setup, load React and the widget from a CDN and initialise it with a module script:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@chatterfly/widget/dist/index.css">
<div id="cf-root"></div>

<script type="module">
  import React from "https://esm.sh/react";
  import { createRoot } from "https://esm.sh/react-dom/client";
  import { ChatterflyWidget } from "https://esm.sh/@chatterfly/widget";

  createRoot(document.getElementById("cf-root")).render(
    React.createElement(ChatterflyWidget, {
      workflowId: "wf_abc123",
      apiBase: "https://your-chatterfly.example.com",
    })
  );
</script>

Configuration & props

When using the serverless embed, pass workflowId (recommended) or 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.