Chatbot-Integration

Intro

Unternehmen wie Slack, Microsoft und Facebook haben dem Konzept des "Chatbots" reichlich Aufwind beschert. Zu welchem Grad die KI-Chatbots die Erwartungen erfüllen werden bleibt abzuwarten. Diese reichen von persönlichen Assistenten bis zu Customer-Service-Agenten – oder sogar Herrschern über die Menschheit.

Bei Userlike interessieren wir uns vor allem für Kundenservice. Und wir sind ziemlich sicher, dass in nächster Zeit kein KI-System an die Fähigkeiten des Mensch-zu-Mensch-Kontakts heranreichen wird. Trotzdem halten wir Service-Bots für nützlich. Aus diesem Grund möchten wir Ihnen zeigen, wie Sie ganz einfach Ihre eigenen Service-Bots erschaffen und sie über unsere Chat-Infrastruktur mit Ihrem Userlike-Account verbinden können.

Chat-ThemaBeschreibung
Chatbot-IntegrationWie Sie Ihren Chatbot in unsere Infrastruktur integrieren
Chatbot-HTTP-APIDetails des Chatbot-HTTP-API-Protokolls
Chat-CommandsChat-Commands, die Ihr Chatbot nutzen kann
Chatbot-Chat-ÜbersichtBeobachten Sie die Chat-Aktivitäten Ihres Chatbots
Chatbot-ProjekteIdeen für Ihr erstes Chatbot-Projekt
Beispiel-CodeBeispiel-Code für Chatbots

Chatbot-Integration

Wir nehmen an, dass Sie schon einen aktiven Chatbot (Framework) haben, den Sie jetzt mit Ihrer Userlike-Chat-Infrastruktur verbinden möchten. Wir gehen außerdem davon aus, dass Ihr Chatbot (Framework) per HTTP zu erreichen ist. Nun müssen Sie einfach einen "stellvertretenden" Bot-Operator in Ihrem Dashboard erstellen: stellen Sie sich diesen als den Gesandten (oder Botschafter) Ihres Chatbots in der Userlike-Chat-Infrastruktur vor.

Einen Bot-Operator zu erstellen ist genauso einfach, wie einen regulären Operator hinzuzufügen. Gehen Sie in Ihrem Dashboard auf "Config" und klicken Sie "Operatoren". Sie sehen eine Tabelle mit all Ihren bestehenden menschlichen Operatoren. Darunter, unter "Bots", ist eine (noch leere) Tabelle für Ihre Bot-Operatoren. Klicken Sie auf "Bot hinzufügen", um Ihren ersten Chatbot zu erstellen:

Jetzt können Sie Ihren neuen Bot-Operator konfigurieren:

Die Einstellungen für Vorname, Nachname und Operatorengruppe sind identisch zu denen eines regulären menschlichen Operators. Weiter unten finden Sie Erklärungen zu Chat-Endpunkten und den Bot-Verhaltensmodi.

HTTP-Chat-Endpunkte

Ihr Chatbot (Framework) kann bis zu drei HTTP-Endpunkte zum Abruf durch den Userlike-Chatserver bereitstellen. Während der Endpunkt "Chat-Nachricht" immer benötigt wird, können Sie die Endpunkte "Chat-Start" und "Chat-Ende" hinzufügen, falls sie bei Ihrem spezifischen Setup nützlich sind.

HTTP-EndpunktBeschreibung
Chat-Start-EndpunktWird vom Userlike-Chatserver gecallt, wenn ein Webvisitor einen neuen Chat mit Ihrem Bot startet. Ihre Antwort wird an den Webvisitor gesendet.
Chat-Nachricht-EndpunktWird vom Userlike-Chatserver bei jeder Nachricht gecallt, die der Webvisitor an Ihren Bot schickt. Ihre Antwort wird an den Webvisitor gesendet.
Chat-Ende-EndpunktWird vom Userlike-Chatserver gecallt, sobald die Chat-Session mit Ihrem Bot endet. Es wird keine Antwort erwartet.

Die HTTP-API (das erwartete Anfrage/Antwort-Protokoll) dieser Endpunkte erklären wir weiter unten im Detail.

Bot-Verhaltensmodi

Sie können Ihren Chatbot in vier verschiedenen Verhaltensmodi einsetzen. Diese Modi entscheiden, in welchen Situationen Ihre Webvisitor mit Ihrem Chatbot verbunden werden und wann seine menschlichen Kollegen die bevorzugte Wahl sind.

Bot-VerhaltensmodusBeschreibung
Service-ZeitDer Bot ist nur außerhalb der für das Widget festgelegten Service-Zeit online. Während der Service-Zeit gehen alle Chats an menschliche Operatoren.
FailoverDer Bot ist immer online, nimmt aber nur Chats an, wenn kein anderer Operator frei ist.
MenschlichDer Bot ist immer online und nimmt Chats genau wie ein menschlicher Operator entgegen.
FirewallDer Bot ist immer online und nimmt alle Chats an (z.B. um sie zu kategorisieren und weiterzuleiten).

Nachdem Sie Ihren neuen Chatbot konfiguriert und gespeichert haben, erscheint er in der Bot-Übersicht, direkt unter der Tabelle mit Ihren menschlichen Operatoren.

Von hier aus können Sie ihn wie jeden anderen Operator bearbeiten.

Falls Sie einen existierenden Chatbot bearbeiten, können Sie zusätzlich sein Profilbild ändern und bestimmen, wie viele Chats der Bot maximal gleichzeitig führen soll.

XMPP-Integration

Falls Sie sich noch per XMPP mit unserer Infrastruktur verbinden, finden Sie alle Einzelheiten in unserem Chatbot-XMPP-Tutorial. Beachten Sie, dass dieser Weg, Ihren Chatbot mit Userlike zu verbinden, mehr technisches Wissen erfordert.

Chatbot-HTTP-API

Zuerst geben wir Ihnen einen Überblick über Anfrage/Antwort-Werte für Ihre drei HTTP-Endpunkte. Weiter unten beschreiben wir das JSON-Austauschformat detaillierter und erklären, wie Ihr Chatbot(-Framework) es nutzen muss, um den Status bei jedem Chat mit Ihren Webvisitors zu halten.

Mit einer Ausnahme müssen alle Requests an Ihren und Antworten von Ihrem Chatbot (Framework) die HTTP-POST-Methode nutzen - nur die erste Request an den "Chat-Start-Endpunkt" wird per HTTP-GET-Methode (ohne Parameter) durchgeführt. Es ist möglich, dass wir in der Zukunft die POST-Methode auch für erste Requests nutzen werden, erlauben Sie Ihrem Endpunkt also am besten, beide Methoden zu akzeptieren.

HTTP-EndpunktBeschreibung
Chat-Start-EndpunktWird vom Userlike-Chatserver gecallt, wenn ein Webvisitor einen neuen Chat mit Ihrem Bot startet. Ihre Antwort wird an den Webvisitor gesendet.
Request-FormatGET - ohne Parameter
Antwort-FormatPOST - mit Body, der die JSON-Formate "answers" und "context" enthält:
{
    "answers": ["Each item", "appears as separate chat bubble"],
    "context": {"context_item": "..."}
}
Chat-Nachricht-EndpunktWird vom Userlike-Chatserver bei jeder Nachricht gecallt, die der Webvisitor oder Chat-Server an Ihren Bot schickt. Ihre Antwort wird an den Webvisitor gesendet.
Request-FormatPOST - mit Body, der die JSON-Formate "input" und "context" enthält:
{
    "input": "Message sent by Webvisitor",
    "context": {"context_item": "..."}
}
Antwort-FormatPOST - mit Body, der die JSON-Formate "answers" und "context" enthält:
{
    "answers": ["Each item", "appears as separate chat bubble"],
    "context": {"other_item": "..."}
}
Chat-Ende-EndpunktWird mit einer POST-Request vom Userlike Chatserver gecallt, wenn die Chat-Session mit Ihrem Bot endet. Es wird keine Antwort erwartet.
Request-FormatPOST - mit Body, der das JSON-Format "context" enthält:
{
    "context": {"other_item": "..."}
}
Antwort-FormatKeine Antwort erwartet
JSON-Exchange-Format

Der Text jeder POST Anfrage/Antwort muss ein JSON-Objekt beinhalten. Es gibt drei verschieden JSON-Formate, die dieses Objekt darstellen können: "input", "answers" und "context". Während "input" und "answers" sich gegenseitig ausschließen, muss das "context"-Objekt immer vorliegen.

JSON-FormatBeschreibung
answers"Antworten" von Ihrem Chatbot können entweder als einzelner String oder als Array von Strings oder Objekten versendet werden. Bei einem Array wird Ihrem Webvisitor jedes Element in einer separaten Chat-Blase angezeigt. Beispiel:
"answers": ["First message sent to Webvisitor", "Second message"]
"answers": "Only one message sent to Webvisitor"
"answers": [
    "The next message is a command",
    {"command": "push", "value": "/about"}
]
inputVon Ihrem Chatbot gesendet, enthält "input" die Chat-Nachricht Ihres Webvisitors als einzelner String.
"input": "Incoming message from Webvisitor"
contextVon Ihrem Chatbot gesendet und wiederholt in der Antwort unseres Chatservers, kann "context" jedes gültige JSON-Object sein, dass sie benötigen. Beispiel:
"context": {
    "state": "askname",
    "session_info": {
        "id": "abcdef"
    }
}
States halten

Wir haben gesehen, dass der JSON-Body jeder POST-Anfrage/Antwort ein "context"-Objekt enthalten muss. Ausgelöst von der ersten Antwort Ihres Chatbots (/Chatbot-Frameworks), werden alle weiteren Anfragen von unserem Chat-Server an Ihren Chatbot immer das letzte "context"-Objekt, das Ihr Bot bereitgestellt hat, wiederholen.

Sie können dieses wiedergegebene "context"-Object benutzen, um den State des Chats in Ihrem Chatbot (Framework) zu verfolgen. Ein kurzes Beispiel:

Anfrage/AntwortJSON-Body
Erste Request unseres Chat-Servers, wenn ein neuer Chat beginnt-
Die erste Antwort des Chatbots definiert den State im Kontext
{
    "answers": ["What is your name?"],
    "context": {
        "state": "askname"
    }
}
Die nächste Chat-Server-Request gibt den ursprünglichen State im Kontext wieder
{
    "input": "John Doe",
    "context": {
        "state": "askname"
    }
}
Die nächste Chatbot-Antwort aktualisiert den State im Kontext
{
    "answers": ["And your email address?."],
    "context": {
        "state": "askemail"
    }
}
Die nächste Chat-Server-Request gibt den aktualisierten State im Kontext aus
{
      "input": "john.doe@userlike.com",
      "context": {
          "state": "askemail"
      }
  }

Bei jeder Request an Ihren Chatbot (Framework) "erinnert" unser Chatserver den Bot also über den State der aktuellen Chat-Session. Bitte beachten Sie, dass dies nur ein Beispiel ist und Sie dem "context"-Object verschiedene Eigenschaften zuweisen können: alles, was sie darauf einstellen, wird von unserer nächsten Request wiedergegeben.

Chat-Commands

Sobald Ihr Bot in die Userlike-Chat-Infrastruktur integriert ist, kann er mit Ihren Webvisitors interagieren. Noch besser, er hat auch Zugriff auf die Userlike Chat-Commands, was ihm völlige Kontrolle über die initiierte Chat-Session gibt. So kann Ihr Chatbot Daten von Webvisitors sammeln und speichern, sie an bestimmte Orte Ihrer Website senden oder die aktuelle Chat-Session an einen menschlichen Kollegen weiterleiten.

Sie können Userlike Chat-Befehle als reguläre Nachrichten oder als JSON-Objekte senden. Der Befehlstext soll mit dem Befehlsnamen anfangen und muss nicht das Zeichen "$" enthalten. When der Befehl einen Argument erfordert, muss dieser unter "Wert" angegeben werden, sofern nicht anders spezifiziert.

{
    "answers": [
        {
            "command": "screenshot"
        },
        {
            "command": "push",
            "value": "/about"
        }
    ]
}

Die folgenden Commands sind aktuell verfügbar und ermöglichen leistungsstarke Automationsmuster.

CommandBeschreibung
$screenshotScreenshot vom Browser des Webvisitors machen
$forwardChat an anderen Operator weiterleiten
$forward.jsonChat an anderen Operator weiterleiten (mit JSON-Response)
$groupChat an andere Operatorengruppe weiterleiten
$group.jsonChat an andere Operatorengruppe weiterleiten (mit JSON-Response)
$anyChat an den nächsten verfügbaren Operator weiterleiten
$any.jsonChat an nächsten verfügbaren Operator weiterleiten (mit JSON-Response)
$nameWebvisitor Namen hinzufügen
$additional01Zusätzlichen Wert 1 setzen
$additional02Zusätzlichen Wert 2 setzen
$additional03Zusätzlichen Wert 3 setzen
$emailE-Mail Ihres Webvisitors hinzufügen
$localeLocale für Chat-Session festlegen
$noteDem Chat-Transkript eine Notiz hinzufügen
$sendChat-Transkript nach Beendigung der Chat-Session an die E-Mail-Adresse Ihres Webvisitors senden
$dispatchChat-Transkript an die von Ihnen angegebene E-Mail-Adresse senden
$pushWebvisitor auf eine lokale URL leiten
$downloadOffer Webvisitor given download
$blockWebvisitor aus dem Chat blocken
$imageEin Bild an den Webvisitor schicken.

Geben Sie eine Bild-URL als erstes Argument an.
$image https://example.com/image.png
Alternativ können Sie eine URL zu einem Vorschaubild definieren.
$image https://example.com/image.png https://example.com/thumbnail.png
Sie können eine optionale Überschrift definieren, die in doppelte Anführungszeichen eingebettet sein muss.
$image https://example.com/image.png "This is an example image"
Sie können sowohl ein Vorschaubild als auch eine Überschrift definieren.
$image https://example.com/image.png https://example.com/thumbnail.png "This is an example image"

Anstelle der Kodierung des Befehls als String können Sie ein JSON-Objekt senden.
{
    "answers": [
        {
            "command": "image",
            "url": "https://example.com/image.png",
            "thumbnail_url": "https://example.com/thumbnail.png",
            "title": "This is an example image"
        }
    ]
}

Die Werte "thumbnail_url" und "title" sind optional.
$videoVideo an Webvisitor schicken.

Geben Sie eine Video-URL als erstes Argument an.
$video https://example.com/video.mp4
Alternativ können Sie eine URL zu einem Vorschaubild definieren.
$video https://example.com/video.mp4 https://example.com/thumbnail.jpg
Sie können auch eine optionale Überschrift hinzufügen, die in doppelte Anführungszeichen eingebettet sein muss.
$image https://example.com/video.mp4 "This is an example video"
Sie können sowohl ein Vorschaubild als auch eine Überschrift definieren.
$image https://example.com/video.mp4 https://example.com/thumbnail.jpg "This is an example video"

Anstelle der Kodierung des Befehls als String können Sie ein JSON-Objekt senden.
{
    "answers": [
        {
            "command": "video",
            "url": "https://example.com/video.mp4",
            "thumbnail_url": "https://example.com/thumbnail.jpg",
            "title": "This is an example video"
        }
    ]
}

Die Werte "thumbnail_url" und "title" sind optional.

Hinweis: Stellen Sie sicher, dass das Video in einem Format kodiert ist, das von allen Webbrowsern unterstützt wird.
$chipsEine Liste vordefinierter Antworten schicken.

Geben Sie durch Semikolon getrennte Optionen an.
$chips Yes;No;Maybe later
Sie können für jede Antwort auch ein separates Label definieren.
$chips Yes:Yes please!;No:No thanks!;Maybe later Sie können eine optionale Überschrift definieren, die in doppelte Anführungszeichen eingebettet sein muss.
$chips Yes;No;Maybe later "Would you like to buy this product?"
Hinweis: Falls Ihre Optionen die Sonderzeichen ";", ":" oder "\" enthalten, müssen diese mit "\" maskiert werden.
$chips Yes:Yes please!;No:No thanks!;Maybe later:My answer is\: maybe

Anstelle der Kodierung des Befehls als String können Sie ein JSON-Objekt senden.
{
    "answers": [
        {
            "command": "chips",
            "choices": [
                {"title": "Yes"},
                {"title": "No"},
                {"title": "Maybe later", "message": "My answer is: maybe"}
            ],
            "title": "Would you like to buy this product?"
        }
    ]
}

Beim Senden des Befehls als JSON-Objekt sind keine speziellen Escape-Zeichen notwendig.
$linksListe von Links mit einem Titeltext schicken.
$quitChat beenden
![macroname]Gespeicherten Textbaustein senden

Wenn Sie Erfolgs- und Fehler-Benachrichtigungen für reguläre Chat-Commands (z.B. "$any") in Ihrem Bot-Interface erhalten möchten, aktivieren Sie diese Option in den Bot-Operator-Einstellungen. Andernfalls werden diese Nachrichten nicht zurück in Ihr Bot-Interface geleitet.

Falls ein JSON-Command bereitgestellt wurde, wird das dazugehörige Response-Object das folgende Format haben:

{
type: "info|error",
status: "OperatorStatsError|OK|OperatorNameNotFound|OperatorNotFound|SelfForwardError|OperatorBusy|OperatorNotAvailable|GroupNotFound|GroupNameNotFound|AllOperatorsBusy",
message: "...",
data: {...},
}

 

Schauen Sie sich Code-Beispiel weiter unten an das Code-Beispiel an, um mehr über die Integration dieser Commands in Ihre Bot-Logik zu erfahren.

Chatbot-Chat-Übersicht

Während wir Automation bei vielen Aufgaben willkommen heißen, möchten wir dem Chatbot unseres Vertrauens doch ab und zu auf die Finger schauen. Ist er wirklich der loyale Diener, den wir uns erhoffen? Glücklicherweise ist die gesamte Aktivität Ihres Chatbots in Transkripten in Ihrem Dashboard verfügbar, wie bei jedem menschlichen Operator.

Anschließend an unser einfaches Beispiel von oben wird die folgende Interaktion eines Webvisitors mit Ihrem Chatbot...

... genau so im Userlike Dashboard angezeigt, wie jedes andere Chat-Transkript.

Sie können ganz einfach alle Interaktionen Ihres Chatbots nach regulären Audits filtern und sicher stellen, dass er seinen Job wie erwartet erledigt. Gefilterte Ergebnisse enthalten auch Interaktionen, die nur von Ihrem Chatbot initiiert wurden und dann zu einem menschlichen Operator weitergeleitet wurden, so haben Sie also wirklich die komplette Übersicht.

Chatbot-Ideen

Wir haben ein paar Ideen für sinnvolle Kundenservice-Chatbot-Projekte gesammelt, die Sie in die Userlike-Infrastruktur einbinden können.

Ein simpler Service-Chatbot

Ein Service-Chatbot befindet sich an vorderster Front. Er wartet auf Webvisitors, begrüßt sie und sammelt nützliche Daten für besseren Kundenservice. Sobald er seinen Job erledigt hat, leitet er den Webvisitor an einen menschlichen Kollegen weiter.

Wir stellen Ihnen standardmäßig unseren eingebauten Service-Chatbot Chat Butler zur Verfügung, Sie können allerdings auch Ihre eigene Version mit erweiterten Funktionen entwerfen, die besser zu Ihrem Anwendungsgebiet passen.

Was ein Service-Chatbot für Sie tun kann
Ihre Webvisitor mit Ihren vordefinierten Makros ansprechen
{
    "answers": ["!hi", "!welcome"],
    "context": {...}
}
E-Mail-Adresse des Webvisitors festlegen
{
    "answers": ["$email %s" % email_from_input],
    "context": {...}
}
Namen des Webvisitors festlegen
{
    "answers": ["$name %s" % name_from_input],
    "context": {...}
}
Ihre Webvisitors an einen beliebigen freien menschlichen Operator weiterleiten
{
    "answers": ["$any"],
    "context": {...}
}
Ein "Deal"-Bot

Der Deal-Bot bietet Ihren Kunden an, nach speziellen Angeboten zu suchen.

Kram, den ein Deal-Bot für Sie erledigen kann
Webvisitors proaktiv fragen, ob sie an speziellen Deals interessiert sind
{
    "answers": ["Want me to check for special deals?"],
    "context": {...}
}
Shop-API-Results an Webvisitor zurücksenden
{
    "answers": [
        "Best deal: http://deal-url",
        {
            "command": "chips",
            "title": "Interested?"
            "options": ["Yes", "No"]
        }
    ],
    "context": {...}
}
Die Antwort des Webvisitors beurteilen und ihn an Produkt-URL weiterleiten
{
    "answers": ["Here you go!", "$push http://deal-url"],
    "context": {...}
}
Ein Routenbot

Der Routen-Bot gibt Ihren Webvisitors Echtzeit-Informationen darüber, wie sie Ihre Firma oder Ihr Event mit öffentlichen Verkehrsmitteln erreichen können. Basierend auf dem vom Webvisitor bereitgestellten Standort sendet der Bot Anfragen an Drittanbieter-Services (z.B. den Verkehrsverbund Berlin-Brandenburg (VBB) und bietet ihnen die Reiseroute von der nächstgelegenen Station zu Ihrem Geschäft, inklusive Fahrplänen.

Dinge, die ein Routenbot für Sie tun kann
Den Standort Ihres Webvisitors abfragen
{
    "answers": ["Where are you right now?"],
    "context": {...}
}
Drittanbieter-API-Results an Webvisitor schicken
{
    "answers": ["Take line %s at station %s." % (line, station)],
    "context": {...}
}
Karte mit Route zur nächsten Station erstellen und an Webvisitor schicken
{
    "answers": [
        "$image %s \"Route to the next station\"" % map_image_url,
        "Here is also a link to Google Maps: %s" % google_map_url],
    "context": {...}
}

Haben wir Ihr Interesse geweckt? Wir sind neugierig, welche Art von Chatbot-Service Sie (vorhaben zu) entwerfen und in Userlike integrieren möchten! Hinterlassen Sie uns einen Kommentar, kontaktieren Sie uns auf Facebook oder Twitter oder schicken Sie uns ein paar Zeilen per Mail.

Beispiel-Code

Wir haben ein un repositorio Github , um Ihnen ein paar vollständige Code-Beispiele zu geben. Hier ist ein komplettes Beispiel für einen (simplen) Chatbot.

Weitere Beispiele/Pull-Requests sind willkommen!