KI auf Ihrer Website einbinden
Binden Sie Ihren KI-Agenten direkt auf Ihrer Website ein — als Text-Chat, Voice-Anruf im Browser, oder beides.
Überblick
Das Widget bietet zwei Modi:
| Modus | Beschreibung |
|---|---|
| Chat | Textbasierter Chat mit Markdown, Quick Replies und Dateiexport |
| Voice | Sprachanruf im Browser via WebRTC — wie ein Telefonat, aber ohne Telefon |
Standardmäßig sind beide Modi aktiv. Sie können in den Organisationseinstellungen festlegen, ob nur Chat, nur Voice oder beides verfügbar sein soll.
Voraussetzungen
- Ein veröffentlichter Agent (mindestens eine publizierte Version)
- Das Widget-Feature muss für Ihre Organisation aktiviert sein
- Die Agent-ID (finden Sie unter Agenten → Agent auswählen → Widget-Button)
Tipp: Wenn das Chat-Feature für einen Agenten aktiviert ist, erscheint im Kopf der Agenten-Seite (Edit-Modus) ein Widget-Button. Ein Klick darauf öffnet den Einbettungs-Code sowie die Konfiguration direkt für diesen Agenten — so erhalten Sie die richtige Agent-ID, ohne sie separat suchen zu müssen.
Einbindung per JS-Snippet
Fügen Sie folgenden Code vor dem schließenden </body>-Tag Ihrer Website ein:
<script
src="https://widget.dalvon.ai/v1/widget.js"
data-agent-id="IHRE_AGENT_ID"
async
></script>
Das Widget erscheint als schwebender Button unten rechts auf Ihrer Seite.
Erweiterte Konfiguration
Für mehr Kontrolle verwenden Sie die JavaScript-API:
<script src="https://widget.dalvon.ai/v1/widget.js" async></script>
<script>
window.TelAI = window.TelAI || { _q: [] };
TelAI.init({
agentId: "IHRE_AGENT_ID",
// Optionale UI-Sprache (Standard: Sprache des Agenten)
lang: "de",
// Optionale Kontaktdaten und dynamische Variablen
// Werden im Prompt als {{contact.first_name}} etc. verfügbar
variables: {
"contact.first_name": "Max",
"contact.last_name": "Müller",
"contact.email": "max@example.com",
"contact.company": "Firma GmbH",
"contact.customer_number": "K-12345",
// Eigene dynamische Variablen
"dynamic.abteilung": "Vertrieb",
"dynamic.vertragsnummer": "V-2024-001",
}
});
</script>
Programmatische Steuerung
TelAI.open(); // Widget öffnen
TelAI.close(); // Widget schließen
TelAI.reset(); // Session zurücksetzen (neues Gespräch)
Einbindung per iFrame
Falls das JS-Snippet nicht gewünscht ist, können Sie das Widget auch per iFrame einbetten:
<iframe
src="https://widget.dalvon.ai/chat/IHRE_AGENT_ID"
width="400"
height="600"
style="border: none; border-radius: 12px;"
allow="microphone"
></iframe>
Wichtig: Das
allow="microphone"-Attribut ist für den Voice-Modus erforderlich.
Verfügbare Variablen
Alle Variablen, die Sie über variables übergeben, stehen im Prompt des Agenten als Template-Variablen zur Verfügung. Folgende Prefixe werden unterstützt:
| Prefix | Beispiel | Beschreibung |
|---|---|---|
contact.* | contact.first_name | Kontaktdaten des Website-Besuchers |
dynamic.* | dynamic.vertragsnummer | Eigene dynamische Felder |
Kontakt-Felder
| Variable | Beschreibung |
|---|---|
contact.first_name | Vorname |
contact.last_name | Nachname |
contact.company | Firma |
contact.email | E-Mail-Adresse |
contact.phone | Telefonnummer |
contact.customer_number | Kundennummer |
contact.street | Straße |
contact.house_number | Hausnummer |
contact.postal_code | Postleitzahl |
contact.city | Stadt |
contact.country | Land |
Widget-Design anpassen
Das Erscheinungsbild des Widgets wird in den Organisationseinstellungen konfiguriert (unter Agenten → Widget → Design):
| Einstellung | Beschreibung |
|---|---|
| Primärfarbe | Farbakzent des Widgets (Hex, z.B. #0066FF) |
| Logo | Ihr Logo im Widget-Header |
| Avatar | Avatar-Bild in Chat-Nachrichten |
| Begrüßungstext | Text beim Öffnen des Widgets |
| Position | bottom-right oder bottom-left |
| Modi | chat, voice oder beides |
Erlaubte Domains
Unter Regeln können Sie eine Domain-Whitelist konfigurieren. Ist die Liste leer, kann das Widget auf jeder Domain eingebettet werden. Sobald Sie Domains eintragen, wird das Widget nur auf diesen Domains geladen:
example.com
*.example.com
shop.example.com
Chat-spezifische Einstellungen
Im Agent-Editor unter Allgemein können Sie über den Voice/Chat-Toggle separate Einstellungen für den Chat-Modus festlegen:
- Chat-Prompt: Eigener Prompt für den Chat-Modus (leer = Voice-Prompt wird automatisch angepasst)
- Chat-Begrüßung: Eigene Begrüßung für den Chat-Modus (leer = Voice-Begrüßung wird verwendet)
- Quick Replies: Vordefinierte Antwortvorschläge als klickbare Buttons
- Max. Nachrichten: Maximale Nachrichten pro Gespräch (Standard: 50)
Technische Details
Protokolle
| Modus | Protokoll | Endpoint |
|---|---|---|
| Chat | WebSocket | wss://calling-pipecat.dalvon.ai/widget/chat |
| Voice | WebRTC | https://calling-pipecat.dalvon.ai/widget/voice/offer |
Chat-WebSocket-Protokoll
→ {"type": "config", "agent_id": "...", "channel": "webchat", "variables": {...}}
← {"type": "ready", "chat_id": "...", "first_message": "...", "quick_replies": [...]}
→ {"type": "user_message", "content": "Hallo!"}
← {"type": "tool_status", "message": "Sucht nach Informationen..."}
← {"type": "agent_message", "content": "Guten Tag! Wie kann ich Ihnen helfen?"}
← {"type": "completed", "chat_id": "..."}
Voice-WebRTC-Flow
GET /widget/voice/ice— ICE-Server (STUN/TURN) abrufenRTCPeerConnectionerstellen mit ICE-ServernPOST /widget/voice/offermit SDP-Offer — erhält SDP-Answer zurück- Audio-Stream läuft bidirektional über WebRTC
POST /widget/voice/stop— Session beenden
Session-Persistenz
Chat-Sitzungen bleiben über Seitenwechsel erhalten (LocalStorage). Bei erneutem Öffnen des Widgets wird die vorherige Konversation fortgesetzt.
Fehlerbehebung
| Problem | Lösung |
|---|---|
| Widget erscheint nicht | Prüfen Sie, ob der Agent veröffentlicht ist und das Widget-Feature aktiviert ist |
| Voice funktioniert nicht | Stellen Sie sicher, dass allow="microphone" (iFrame) gesetzt ist bzw. der Browser Mikrofonzugriff erlaubt |
| ”Agent not found” Fehler | Überprüfen Sie die Agent-ID und ob eine publizierte Version existiert |
| Domain blockiert | Prüfen Sie die Domain-Whitelist in den Regeln |