Implement an experience

This page is the developer journey map for building a voice experience with @scenaro/sdk. It follows the same structure as Retell, Vapi, and ElevenLabs docs: install → connect → listen → handle tools → ship.

Already have a working quickstart? Use this page as a checklist and jump to the sections you need.

What you are building

Layer	Your responsibility	Provided by Scenaro
Scenario	Choose publication UUID	Cockpit authoring + agent
Session	Call `start()` / `end()`	Identify, JWT, Transport credentials
Transport	Usually nothing	SDK connects the session + data channel — see Transport
Tools	Implement frontend handlers	Agent calls tools via RPC
UI features	Registry + components	`FeatureProvider` or local runtime
Brand	CSS, layout, copy	—

Prerequisites

A published scenario UUID from Cockpit
Node.js 18+ and React 18+ (for the React path)
Microphone access in the browser (for voice mode)

Step 1 — Install

npm install @scenaro/sdk

pnpm add @scenaro/sdk

Current version: @scenaro/sdk@0.3.0

This is all you need for the embed path below. Only install livekit-client and @livekit/components-react if you reach Step 7.

Step 2 — Choose your integration path

React embed (recommended)

ScenaroProvider + useScenaroSession. Used by all Scenaro experience apps and platform-spa. Start here unless you have a strong reason not to.

Headless / non-React

ScenaroSession from @scenaro/sdk. Same lifecycle and events, no React bindings. See ScenaroSession reference.

Provider stack (React)

import { ScenaroProvider, FeatureProvider } from '@scenaro/sdk/react';

export function ScenaroLiveProviders({ children, registry }) {
  return (
    <ScenaroProvider apiUrl={process.env.NEXT_PUBLIC_API_URL!}>
      <FeatureProvider registry={registry}>
        {children}
      </FeatureProvider>
    </ScenaroProvider>
  );
}

FeatureProvider is optional — skip it if you only need session tools (see Tools and features).

Step 3 — Start a session

The SDK handles the full connect flow: identify visitor → start session → connect Transport → config handshake.

import { useScenaroSession } from '@scenaro/sdk/react';

const PUBLICATION_UUID = 'your-publication-uuid';

export function VoiceControls() {
  const {
    status,       // 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'ended'
    agentState,   // 'idle' | 'listening' | 'thinking' | 'speaking'
    start,
    end,
    sendText,
    setMicrophoneEnabled,
  } = useScenaroSession({
    scenario: PUBLICATION_UUID,
    language: 'en-US', // optional — omit to use scenario default
    onError: (e) => console.error(e.code),
  });

  return (
    <>
      <button onClick={() => start()} disabled={status === 'connecting'}>
        {status === 'connected' ? 'Connected' : 'Start'}
      </button>
      <button onClick={() => end()} disabled={status !== 'connected'}>
        End
      </button>
    </>
  );
}

Auth is two-hop: identifyUser then startSession. You never call these directly in a typical embed — start() runs both. See Authentication.

Step 4 — Listen to events

Like Retell’s call_started / Vapi’s call-start / ElevenLabs’ onConnect, Scenaro exposes session state through the hook and typed callbacks:

What you need	How
Connection state	`status`, `agentState`
Transcript / messages	`messages` array + `onMessage`
Session config	`config` (curated) or `rawConfig` (wire format)
Errors	`error` + `onError`
Session ended	`onSessionEnd`
Cross-component events	`useScenaroEvents()` event bus

const { messages, config } = useScenaroSession({
  scenario: PUBLICATION_UUID,
  onMessage: (m) => appendToUI(m),
  onSessionEnd: (info) => showSummary(info.reason),
});

See Events and listeners for the full event catalog.

Step 5 — Handle frontend tools

When the voice agent calls a tool configured for frontend execution, the SDK routes the RPC to your handler and returns the result to the agent. You have two integration patterns — pick one per tool:

Pattern	Best for	Doc
Session tools	Headless logic, no UI panel	`useScenaroSession({ tools })`
Feature tools	Tool opens a UI panel (search, cart…)	`FeatureProvider` registry

// Session tool — plain function, SDK handles RPC
useScenaroSession({
  scenario: PUBLICATION_UUID,
  tools: {
    search_products: async (args, context) => {
      return searchCatalog(args, { signal: context.signal });
    },
  },
});

Read Tools and features before wiring handlers — the two patterns use different handler signatures.

Step 6 — Build UI features (optional)

For rich experiences (product search, comparison, shopping list), register feature components:

Define handlers + a React component per feature type
Register in a Map<string, ToolRegistryEntry>
Mount FeatureProvider with that registry

See Feature registry and the custom feature recipe.

Most Scenaro experience apps keep a local FeatureManager instead of SDK FeatureProvider. Both patterns work on top of useScenaroSession. See Tools and features.

Step 7 — Advanced: Transport extensions (optional)

Most embeds never touch the underlying engine directly. When you need custom audio visualizers, avatars, or participant UI, use room from the hook — the current Transport implementation’s engine handle:

const { room } = useScenaroSession({ scenario: PUBLICATION_UUID });
// room: LiveKit Room | null (today) — use @livekit/components-react hooks

See Advanced: Transport extensions and Transport for the portable-vs-engine-extension distinction.

Step 8 — Ship to production

Before going live:

Env vars: NEXT_PUBLIC_API_URL (or equivalent) points to production API
Scenario published in Cockpit production environment
HTTPS + microphone permission UX
Error handling for IDENTIFY_FAILED, SESSION_START_FAILED, MIC_PERMISSION_DENIED
Session cleanup on page unload (end())

Full checklist: Production checklist.

Compare with other platforms

Theme	Retell	Vapi	ElevenLabs	Scenaro
Web SDK install	`retell-client-js-sdk`	`@vapi-ai/web`	`@elevenlabs/react`	`@scenaro/sdk/react`
Start call	`startCall({ accessToken })`	`start(assistantId)`	`startSession({ agentId })`	`start()` via `useScenaroSession`
Auth	Server mints token	Public key + assistant ID	Signed URL / token	Two-hop identify + session (automatic)
Events	`call_started`, `update`	`call-start`, `message`	`onConnect`, `onMessage`	`status`, `agentState`, `messages`
Client tools	—	`tool-calls` (one-way)	`clientTools`	Session tools + FeatureProvider (two-way RPC)
Transport	WebRTC audio	WebRTC	WebRTC / WebSocket	Abstracted (LiveKit today) — see Transport

Scenaro’s differentiator: scenario-driven features authored in Cockpit, with a typed protocol between agent and frontend carried over Transport.

​What you are building

​Prerequisites

​Step 1 — Install

​Step 2 — Choose your integration path

React embed (recommended)

Headless / non-React

​Provider stack (React)

​Step 3 — Start a session

​Step 4 — Listen to events

​Step 5 — Handle frontend tools

​Step 6 — Build UI features (optional)

​Step 7 — Advanced: Transport extensions (optional)

​Step 8 — Ship to production

​Recommended reading order

​Compare with other platforms

What you are building

Prerequisites

Step 1 — Install

Step 2 — Choose your integration path

Provider stack (React)

Step 3 — Start a session

Step 4 — Listen to events

Step 5 — Handle frontend tools

Step 6 — Build UI features (optional)

Step 7 — Advanced: Transport extensions (optional)

Step 8 — Ship to production

Recommended reading order

Compare with other platforms