Website-Widgets
Binden Sie Ihren Voice Agent auf jeder beliebigen Website ein, damit Besucher direkt aus dem Browser ein Sprachgespräch starten können. Der Widgets-Tab liefert Einbettungs-Codes, Anpassungsoptionen und Einstellungen zur Domain-Sicherheit.
Das Callback Widget funktioniert grundsätzlich anders als die Widgets auf dieser Seite — anstatt einen Sprachanruf im Browser zu starten, sammelt es die Telefonnummer des Besuchers, und Ihr Agent ruft zurück. Siehe die eigene Seite Callback Widget.
Widget-Typen
Hanc.AI bietet vier In-Browser-Widget-Typen sowie ein separates Callback Widget für Telefon-Rückrufe:
| Widget | Tag-Name | Beschreibung | Am besten geeignet für |
|---|---|---|---|
| Floating Widget | hanc-ai-floating-call | Kugelförmiger Button, der über Ihrer Seite schwebt | Dauerhaft sichtbarer Call-to-Action |
| Pill Widget | hanc-ai-pill-call | Kompakter, pillenförmiger Button, inline im Inhalt platziert | Minimaler Platzbedarf innerhalb eines bestehenden Layouts |
| Pill Floating Widget | hanc-ai-pill-float-call | Gleiche kompakte Pillenform wie Pill, schwebt aber wie das Floating-Widget mit der Seite mit | Wenn Sie eine Pillen-Ästhetik möchten, die dem Besucher beim Scrollen folgt |
| Inline Widget | hanc-ai-inline-call | Vollformatiger Anruf-Button, fest im Seiteninhalt eingebettet | Eigene „Sprechen Sie mit uns"-Abschnitte |
| Callback Widget | hanc-ai-callback | Telefonnummern-Formular; der Agent ruft den Besucher zurück | Lead-Generierungs- und High-Intent-Landingpages — siehe Callback Widget |
Allgemeine Attribute
Alle Widget-Typen unterstützen diese Kern-Attribute:
| Attribut | Pflicht | Beschreibung | Standard |
|---|---|---|---|
agent-id | Ja | Eindeutige Kennung Ihres Agenten | — |
voice-service-url | Nein | Voice-Service-URL überschreiben | Automatisch erkannt |
api-base-url | Nein | API-Basis-URL überschreiben | Automatisch erkannt |
Darstellungs-Attribute
| Attribut | Beschreibung | Werte | Standard |
|---|---|---|---|
position | Position des Widgets auf der Seite | bottom-right, bottom-left, top-right, top-left, static | bottom-right |
size | Widget-Größe in Pixel | Zahl | 120 |
theme | Name des Farbthemas | Siehe Farbthemen | default |
Button-Text-Attribute
| Attribut | Beschreibung | Standard |
|---|---|---|
button-start-text | Text auf dem inaktiven Button | "Call" |
button-connecting-text | Text während des Verbindungsaufbaus | "Connecting..." |
button-end-text | Text während eines aktiven Anrufs | — |
Terms-Attribute
| Attribut | Beschreibung | Standard |
|---|---|---|
terms-enabled | Einwilligungsdialog vor dem Anruf aktivieren | false |
terms-content | Einwilligungstext im Markdown-Format | "" |
terms-url | Link zu Ihren Allgemeinen Geschäftsbedingungen | "https://hanc.ai/terms" |
privacy-url | Link zu Ihrer Datenschutzerklärung | "https://hanc.ai/privacy" |
Terms-Attribute am HTML-Element werden von den über die API geladenen Widget-Einstellungen des Agenten überschrieben, es sei denn, skip-fetch ist auf true gesetzt.
Sound-Attribute
| Attribut | Beschreibung | Standard |
|---|---|---|
sound-enabled | Anrufstart-/Anrufende-Sounds aktivieren | true |
sound-volume | Lautstärke der Sound-Effekte | 0.25 |
sound-preset | Sound-Preset-Bezeichner | "1" |
Farbthemen
Passen Sie das Erscheinungsbild des Widgets mit 11 integrierten Farbthemen an:
| Theme | Wert |
|---|---|
| Default | default |
| Purple | purple |
| Blue | blue |
| Cyan | cyan |
| Emerald | emerald |
| Amber | amber |
| Tangerine | tangerine |
| Rose | rose |
| Ember | ember |
| Black | black |
| White | white |
Jedes Theme hat eine helle und eine dunkle Variante. Setzen Sie das Theme über das theme-Attribut im Einbettungs-Code oder in den Widget-Einstellungen des Agenten.
Einbettungs-Beispiele
Floating Widget
<hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Floating Widget mit Theme und Position
<hanc-ai-floating-call
agent-id="YOUR_AGENT_ID"
theme="emerald"
position="bottom-left"
size="140"
></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Pill Widget
<hanc-ai-pill-call agent-id="YOUR_AGENT_ID"></hanc-ai-pill-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Inline Widget
<hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Die obige Skript-URL lädt stets die neueste veröffentlichte Widget-Version — Ihre Website übernimmt Verbesserungen automatisch. Wenn Sie auf eine geprüfte Version festlegen möchten, pinnen Sie diese explizit mit https://unpkg.com/hanc-webrtc-widgets@1.4.0 (mit der gewünschten Version). Ohne Versionsangabe gilt standardmäßig das Tag @latest.
Widget-Events
Widgets senden Events, die Sie in JavaScript abhören können:
| Event | Beschreibung |
|---|---|
status-changed | Wird ausgelöst, wenn sich der Anrufstatus ändert |
connecting | Anruf wird aufgebaut |
connected | Anruf ist aktiv |
idle | Kein aktiver Anruf |
error | Ein Fehler ist aufgetreten |
audio-track | Audio-Track der Gegenseite empfangen (für Visualisierung) |
local-audio-track | Lokaler Mikrofon-Audio-Track (für Visualisierung) |
microphone-enabled | Mikrofon wurde aktiviert |
microphone-disabled | Mikrofon wurde deaktiviert |
call-start | Wird ausgelöst, wenn ein Anruf erfolgreich startet |
call-end | Wird ausgelöst, wenn der Anruf endet |
Beispiel: Auf Events lauschen
const widget = document.querySelector('hanc-ai-floating-call');
widget.addEventListener('call-start', () => {
console.log('Call started');
});
widget.addEventListener('call-end', () => {
console.log('Call ended');
});
Technische Voraussetzungen
Widgets erfordern, dass der Browser des Besuchers Folgendes unterstützt:
- WebGL 2.0 — fürs Rendering
- Web Audio API — für die Audioverarbeitung
- WebRTC — für die Echtzeit-Sprachkommunikation
Alle modernen Browser (Chrome, Firefox, Safari, Edge) unterstützen diese Technologien.
Domain-Beschränkungen
Steuern Sie, welche Websites Ihr Agent-Widget einbetten dürfen.
Immer erlaubte Domains
Die folgenden Domains sind unabhängig von der Konfiguration immer erlaubt:
hanc.ai(und Subdomains)hanc.me(und Subdomains)localhost
Alle Domains erlauben
Standardmäßig kann Ihr Widget auf jeder Website eingebettet werden. Schalten Sie „Allow all domains" in den Widget-Einstellungen aus, um das einzuschränken.
Auf bestimmte Domains beschränken
Wenn eingeschränkt, fügen Sie jede erlaubte Domain einzeln hinzu:
- Domain-Namen ohne
https://eintragen (z. B.example.com) - Subdomains benötigen eigene Einträge (z. B.
www.example.com,shop.example.com) - Ports können angegeben werden (z. B.
localhost:3000) - Maximal 50 Domains können freigegeben werden
Beschränken Sie Widgets bei Produktiv-Agenten auf Ihre eigenen Domains, um unbefugte Einbettungen zu verhindern.
Allgemeine Geschäftsbedingungen
Aktivieren Sie einen Einwilligungsdialog, bevor Anrufer ein Gespräch beginnen können.
Konfiguration
| Einstellung | Beschreibung |
|---|---|
| Enable Terms | AGB-Dialog ein-/ausschalten |
| Terms Content | Einwilligungstext im Markdown-Format, der Nutzern angezeigt wird (max. 5.000 Zeichen) |
| Terms URL | Link zur vollständigen AGB-Seite |
| Privacy URL | Link zu Ihrer Datenschutzerklärung |
Wenn aktiviert:
- Nutzer sehen vor Anrufbeginn einen Einwilligungsdialog
- Sie müssen auf „Zustimmen" klicken, um fortzufahren
- Die Einwilligung wird lokal im Browser gespeichert
- Die Schaltfläche Reset Consent löscht die gespeicherte Einwilligung für Testzwecke
Formatierung des Inhalts
Der AGB-Inhalt unterstützt Markdown-Formatierung:
####für Überschriften verwenden**fett**für Hervorhebungen- Zeilenumbrüche für bessere Lesbarkeit
Verwandt
- Callback Widget — Telefon-Rückrufe für Besucher, die lieber nicht im Browser sprechen
- Voice Agents Übersicht
- Einstellungen — Agent-Einstellungen inklusive Widget-Konfiguration
- Integrationen — API-Keys und Telefonnummern-Setup