hanc-webrtc-widgets 2.8.5 → 2.8.6

package/README.md

@@ -8,10 +8,12 @@ You can use it in **plain HTML**, or integrate it with **React**, **Next.js**, *
 
 ## ✨ Features
 
-- 🎨 **Four Widget Types**: Inline, Floating, Pill, and Pill Floating layouts
+- 🎨 **Five Widget Types**: Inline, Floating, Pill, Pill Floating, and Callback (call-me-back)
 - 🌈 **Audio-Reactive 3D Orb**: WebGL-powered visualization responding to voice
 - 🎭 **Color Presets**: Dark and light theme color palettes
+- 🌍 **14 UI Languages**: Callback widget UI localised across en/de/fr/es/it/pt/pl/cs/hu/tr/kk/zh/ru/uk
 - 🔧 **Highly Customizable**: Full control over colors, glow, animations, and behavior
+- 🛡 **Terms & Privacy**: Optional consent modal before the call starts
 - 🚀 **Zero Dependencies**: Works standalone or with any framework
 - 📦 **Tiny Bundle**: Optimized for performance
 - ♿ **Accessible**: Built with Web Components standards
@@ -59,6 +61,12 @@ You can use it in **plain HTML**, or integrate it with **React**, **Next.js**, *
       position="bottom-right"
       button-start-text="Talk to AI"
     ></hanc-ai-pill-floating-call>
+
+    <!-- Callback Widget (visitor leaves number → AI calls them back) -->
+    <hanc-ai-callback
+      agent-id="YOUR_AGENT_ID"
+      theme="emerald"
+    ></hanc-ai-callback>
   </body>
 </html>
 ```
@@ -332,6 +340,16 @@ const handleCallEnd = () => {
 
 ## Components
 
+The library ships five custom elements:
+
+- [`<hanc-ai-inline-call>`](#hanc-ai-inline-call) — large inline widget with the audio-reactive orb
+- [`<hanc-ai-floating-call>`](#hanc-ai-floating-call) — same widget, fixed-positioned in a viewport corner
+- [`<hanc-ai-pill-call>`](#hanc-ai-pill-call) — horizontal pill button with a small orb
+- [`<hanc-ai-pill-floating-call>`](#hanc-ai-pill-floating-call) — pill button fixed in a corner
+- [`<hanc-ai-callback>`](#hanc-ai-callback) — call-me-back form (no WebRTC; visitor leaves a number, agent calls them)
+
+The first four open a WebRTC call session in the visitor's browser. The fifth is a one-way "leave your number" form — the platform's outbound dispatcher calls the visitor from the agent's phone number.
+
 ### `<hanc-ai-inline-call>`
 
 An inline widget that embeds directly in your page content. Features a large, prominent orb visualization with button overlay.
@@ -354,7 +372,9 @@ The essentials to get started:
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `agent-id` **(required)** | string | - | Hanc AI agent ID |
-| `voice-service-url` | string | - | Optional custom voice service URL |
+| `api-base-url` | string | auto-detect | Override the manifest API host (auto: `api.hanc.me` for `*.hanc.me`/localhost, `api.hanc.ai` otherwise) |
+| `voice-service-url` | string | - | Optional custom LiveKit voice service URL |
+| `skip-fetch` | boolean | `false` | Skip the manifest fetch and rely on the `manifestOverride` JS property — used by the dashboard preview |
 | `button-start-text` | string | `"Start Call"` | Button text in idle state |
 | `button-connecting-text` | string | `"Connecting..."` | Button text when connecting |
 | `size` | number | `370` | Container size in pixels (responsive on small screens) |
@@ -373,6 +393,21 @@ The essentials to get started:
 | `audio-smoothing` | number | `0.9` | Audio smoothing (0.1 = slow, 1.0 = instant) |
 | `idle-morph-multiplier` | number | `0.25` | Morph strength in idle state |
 | `color-contrast` | number | `1.5` | Color pattern sharpness |
+| `terms-enabled` | boolean | `false` | Show terms & privacy consent modal before the call starts |
+| `terms-content` | string | - | Markdown content shown in the terms modal (when enabled) |
+| `terms-url` | string | - | Link to full terms; rendered inside the modal |
+| `privacy-url` | string | - | Link to the privacy policy; rendered inside the modal |
+| `sound-enabled` | boolean | `false` | Play call-start / call-end sound effects |
+| `sound-volume` | number | `0.5` | Sound effect volume (0-1) |
+| `sound-preset` | string | `"default"` | Sound preset name |
+
+#### JS-only Properties
+
+Properties that can only be set from JavaScript (no HTML attribute equivalent):
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `manifestOverride` | object | Provides a synthetic manifest in place of the network fetch. Pair with `skip-fetch="true"`. Used by the dashboard preview iframe; not typically needed in production embeds |
 
 #### Events
 
@@ -576,6 +611,50 @@ Same attributes as `<hanc-ai-pill-call>`, plus:
 
 ---
 
+### `<hanc-ai-callback>`
+
+A "call-me-back" widget. Visitors leave a phone number; the platform queues the request and the AI agent calls them within a few minutes. Unlike the other widgets, this one doesn't open a WebRTC session in the browser — it's a one-way ticket from the visitor's number to the agent's outbound line.
+
+#### Quick Start Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `agent-id` **(required)** | string | - | Your Hanc AI agent ID |
+| `theme` | string | `"default"` | Color theme — same palette as the call widgets |
+| `locale` | string | (from manifest) | UI language: `en`, `de`, `fr`, `es`, `it`, `pt`, `pl`, `cs`, `hu`, `tr`, `kk`, `zh`, `ru`, `uk` |
+
+#### All Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `agent-id` **(required)** | string | - | Hanc AI agent ID |
+| `api-base-url` | string | auto-detect | Override the API host (auto: `api.hanc.me` for `*.hanc.me`/localhost, `api.hanc.ai` otherwise) |
+| `theme` | string | `"default"` | Theme name — see Themes section |
+| `locale` | string | (manifest's `widget_locale`) | Per-instance UI language override. When set, wins over the agent's dashboard setting — useful for multi-language host sites that control language per page. Falls back to English if the value isn't one of the 14 bundled locales |
+| `skip-fetch` | boolean | `false` | Skip the manifest fetch and use the `manifestOverride` property instead (dashboard preview use case) |
+
+#### Language behaviour
+
+The widget UI (button labels, status screens, error messages) is localised across 14 languages. Resolution order:
+
+1. The `locale` attribute on the element (per-page override)
+2. The agent's `widget_settings.locale` saved in the dashboard, served on the manifest as `widget_locale`
+3. English fallback
+
+The widget bundles all 14 dictionaries inline (~11 kB gzipped extra) so language switches are instant — no extra network roundtrip.
+
+#### Example
+
+```html
+<!-- Default: language follows agent.widget_settings.locale from the dashboard -->
+<hanc-ai-callback agent-id="YOUR_AGENT_ID" theme="emerald"></hanc-ai-callback>
+
+<!-- Per-page override: force German regardless of dashboard setting -->
+<hanc-ai-callback agent-id="YOUR_AGENT_ID" locale="de"></hanc-ai-callback>
+```
+
+---
+
 ## Color Presets
 
 The library includes professional color presets optimized for dark and light backgrounds.