@hostwebhook/voice-widget

Framework-agnostic voice agent widget for HostWebhook. Renders a <hw-voice> Web Component (works in plain HTML, React, Vue, Svelte, Astro, etc.) plus an optional typed React wrapper at @hostwebhook/voice-widget/react.

The widget connects the visitor's browser directly to the configured voice provider (ElevenLabs in v0.x, Vapi/Retell coming) over WebRTC. HostWebhook provisions the agent + handles the agent's tool webhooks; the audio loop itself never passes through our infra. That's by design — sub-second latency stays solved by the provider, our value lives in the workflow + RAG + audit layer.

Install

npm install @hostwebhook/voice-widget

The provider SDK is loaded lazily from a CDN (esm.sh by default) the first time the user starts a call — no audio plumbing in your baseline bundle.

Quick start (HTML)

<script type="module" src="https://cdn.jsdelivr.net/npm/@hostwebhook/voice-widget/dist/index.mjs"></script>

<!-- Modal mode (default): floating launcher button + overlay -->
<hw-voice
  agent-id="agent_abc123"
  agent-name="Support agent"
  primary-color="#7c3aed">
</hw-voice>

<!-- Inline mode: panel rendered in container -->
<hw-voice mode="inline" agent-id="agent_abc123"></hw-voice>

Quick start (React)

import { HwVoice } from '@hostwebhook/voice-widget/react';

<HwVoice
  agentId="agent_abc123"
  agentName="Support agent"
  primaryColor="#7c3aed"
  mode="modal"
/>

Attributes / props

| Attribute | Prop | Description | |---|---|---| | agent-id | agentId | Provider-side agent id (direct mode) | | chat-id | chatId | HW chat-trigger id (signed mode, Phase 3) | | agent-name | agentName | Friendly name shown in the panel title | | mode | mode | modal (default) or inline | | primary-color | primaryColor | Hex accent — drives orb gradient + glow + buttons | | theme | theme | light / dark / auto | | api-base | apiBase | HW API URL override | | voice-provider | voiceProvider | elevenlabs (only one wired today) | | voice-sdk-url | voiceSdkUrl | CDN override for the provider SDK |

Imperative-only (set via JS, not HTML attributes): authProvider, authEndpoint.

Events

The element emits a single hw-voice event with a detail payload:

type HwVoiceEvent =
  | { type: 'mode'; mode: 'idle' | 'connecting' | 'listening' | 'speaking' | 'ended' }
  | { type: 'turn'; turn: { role: 'user' | 'agent'; text: string; final: boolean } }
  | { type: 'duration'; seconds: number }
  | { type: 'end'; reason: string }
  | { type: 'error'; error: Error };

Status

• ✅ v0.1 — minimal Web Component, ElevenLabs driver, public agents
• ✅ v0.2 — premium UI (animated orb, audio levels, transcript, mute, volume), modal + inline modes
• ✅ v0.3 — signed sessions via HW backend (/voice-sessions/start), dashboard auto-pin, signedUrlProvider imperative escape hatch
• ✅ v0.4 — Vapi + Retell drivers, discriminated VoiceSessionTicket, full provider parity
• ⏳ v1.0 — battle-tested in prod, docs polish
• ⏳ v0.3 — signed sessions via HW backend (/voice-sessions/start), dashboard auto-pin
• ⏳ v1.0 — Vapi + Retell drivers, full docs

License

MIT