Zum Hauptinhalt springen
DocumentationAPI ReferenceVideo Tutorials

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.

Sie suchen das Callback-Widget?

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:

WidgetTag-NameBeschreibungAm besten geeignet für
Floating Widgethanc-ai-floating-callKugelförmiger Button, der über Ihrer Seite schwebtDauerhaft sichtbarer Call-to-Action
Pill Widgethanc-ai-pill-callKompakter, pillenförmiger Button, inline im Inhalt platziertMinimaler Platzbedarf innerhalb eines bestehenden Layouts
Pill Floating Widgethanc-ai-pill-floating-callGleiche kompakte Pillenform wie Pill, schwebt aber wie das Floating-Widget mit der Seite mitWenn Sie eine Pillen-Ästhetik möchten, die dem Besucher beim Scrollen folgt
Inline Widgethanc-ai-inline-callVollformatiger Anruf-Button, fest im Seiteninhalt eingebettetEigene „Sprechen Sie mit uns"-Abschnitte
Callback Widgethanc-ai-callbackTelefonnummern-Formular; der Agent ruft den Besucher zurückLead-Generierungs- und High-Intent-Landingpages — siehe Callback Widget

Allgemeine Attribute​

Alle Widget-Typen unterstützen diese Kern-Attribute:

AttributPflichtBeschreibungStandard
agent-idJaEindeutige Kennung Ihres Agenten—
voice-service-urlNeinVoice-Service-URL überschreibenAutomatisch erkannt
api-base-urlNeinAPI-Basis-URL überschreibenAutomatisch erkannt

Darstellungs-Attribute​

AttributBeschreibungWerteStandard
positionPosition des Widgets auf der Seitebottom-right, bottom-left, top-right, top-left, staticbottom-right
sizeWidget-Größe in PixelZahl120
themeName des FarbthemasSiehe Farbthemendefault

Button-Text-Attribute​

AttributBeschreibungStandard
button-start-textText auf dem inaktiven Button"Call"
button-connecting-textText während des Verbindungsaufbaus"Connecting..."
button-end-textText während eines aktiven Anrufs—

Terms-Attribute​

AttributBeschreibungStandard
terms-enabledEinwilligungsdialog vor dem Anruf aktivierenfalse
terms-contentEinwilligungstext im Markdown-Format""
terms-urlLink zu Ihren Allgemeinen Geschäftsbedingungen"https://hanc.ai/terms"
privacy-urlLink zu Ihrer Datenschutzerklärung"https://hanc.ai/privacy"
info

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​

AttributBeschreibungStandard
sound-enabledAnrufstart-/Anrufende-Sounds aktivierentrue
sound-volumeLautstärke der Sound-Effekte0.25
sound-presetSound-Preset-Bezeichner"1"

Farbthemen​

Passen Sie das Erscheinungsbild des Widgets mit 11 integrierten Farbthemen an:

ThemeWert
Defaultdefault
Purplepurple
Blueblue
Cyancyan
Emeraldemerald
Amberamber
Tangerinetangerine
Roserose
Emberember
Blackblack
Whitewhite

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>
Eine Widget-Version festpinnen

Die obige Skript-URL lädt stets die neueste veröffentlichte Widget-Version — Ihre Website übernimmt Verbesserungen automatisch, und @latest gilt standardmäßig, wenn keine Version angegeben ist. Wenn Sie auf eine feste Version festlegen möchten, pinnen Sie diese explizit, indem Sie die gewünschte Version anhängen, z. B. https://unpkg.com/hanc-webrtc-widgets@X.Y.Z.

Widget-Events​

Widgets senden Events, die Sie in JavaScript abhören können:

EventBeschreibung
status-changedWird ausgelöst, wenn sich der Anrufstatus ändert
connectingAnruf wird aufgebaut
connectedAnruf ist aktiv
idleKein aktiver Anruf
errorEin Fehler ist aufgetreten
audio-trackAudio-Track der Gegenseite empfangen (für Visualisierung)
local-audio-trackLokaler Mikrofon-Audio-Track (für Visualisierung)
microphone-enabledMikrofon wurde aktiviert
microphone-disabledMikrofon wurde deaktiviert
call-startWird ausgelöst, wenn ein Anruf erfolgreich startet
call-endWird 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');
});

Den Agenten Seiten öffnen lassen​

Während eines Browser-Anrufs kann der Agent Ihre Website bitten, eine Seite zu öffnen – „lassen Sie mich Ihnen die Preise zeigen“ – und der Besucher sieht es, ohne das Gespräch zu unterbrechen.

Ihre Seite behält die Kontrolle. Der Agent schickt eine Anfrage, Ihr Code entscheidet, was sie bedeutet. Eine URL öffnen, einen Tab wechseln, zu einem Abschnitt scrollen und ein Akkordeon aufklappen – alles gültige Antworten.

Dafür braucht es drei Schritte, und keiner funktioniert für sich allein.

Schritt 1 – Sagen Sie dem Agenten, welche Seiten es gibt​

Der Agent kennt Ihre Seitenstruktur nicht. Er fragt immer nur nach einem Pfad, den Sie ihm gegeben haben – listen Sie sie im Prompt des Agenten oder in der Wissensdatenbank auf:

Seiten unserer Website:
/pricing — Tarife und Preise
/contact — Kontaktformular und Telefonnummer
/product/crm — das CRM

Ohne diesen Schritt hat der Agent nichts, wonach er fragen könnte, und versucht es gar nicht erst.

Schritt 2 – Die Anfrage auf Ihrer Seite behandeln​

Fügen Sie das einmal ein, irgendwo nach dem Widget-Skript. Das Event steigt durch die Seite auf, document ist also ein guter Ort:

<script>
document.addEventListener('agent-command', (event) => {
  const { type, payload } = event.detail;

  if (type === 'navigate') {
    // Single-Page-App: routen ohne Neuladen — der Anruf läuft weiter.
    router.push(payload.path);

    // Klassische Website: einen zweiten Tab öffnen, damit dieser (und der Anruf) bestehen bleibt.
    // window.open(payload.path, '_blank');

    event.preventDefault();   // ← sagt dem Agenten: erledigt
  }
});
</script>
Ein vollständiges Neuladen beendet den Anruf

Der Anruf lebt in dieser Seite. window.location.href = … entlädt das Dokument, und das Gespräch geht mit — der Besucher wird mitten im Satz getrennt. Routen Sie clientseitig, wenn Sie einen Router haben, sonst öffnen Sie die Seite in einem neuen Tab. Es gibt keine Wiederverbindung: ein Neuladen überlebt nichts.

preventDefault() ist nicht optional

Es ist die einzige Art zu sagen „ich habe es erledigt“. Ohne diese Zeile erfährt der Agent, dass die Seite keine Navigation unterstützt: Er versucht es für den Rest des Anrufs nicht mehr und beschreibt stattdessen, wo man klicken muss. In der Konsole erscheint nichts – die Seite wirkt einfach so, als hätte sie die Anfrage ignoriert, und genau das hat sie getan.

Schritt 3 – Ausprobieren​

Rufen Sie Ihren Agenten von der Website aus an und bitten Sie ihn um eine Seite. Zweierlei sollte passieren: Die Seite öffnet sich, und der Agent sagt so etwas wie „hier sind die Preise“ statt „Sie finden sie im Menü“.

Dem Agenten mit Daten antworten​

Manche Befehle sind Fragen statt Anweisungen. Sie kommen genauso an, beantwortet werden sie aber mit respond():

BefehlWonach der Agent fragtWomit Sie antworten
navigate„öffne diesen Pfad“mit nichts – preventDefault() genügt
page_context„was sieht der Besucher gerade?“was nützlich ist: Pfad, Titel, Produkt
cart_state„was liegt im Warenkorb?“Positionen, Summen, Währung
<script>
document.addEventListener('agent-command', (event) => {
  const { type, respond } = event.detail;

  if (type === 'page_context') {
    event.preventDefault();
    respond({ path: location.pathname, title: document.title });
  }
});
</script>

Nach preventDefault() haben Sie etwa eine Sekunde zum Antworten – ein await ist in Ordnung, ein langsamer API-Aufruf nicht. Antworten Sie mit dem, was Sie ohnehin schon haben.

Was der Agent verlangen darf und was nicht​

  • Nur Pfade auf Ihrer eigenen Website. Ein Pfad muss mit / beginnen. Alles, was Ihre Domain verlassen könnte – //evil.com, https://…, Backslashes – wird abgewiesen, bevor es Ihre Seite erreicht. Ein Agent kann Ihre Besucher nicht woanders hinschicken.
  • Nur Browser-Anrufe. Bei einem Telefonanruf gibt es keine Seite zu öffnen, dort existieren diese Befehle nicht.
  • Eine Absage genügt. Bestätigt Ihre Seite die erste Anfrage nicht, fragt der Agent für den Rest des Anrufs nicht mehr. Er versucht es nicht erneut und – wichtiger – er behauptet dem Besucher gegenüber nicht, etwas geöffnet zu haben.
Es passiert nichts?

Loggen Sie jeden Befehl, bevor Sie filtern: document.addEventListener('agent-command', e => console.log(e.detail)). Sehen Sie navigate in der Konsole, hat der Agent seinen Teil getan und es fehlt preventDefault() oder Ihr Handler. Sehen Sie gar nichts, wurde dem Agenten nie gesagt, dass es diesen Pfad gibt – zurück zu Schritt 1.

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
Sicherheit

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​

EinstellungBeschreibung
Enable TermsAGB-Dialog ein-/ausschalten
Terms ContentEinwilligungstext im Markdown-Format, der Nutzern angezeigt wird (max. 5.000 Zeichen)
Terms URLLink zur vollständigen AGB-Seite
Privacy URLLink 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​