Demo und Anleitung

BotBucket Chatbot-iFrame integrieren

Für die lokale Entwicklung lädt diese Demo das Chat-Frontend unter window.location.origin. Mit ?id=IHRE-BOT-ID&debugFormPanel=1 werden nur technische Panel-Metadaten in der Browserkonsole angezeigt. &remoteIframe=1 lädt testweise den Stand auf int.botbucket.de. Der produktive Einbaucode unten behält die externe BotBucket-Adresse.

Auf dieser Seite sehen Sie unten rechts einen eingeblendeten Chatbot. Genau so können Sie Ihren eigenen BotBucket-Chatbot auf Ihrer Webseite einbinden. Unten finden Sie die vollständige Installations-Anleitung inklusive kopierbarem Beispielcode.

Hinweis: In dieser Demo wird als Bot-ID die UUID c6955997-a589-4423-94d4-96f7cb6579c4 verwendet. Diese Bot-ID erhalten Sie von BotBucket und ersetzen sie in Ihrem Code durch Ihre eigene.

1. Script-Tag im <head> einfügen

Einbindung: Fügen Sie folgenden Script-Tag innerhalb des <head>-Bereichs Ihrer Webseite ein:

<script
    src="https://int.botbucket.de/js/botbucket-chatbot-integration.js"
    defer
    data-closedSizeWidth="250px"
    data-closedSizeHeight="60px"
    data-openSizeWidth="min(500px, 100%)"
    data-openSizeHeight="min(800px, 80%)"
    data-iFrameElementId="helperbot-iframe"
    data-iFrameContainerElementId="helperbot-container"
    data-autoSizeClosedBot="true"
    data-autoSizeOpenBot="true"
></script>

Parameter des Script-Tags (data-Attribute):

Attribut	Beispielwert	Bedeutung
`data-closedSizeWidth`	`250px`	Breite des Chatbot-Containers, wenn der Bot geschlossen ist (z. B. nur Button/Badge sichtbar).
`data-closedSizeHeight`	`60px`	Höhe des Chatbot-Containers im geschlossenen Zustand.
`data-openSizeWidth`	`min(500px, 100%)`	Konfigurierte Mindestbreite des geöffneten Chats. Bei aktiver automatischer Anpassung werden 510 px für den Chat bzw. 970 px für Chat und Formular angefordert. Gültige CSS-Werte sind beispielsweise `400px`, `80%` oder `min(500px, 100%)`.
`data-openSizeHeight`	`min(800px, 80%)`	Höhe des Chatbot-Containers im geöffneten Zustand, ebenfalls als CSS-Wert.
`data-iFrameElementId`	`helperbot-iframe`	ID des iFrame-Elements, das den Chatbot enthält. Diese ID muss mit dem `id`-Attribut Ihres iFrames übereinstimmen.
`data-iFrameContainerElementId`	`helperbot-container`	ID des umgebenden Containers, dessen Größe beim Öffnen/Schließen des Bots dynamisch angepasst wird.
`data-autoSizeClosedBot`	`true` oder `false`	Steuert, ob der geschlossene Zustand automatisch anhand von Informationen aus dem iFrame angepasst wird. Typischer Wert: `true`.
`data-autoSizeOpenBot`	`true`	Erweitert den geöffneten Chat automatisch auf die vom iFrame gewünschte Breite (mit Formularbereich bis 970 px); begrenzt auf den sichtbaren Bildschirm. Mit `false` bleibt die fest eingestellte Overlay-Größe maßgeblich.

Alle Breiten- und Höhenangaben sind reguläre CSS-Werte. Sie können diese an das Design Ihrer Webseite anpassen. Bei einem aktiven Formular öffnet die neue Chatbot-Version eine zweite Spalte links; die Host-Seite vergrößert dafür den Container automatisch nach links.

2. Container-DIV und iFrame auf der Seite platzieren

Einbindung: Fügen Sie im <body> Ihrer Seite den Container und das iFrame ein. Üblicherweise wird der Chatbot unten rechts positioniert:

<div id="helperbot-container"
     style="position: fixed; right: 10px; bottom: 40px; z-index: 1000; width: 250px; height: 60px; max-width: calc(100vw - 16px);">
    <iframe
        id="helperbot-iframe"
        title="HelperBot"
        src="https://int.botbucket.de/bot/IHRE-BOT-ID/chat/iframe/undecorated"
        style="border-width: 0px; width: 100%; height: 100%; color-scheme: auto;"
        allowTransparency
        allow="microphone; autoplay"
    ></iframe>
</div>

Erläuterungen:

IHRE-BOT-ID wird durch Ihre individuelle Bot-ID ersetzt, z. B. c6955997-a589-4423-94d4-96f7cb6579c4.
position: fixed; right: 10px; bottom: 40px; sorgt dafür, dass der Bot immer unten rechts im Fenster sichtbar bleibt.
Die anfängliche Breite und Höhe des Containers (z. B. width: 250px; height: 60px;) werden vom Integration-Skript beim Öffnen/Schließen überschrieben.
Barrierefreiheit: Die Tab-Reihenfolge der Tastaturbedienung folgt der Reihenfolge im HTML-Code, nicht der Position auf dem Bildschirm. Ein position: fixed-Container am Ende des <body> ist daher auch erst als letztes Element per Tab erreichbar. Platzieren Sie Container und iFrame deshalb weiter vorne im Code, z. B. direkt nach der Hauptnavigation, damit Tastatur-Nutzende den Chatbot ohne langes Durchtabben erreichen. Setzen Sie auf dem iFrame kein tabindex="-1".

3. Zusammenfassung der Integrationsschritte

Script-Tag mit den gewünschten data--Parametern in den <head> einfügen.
Container-DIV mit fester Position (z. B. unten rechts) in den <body> einfügen.
iFrame mit Ihrer Bot-ID innerhalb des Containers platzieren.

Sobald diese Schritte umgesetzt sind, kümmert sich die Datei botbucket-chatbot-integration.js darum, die Größe des Containers passend zu öffnen und zu schließen. Der Chatbot kann dann direkt auf Ihrer Webseite genutzt werden.