@skippr/live-agent-sdk

Embed an autonomous product specialist that sees, speaks, and acts in real time — handling demos, onboarding, training, and support inside your app with a single React component or script tag.

Key Features

• Real-time voice — two-way audio with live transcription
• Capture modes — screenshare (user shares screen) or auto (DOM capture)
• Agent controls — opt-in capabilities like element highlighting (auto mode only)
• Chat + transcript — text messaging with voice transcripts merged into one thread
• Session agenda — structured phases with progress tracking
• Flexible auth — email OTP (direct auth) or backend-signed JWT (secret mode)
• Drop-in integration — one React component or script tag, no WebRTC code needed
• Host-safe styles — prefixed CSS that won't conflict with your app

Prerequisites

You need an agentId and appKey from the Skippr Platform.

1. Sign up at specialist.skippr.ai
2. Create an agent and copy the agentId from the agent details page
3. Create an App Key in Settings and copy the appKey — one App Key works for all your agents

Installation

React

npm install @skippr/live-agent-sdk

Script Tag

No install needed. Add this to any webpage:

<script src="https://unpkg.com/@skippr/live-agent-sdk/dist/skippr-sdk.js"></script>
<script>
  Skippr.initialize({
    agentId: 'your_agent_id',
    appKey: 'pk_live_your_key',
  });
</script>

Quick Start

React

import { LiveAgent } from '@skippr/live-agent-sdk';
import '@skippr/live-agent-sdk/styles';

function App() {
  return (
    <LiveAgent
      agentId="your_agent_id"
      appKey="pk_live_your_key"
    />
  );
}

Script Tag

<script src="https://unpkg.com/@skippr/live-agent-sdk/dist/skippr-sdk.js"></script>
<script>
  Skippr.initialize({
    agentId: 'your_agent_id',
    appKey: 'pk_live_your_key',
  });
</script>

Authentication

The SDK supports two identity modes, configured per App Key in the Skippr dashboard.

Direct Auth (default)

Users log in via email OTP inside the widget. No backend integration needed. The SDK handles the full OTP flow: email input, code verification, and token persistence automatically.

React:

<LiveAgent agentId="your_agent_id" appKey="pk_live_your_key" />

Script tag:

Skippr.initialize({
  agentId: 'your_agent_id',
  appKey: 'pk_live_your_key',
});

Secret Mode

Your backend signs a JWT with the App Key's identity secret and passes it as userToken. The SDK exchanges it for a bearer token server-side and skips the login form entirely.

Step 1: Generate a signed JWT on your backend

The JWT must be signed with HS256 using the identity secret you received when creating the App Key.

| Claim | Type | Required | Description | |-------|------|----------|-------------| | sub | string | Yes | Unique user identifier in your system | | name | string | No | User's display name | | email | string | No | User's email address | | exp | number | Recommended | Expiration timestamp (Unix seconds) |

Node.js example:

import jwt from 'jsonwebtoken';

const userToken = jwt.sign(
  {
    sub: user.id,
    name: user.name,
    email: user.email,
  },
  process.env.SKIPPR_IDENTITY_SECRET,
  { algorithm: 'HS256', expiresIn: '1h' },
);

Step 2: Pass the token to the SDK

React:

<LiveAgent
  agentId="your_agent_id"
  appKey="pk_live_your_key"
  userToken={userToken}
/>

Script tag:

Skippr.initialize({
  agentId: 'your_agent_id',
  appKey: 'pk_live_your_key',
  userToken: 'eyJhbGciOiJIUzI1NiIs...',
});

Custom Components

Any component rendered inside <LiveAgent> can use the useLiveAgent hook to access session state and controls:

import { LiveAgent, useLiveAgent } from '@skippr/live-agent-sdk';

function ConnectionStatus() {
  const { isConnected } = useLiveAgent();

  if (isConnected) return <p>Agent connected</p>;
  return <p>Agent disconnected</p>;
}

function App() {
  return (
    <LiveAgent agentId="your_agent_id" appKey="pk_live_your_key">
      <ConnectionStatus />
    </LiveAgent>
  );
}

API Reference

<LiveAgent>

Self-contained widget component. Renders a floating button that opens a sidebar panel for real-time agent interaction.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | agentId | string | required | Agent ID from the Skippr dashboard | | appKey | string | required | Publishable App Key from the Skippr dashboard | | userToken | string | — | Signed JWT for secret mode identity verification | | position | 'left' \| 'right' | 'right' | Side of the screen for the widget | | variant | 'floating' \| 'sidebar' | 'floating' | Widget display mode | | minimizable | boolean | true | Whether the widget can be minimized | | defaultOpen | boolean | false | Whether the panel starts open | | welcomeMessage | string | — | Message shown on the minimized bubble | | startSessionLabel | string | 'Talk to Skippr' | Label for the start-session button | | autoFocusChat | boolean | true | Whether the chat input auto-focuses when opened | | captureMode | 'screenshare' \| 'auto' | 'screenshare' | How the agent sees the page - 'screenshare' prompts the user to share, 'auto' uses DOM capture (no permission prompt) | | agentControls | { highlight?: boolean } | — | Opt-in agent capabilities (e.g. element highlighting). Requires captureMode: 'auto'. | | showAgentStateBanner | boolean | true | Whether to show the top-pinned status banner (talking / thinking / listening / observing) while connected |

useLiveAgent()

Hook for accessing session state and panel controls. Must be called within <LiveAgent>.

State

| Field | Type | Description | |-------|------|-------------| | isConnected | boolean | Whether the agent is connected | | isStarting | boolean | Whether a session is being created | | isPanelOpen | boolean | Whether the panel is currently open | | isMinimized | boolean | Whether the widget is minimized | | isAuthenticated | boolean | Whether the user is authenticated | | variant | 'floating' \| 'sidebar' | Current widget display mode | | position | 'left' \| 'right' | Current widget position | | error | string | Error message, if any |

Methods

| Method | Type | Description | |--------|------|-------------| | startSession | () => Promise<void> | Start a new agent session | | disconnect | () => Promise<void> | End the current session | | openPanel | () => void | Open the panel | | closePanel | () => void | Close the panel | | togglePanel | () => void | Toggle the panel open/closed | | expandPanel | () => void | Expand from minimized state | | minimizePanel | () => void | Minimize the widget | | setPosition | (position: 'left' \| 'right') => void | Change widget position |

Additional Hooks

All hooks must be called within <LiveAgent>.

| Hook | Returns | Description | |------|---------|-------------| | useMediaControls() | { isMuted, isScreenSharing, toggleMute, toggleScreenShare } | Mic and screen share state and toggles | | useAgentVoiceState() | { state, isSpeaking, isListening } | Agent voice activity state — state is the full agent state ('listening' \| 'thinking' \| 'speaking' \| ...) | | useIsLocalSpeaking() | boolean | Whether the local user is currently speaking | | useElapsedSeconds(isRunning) | number | Drift-safe elapsed seconds since the flag flipped to true |

Utilities

| Export | Signature | Description | |--------|-----------|-------------| | formatTime | (seconds: number) => string | Format seconds as mm:ss |

Global API (Script Tag)

Available on window.Skippr when using the script tag bundle.

| Method | Description | |--------|-------------| | Skippr.initialize(config) | Mount the widget. Accepts agentId, appKey, userToken, position, variant, minimizable, captureMode, agentControls. | | Skippr.logout() | Clear stored auth token and show the login form (direct auth mode) | | Skippr.destroy() | Remove the widget from the page and clear auth tokens |

Support

For questions, technical support, or feedback:

• Email: [email protected]
• Website: https://skippr.ai

© 2026 Skippr