#
Dialog API
Die Kauz-Plattform ermöglicht Ihnen mithilfe der sogenannten Dialog-API mit dem Chatbot zu interagieren und eine Konversation zu führen. Die API kann eingesetzt werden, um ein eigenes Frontend auf Basis der Kauz Plattform zu entwickeln. Die Schnittstelle selbst nutzt dabei JSON als Datenformat. Die Nachrichten-Inhalte des Chatbots nutzen das sogenannte Kauz Markup.
#
Nutzung der API
#
Protokoll und Endpunkt
Die Dialog-API (sowie alle weiteren APIs) stehen standardmäßig aus Sicherheitsgründen ausschließlich verschlüsselt zur Verfügung (HTTPS). Nutzen Sie dabei für alle Anfragen https:// als Protokoll.
Der Endpunkt ist abhängig von Ihrer Umgebung. Nachfolgend wird für die Beispiele https://example.managed-kauz.net als Endpunkt für die Umgebung angenommen. Tauschen Sie die Domain durch Ihre persönliche aus, um Anfragen an Ihre Umgebung zu senden. Die API ist jeweils unter dem Pfad /api/v4 verfügbar.
#
Authentifizierung
Die Authentifizierung mit der Dialog-API findet durch eine Basic-Authentifizierung statt: username:API_KEY. Die jeweiligen Zugangsdaten für Ihre Umgebung erhalten Sie in Rücksprache mit Ihrer*Ihrem Kauz-Ansprechpartner*in.
curl --location --request POST "https://example.managed-kauz.net/api/v4/dialog/question" \
--header "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
--header "Content-Type: application/json" \
[...]
#
Nachrichten senden (question)
Über /question können neue Fragen an den Chatbot gestellt werden oder eine bestehende Konversation weitergeführt werden: Um eine neue Konversation zu beginnen muss der Parameter conversation bei der Anfrage leer / ungesetzt sein. Um eine bestehende Konversation weiterzuführen, muss die conversation aus der letzten Antwort des Bots in der Anfrage genutzt werden.
#
POST /api/v4/dialog/question
{
"conversation": "string",
"question": "string",
"meta": {},
"customer": "string",
"product": "string",
"group": "string",
"instanceGroup": "string"
}{
"id": "string",
"date": "string",
"conversation": "string",
"customer": "string",
"group": "string",
"intentIds": [
"string"
],
"links": [
"string"
],
"sender": {
"type": "string",
"id": "string"
},
"product": "string",
"raw": "string",
"text": "string",
"textXML": {
"innerXML": "string"
},
"texthash": "string",
"type": "string",
"meta": {}
}curl --location --request POST "https://example.managed-kauz.net/api/v4/dialog/question" \
--header "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
--header "Content-Type: application/json" \
--data-raw "{
\"question\":\"Hallo, wie kannst du mir helfen?\",
\"customer\":\"kauz\",
\"product\":\"helpdesk\",
\"group\":\"de\"
}"{
"id": "51a156da-9393-4a0a-af1e-e76d4d5dbfc7",
"date": "2022-03-30T16:21:22.720Z",
"conversation": "a311a62f-8e01-445a-89e2-186ebf016d55",
"sender": {
"type": "BOT",
"id": "73acad72-7827-4fde-b398-c59607a42826"
},
"content": {
"actions": [],
"sliders": null,
"mapInfo": null,
"card": null,
"textRaw": null,
"searchResults": null,
"plainText": "Guten Tag! Sie können mich alles über unsere Produkte und Dienstleistungen fragen.",
"raw": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><text>Guten Tag! Sie können mich alles über unsere Produkte und Dienstleistungen fragen.</text>"
},
"intentIds": [],
"internal": false,
"meta": {
"isLastDialogPlanNode": "false",
"module": "Basis-Modul",
"parameter": "NO_PARAM",
"thematicKey": "UNKNOWN",
"status": "CORRECT"
},
"raw": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><message conversation=\"a311a62f-8e01-445a-89e2-186ebf016d55\" date=\"2022-03-30T16:21:22.720Z\" id=\"51a156da-9393-4a0a-af1e-e76d4d5dbfc7\"><sender type=\"BOT\" id=\"73acad72-7827-4fde-b398-c59607a42826\"/><content>Guten Tag! Sie können mich alles über unsere Produkte und Dienstleistungen fragen.</content><isInternal>false</isInternal><meta><entry><key>isLastDialogPlanNode</key><value xsi:type=\"xs:string\" xmlns:xs=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">false</value></entry><entry><key>module</key><value xsi:type=\"xs:string\" xmlns:xs=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">Basis-Modul</value></entry><entry><key>parameter</key><value xsi:type=\"xs:string\" xmlns:xs=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">NO_PARAM</value></entry><entry><key>thematicKey</key><value xsi:type=\"thematicKeyBanking\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">UNKNOWN</value></entry><entry><key>status</key><value xsi:type=\"aaKey\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">CORRECT</value></entry></meta><links/><intentIds/></message>",
"group": "de",
"customer": "kauz",
"product": "helpdesk"
}
#
Verarbeitung des Kauz Markup (XML)
#
Rendering von Nachrichteninhalten
Der Inhalt von Chatbot-Nachrichten wird in Form von DOM-Dokumenten dargestellt. Um den Inhalt für Benutzer*innen anzuzeigen, z. B. im Kontext einer webbasierten Benutzeroberfläche, muss der Nachrichteninhalt in ein Format umgewandelt werden, das für die Plattform sinnvoll ist. Mit der Extensible Stylesheet Language (XSL) können Sie solche Transformationen beschreiben, ähnlich wie mit einem Templating-System. Je nach Plattform, auf die Sie abzielen, können Sie XSLT entweder auf der Client-Seite oder auf der Server-Seite ausführen.
Alternativ können auch die DOM-APIs verwendet werden, um Nachrichteninhalte ohne die Hilfe von XSLT zu übersetzen und zu rendern.
#
Client-seitiges XSLT
Alle aktuellen Browser unterstützen die nicht standardisierte XSLT-API, mit der Sie XSL-Transformationen programmatisch nutzen können. Das Mozilla Developer Network bietet einführende Informationen zu XSLT.
Beachten Sie, dass Webbrowser im Allgemeinen nur XSLT 1.0 unterstützen. Für XSLT 2.0 ist eine Bibliothek eines Drittanbieters erforderlich.
Im folgenden Beispiel sehen Sie eine minimale Demonstration, wie die XSLT-API zum Rendern von XML-Inhalten innerhalb einer Webseite verwendet werden kann. In diesem Beispiel wird XML manuell geparst, um eine XML-Dokumentendarstellung zu erzeugen.
const xslt = new XSLTProcessor();
const parser = new window.DOMParser();
const data = "<quux>xyzzy</quux>";
const doc = parser.parseFromString(data, "application/xml");
const stylesheet = parser.parseFromString(`<?xml version="1.0"?>
<xsl:stylesheet
version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html"/>
<xsl:template match="quux">
<strong>
<xsl:value-of select="."/>
</strong>
</xsl:template>
</xsl:stylesheet>`, "application/xml");
xslt.importStylesheet(stylesheet);
const result = xslt.transformToDocument(doc);
document.getElementById("content").appendChild(result.documentElement);
#
Server-seitiges XSLT
Die Pakete xslt-processor und xslt-ts bieten JavaScript- / TypeScript-Implementierungen der XSLT, die Sie bei Nutzung von Node.js einsetzen können.