Package Exports
- @hostwebhook/voice-widget
- @hostwebhook/voice-widget/react
Readme
@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-widgetThe 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,signedUrlProviderimperative 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