polymorph-sdk

Embeddable voice AI widget for your website.

Installation

npm install polymorph-sdk

Requires react and react-dom as peer dependencies (^18.0.0 || ^19.0.0).

Usage

import { PolymorphWidget } from "polymorph-sdk";

function App() {
  return (
    <PolymorphWidget
      apiBaseUrl="https://api.polymorph.dev"
      apiKey="pm_live_your_api_key_here"
      branding={{
        title: "Need help?",
        subtitle: "Chat with us",
        primaryColor: "#171717",
      }}
    />
  );
}

Configuration

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiBaseUrl | string | Yes | Your Polymorph API base URL | | apiKey | string | Yes | API key from Settings > API Keys | | agentName | string | No | LiveKit agent name to dispatch (default: "custom-voice-agent") | | metadata | Record<string, string> | No | Custom metadata passed to the agent | | branding | WidgetBranding | No | Customize widget appearance | | position | "bottom-right" \| "bottom-left" | No | Widget position (default: "bottom-right") | | enableVoice | boolean | No | Enable voice calls (default: true) | | fetchOptions | RequestInit | No | Extra options passed to fetch |

Branding

interface WidgetBranding {
  primaryColor?: string;  // FAB and accent color (default: "#171717")
  title?: string;         // Panel header title (default: "Hi there")
  subtitle?: string;      // Panel subheader
  greeting?: string;      // Initial message before agent connects
}

Hooks

For custom UIs, use the session hook directly:

import { usePolymorphSession } from "polymorph-sdk";

function CustomWidget() {
  const session = usePolymorphSession({
    apiBaseUrl: "https://api.polymorph.dev",
    apiKey: "pm_live_...",
  });

  return (
    <button onClick={session.connect}>
      {session.status === "idle" ? "Start" : session.status}
    </button>
  );
}