ky2help®

ky2help® ist eine Service-Management-Plattform unseres Partners Kyberna AG. Die ky2help® Integration verbindet Apptiva Klar mit der ky2help®-Plattform. Mit ihr können ausgewählte Wissensartikel, Incidents und Requests aus ky2help® automatisch mit Apptiva Klar synchronisiert und dem Chatbot zur Verfügung gestellt werden. Incidents und Requests werden mithilfe von KI auf Relevanz analysiert. Die relevanten Artikel werden mit KI zusammengefasst und anonymisiert synchronisiert. Ebenso können direkt aus dem Chat Tickets im ky2help®-System erstellt werden.

Checkliste für die Kyberna Projektleitung

Nutze diese Checkliste zur Vorbereitung der Integration. Kläre die Punkte und liefere die Angaben an das Apptiva-Klar-Projektteam. Punkte zu optionalen Funktionen gelten nur, wenn diese im Projektumfang enthalten sind.

Für jede Integration

• API-URL inklusive API-Version und URL der ky2help®-Instanz mitteilen (z.B. https://acme.ky2help.com/api/v2.19).
• Sicherstellen, dass die gesamte ky2help®-Instanz über HTTPS erreichbar ist und die API-Anfragen aus dem Internet entgegennimmt.
• Falls eine Firewall den API-Zugriff einschränkt: die statischen IP-Adressen der Apptiva-Klarbots freischalten lassen.
• Ein Bearer-Token mit Leseberechtigung für alle zu synchronisierenden Inhalte sowie Schreibberechtigung für Incidents erstellen und sicher an das Apptiva-Klar-Projektteam übermitteln.
• Die tokenbasierte Identifikation in ky2help® aktivieren und dem verwendeten Dienstkonto «Zugriff auf alle Accounts» erteilen.

Wenn Inhalte synchronisiert werden

• Gewünschte Objekttypen nennen: Knowledge, Incidents und/oder Requests.
• Für jede Quelle den gewünschten Namen in Apptiva Klar sowie die View ID angeben.

Wenn Tickets aus dem Chat erstellt werden

• Process Type und Entry Role für Incidents mitteilen.
• Benötigte Custom Params und weitere projektspezifische Incident-Felder festlegen.

Mindestanforderungen

Für die Synchronisation von ky2help® Inhalten muss ein öffentlicher Zugriff auf die ky2help® API des Kundenservers über das Internet (HTTPS Request) gewährleistet sein.

info

Die gesamte ky2help®-Instanz muss über HTTPS laufen. Es reicht nicht, wenn nur die REST-API HTTPS nutzt: Andernfalls kann ky2help® URLs mit HTTP statt HTTPS zurückgeben. Das kann beim Abrufen von Attachments zu Fehlern führen.

Für zusätzlichen Schutz besteht die Möglichkeit, dass dem Apptiva Klarbot 3 statische IP Adressen zugewiesen werden, welche in der Firewall des Kunden der Whitelist hinzugefügt werden können.

Statische IP Adressen für Apptiva Klarbots

• 34.65.11.159
• 34.65.50.222
• 34.65.164.143

Synchronisation von Wissensdatenbanken

Zugriff

Folgende Informationen werden benötigt, um Apptiva Klar Zugriff auf ky2help® zu gewähren:

• API-URL: z.B. https://{Server}.ky2help.ch/api/{Version}
  • Für die Synchronisierung werden HTTPS Anfrage an die API Endpunkte des jeweiligen Objekt Typs (Knowledge, Incidents oder Requests) gesendet
• Access-Token: Auth Bearer Token mit Leseberechtigung für alle zu synchronisierenden Inhalte im ky2help®. Dieses Token kann im ky2help® generiert werden.

Konfiguration

Für jede zu synchronisierende Knowledgebase im Apptiva Klar können folgende Konditionen konfiguriert werden:

Zwingend

• Objekt Typ (Knowledge, Incidents oder Requests)
• Name der synchronisierten Quelle im Apptiva Klar CMS

Optional

• View ID zur Filterung der Inhalte
• Attribute der Artikel, welche ebenfalls synchronisiert werden sollen
  • Für die Synchronisation werden die JSON Keys der Attribute benötigt.
• Bedingungen für die synchronisierte Quelle im Apptiva Klar CMS (z.B. Sprache, Kontexte, Gültigkeit, soll die Knowledgebase in Antworten als Quelle angezeigt werden)

Ticket-Erstellung

Tickets können direkt aus dem Chat erstellt werden. Die Ticket-Erstellung wird durch den ky2help Incident Agent übernommen – einen KI-Agenten, der den Benutzer durch den Erfassungsprozess führt. Der Agent klärt das Anliegen, zeigt dem Benutzer eine Vorschau des Tickets und erstellt es erst nach expliziter Bestätigung. Das erstellte Ticket enthält den gesamten Chatverlauf sowie eine KI-generierte Zusammenfassung des gemeldeten Problems.

Aktivierung im CMS

Sofern das ky2help Modul installiert ist, steht der ky2help Incident Agent im Apptiva Klar CMS automatisch zur Verfügung und muss dort nur noch aktiviert werden.

Tool-Konfiguration

Das Tool ky2help Incident erstellen kann mit projektspezifischen Parametern konfiguriert werden:

Zwingend

• Process Type – Prozesstyp des Incidents in ky2help®
• Entry Role – Eintragsrolle des Incidents in ky2help®
• Fallback Contact ID – Kontakt-ID, die verwendet wird, wenn kein Benutzer identifiziert werden kann

Optional

• Custom Params – weitere projektspezifische Attribute, die beim Erstellen des Incidents mitgegeben werden

Beispielkonfiguration:

{
  "incidentsParams": {
    "fallbackContactId": 42,
    "processType": 2,
    "entryRole": 3,
    "customParams": {}
  }
}

Verhalten konfigurieren via Prompt

Im CMS kann das Verhalten des Agenten über einen Prompt weiter angepasst werden. So lässt sich beispielsweise festlegen, dass der Agent zwingend nach der Geräte-Inventurnummer fragt, bevor ein Incident erfasst wird.

Chatbot-Konfiguration für optimale Ticket-Erstellung

Damit die Ticket-Erstellung reibungslos funktioniert und Nutzerinnen und Nutzer aktiv darauf hingewiesen werden, empfehlen sich folgende ergänzende Einstellungen in der Grundkonfiguration des Chatbots.

Schnellantworten aktivieren

Unter Interaktion → Schnellantworten können Schnellantworten aktiviert werden. Im Feld Anweisungen für Schnellantworten empfiehlt sich folgender Hinweis:

Wenn der Benutzer ein Problem schildert und die Antwort keine Quick Replies gemäss den allgemeinen Regeln ergibt, füge dennoch «Ticket erfassen» hinzu.

So wird dem Benutzer zur richtigen Zeit und im richtigen Kontext eine direkte Möglichkeit zur Ticket-Erstellung angeboten – ohne dass er selbst danach suchen muss.

Antwort bei Wissenslücken anpassen

Unter Verhalten bei Wissenslücken → Allgemeine Antwort kann der Fallback-Text so formuliert werden, dass der Chatbot bei fehlenden Antworten aktiv auf die Ticket-Erstellung hinweist. Beispiel:

Bitte entschuldige, dabei kann ich dir nicht helfen. Wenn du möchtest, kann ich aber für deine Anfrage ein Ticket in ky2help® erfassen.

Dadurch wird eine Wissenslücke nicht als Sackgasse erlebt, sondern direkt in einen produktiven nächsten Schritt überführt.

Zusätzliche Anweisungen beim Antwortverhalten

Ticketerstellung

Wenn eine Antwort eines Agenten ein Ticket präsentiert oder vorschlägt, gibst du diese Antwort strukturell unverändert weiter – keine Umstrukturierung, keine zusätzlichen Sätze, keine Kürzungen. Textuell darfst du nur die Anrede anpassen (Du/Sie). Reihenfolge, Zeilenumbrüche, Fettschrift und Abschnitte bleiben exakt erhalten.

Integration Apptiva Klar Website-Messenger in ky2help®

Die Integration des Apptiva Klar Website-Messengers in ky2help® erfolgt direkt in der ky2help®-Konfiguration. Dort kann unter anderem festgelegt werden, welche Informationen vom Benutzer an den Chatbot weitergegeben werden sollen.

Damit der Website-Messenger in einem ky2help®-iframe eingebettet werden darf, muss die URL der ky2help®-Instanz in der Webclient-Konfiguration unter allowedEmbedOrigins eingetragen sein. Andernfalls blockiert die Content Security Policy das Einbetten.

Beispiel:

allowedEmbedOrigins: ["https://meinefirma.ky2help.ch"];

Hinweis: Für anonyme Benutzer ist standardmässig eingestellt, dass keine Benutzerdaten an den Chatbot übertragen werden. Nur wenn dies explizit umkonfiguriert wird, werden Informationen weitergegeben.

Benutzer authentifizieren

Der Website Messenger kann den aktuell in ky2help angemeldeten Benutzer über ein kurzlebiges, signiertes Identifikationstoken übernehmen. Dabei werden keine Benutzer-IDs oder personenbezogenen Daten in die URL des Chatbots geschrieben.

Voraussetzungen

• Tokenbasierte Benutzeridentifikation wird ab ky2help® Release 4.14.17 beziehungsweise 4.15.3 unterstützt.

• Die Funktion muss in der ky2help®-Konfiguration aktiviert sein:

  platform.application.chatbot.identification.active=true

  Dadurch werden Benutzerdaten nicht mehr als Klartext-URL-Parameter übergeben. Stattdessen löst der Chatbot ein kurzlebiges Token serverseitig über die REST-Schnittstelle gegen die Benutzerdaten ein.

• Die ky2help-API muss über HTTPS erreichbar sein.

• Für das Dienstkonto, dessen Bearer-Token Apptiva Klar verwendet, muss die Berechtigung Zugriff auf alle Accounts aktiviert sein.

• Die URL der ky2help-Instanz muss in allowedEmbedOrigins der Website-Messenger-Konfiguration eingetragen sein.

• Die Host-Anwendung muss einen geschützten Endpunkt bereitstellen, der für den aktuell angemeldeten Benutzer ein kurzlebiges, signiertes Identifikationstoken ausstellt.

Apptiva Klar konfigurieren

Die API-Basis-URL muss die Versionskomponente enthalten. Für die Benutzeridentifikation wird POST /api/v2.19/chatbot/identification verwendet. Der ky2help-Helper löst das Host-Token ein und validiert die Response:

import { identifyHostUser as identifyKy2HelpHostUser } from "@apptiva/klar-ky2help";

const ky2helpApi = {
  baseUrl: "https://meinefirma.ky2help.ch/api/v2.19",
  accessToken: process.env.KY2HELP_ACCESS_TOKEN,
};

const webclientProps = {
  identifyHostUser: (token: string) =>
    identifyKy2HelpHostUser(ky2helpApi, token, logger),
};

logger steht hier für den serverseitigen Apptiva-Klar-Logger. Das Bearer-Token des ky2help-Dienstkontos darf nur serverseitig konfiguriert werden und darf nicht an den Browser gelangen.

Host-Anwendung konfigurieren

Die Host-Anwendung registriert den Handler, bevor der Benutzer den Chat startet. Auf die Anfrage hin ruft sie ihren eigenen geschützten Endpunkt auf. Dieser prüft die ky2help-Session und stellt ein neues, kurzlebiges Token für genau diesen Benutzer aus:

<script>
  window.chatbot.subscribe(
    "ON_HOST_USER_IDENTIFICATION_TOKEN_REQUESTED",
    async () => {
      try {
        const response = await fetch("/api/chat/identification-token", {
          method: "POST",
          credentials: "include",
          headers: { Accept: "application/json" },
        });

        if (!response.ok) return;

        const { token } = await response.json();
        if (typeof token === "string" && token.length > 0) {
          window.chatbot.provideHostUserIdentificationToken(token);
        }
      } catch (error) {
        console.error("Could not request chat identification token", error);
      }
    },
  );
</script>

Der Host-Endpunkt und sein Session-Cookie gehören zur ky2help-Webanwendung; sie werden nicht von Apptiva Klar bereitgestellt. Das Identifikationstoken wird direkt an den Chatbot übergeben, nicht über URL, Local Storage oder Session Storage.

Antwort und Verhalten

Apptiva Klar löst das Host-Token serverseitig mit dem Bearer-Token des ky2help-Dienstkontos ein. Eine erfolgreiche Antwort enthält userId und payload.roles. firstName, lastName und email sind optional. Weitere Payload-Felder können künftig ergänzt werden.

Hinweis zu contactId

payload.contactId ist nur in der Response enthalten, wenn dem ky2help-Account ein Kontakt zugeordnet ist. Ohne Kontaktzuordnung fehlt dieses Feld vollständig.

HTTP-Status	Verhalten
200	Benutzer wird identifiziert und die Chat-Session kann erstellt werden.
404	Token unbekannt oder abgelaufen; keine Session wird erstellt und der Startbildschirm wird angezeigt.
403	Dem ky2help-Dienstkonto fehlt Zugriff auf alle Accounts.
400	Request oder Token ist ungültig.

Während der Prüfung bleibt der Chat gesperrt und zeigt einen Ladeindikator. Die Eingabe wird erst nach erfolgreicher Validierung und Session-Erstellung freigegeben.

Hinweis zur Ticketerstellung: Der ky2help Incident Agent sucht die Kontakt-ID aktuell unter sessionInfo.client.payload.contactId. Die Identifikationsresponse wird vom Website Messenger zunächst unter sessionInfo.user.payload gespeichert. Daher wird eine daraus stammende contactId nicht automatisch als Ticketkontakt verwendet. Bis diese Zuordnung explizit konfiguriert ist, greift die Incident-Konfiguration auf fallbackContactId zurück, wenn im Client-Payload keine Kontakt-ID vorhanden ist.

Bisherige Accountinformations-Einstellung

Veraltet

platform.application.chatbot.accountInformation ist für die bisherige Übergabe von Accountinformationen als URL-Parameter vorgesehen. Diese Methode wird durch die tokenbasierte Benutzeridentifikation (platform.application.chatbot.identification.active=true) ersetzt. Für ky2help® ab Release 4.14.17 beziehungsweise 4.15.3 sollte die tokenbasierte Identifikation verwendet werden.

Die bisherige Einstellung kann bei älteren ky2help®-Releases weiterhin relevant sein. Sie steuert, welche Accountinformationen über den bisherigen Mechanismus an den Chatbot übergeben werden:

platform.application.chatbot.accountInformation=NONE

Die möglichen Werte sind:

• ALL: Alle Informationen (Name, Vorname und E-Mail) werden dem Chatbot übergeben
• NAME: Nur Name und Vorname werden dem Chatbot übergeben
• NONE: Keine Informationen werden dem Chatbot übergeben (Standard)

Diese Einstellung kann in der Datei application.properties angepasst werden. In der Regel ist eine Anpassung jedoch nicht notwendig, da die Standardeinstellung bereits den Datenschutz wahrt.