Enneo

KI-Agenten & Automatisierung

SDK

enneo SDK - Dokumentation

Das enneo SDK bietet eine umfassende Sammlung von Werkzeugen, die die Entwicklung von spezifischem Code für kundenspezifische Lösungen im Bereich des KI-gestützten Kundensupports erleichtert. Das SDK unterstützt die Implementierung regelbasierter Logik für KI-Agenten, eventbasierte Integrationen, kundenspezifische Webhooks und benutzerdefinierte Funktionen. Das SDK wird automatisch geladen und die Funktionen stehen direkt zur Verfügung.

Einbindung des SDK im Code

Um das enneo SDK in Ihren Code einzubinden, kann folgendes Code-Snippet verwendet werden:

<?php

require(getenv()['SDK'] ?? 'sdk.php');
file_path = os.getenv('SDK', 'sdk.py')
spec = importlib.util.spec_from_file_location('sdk', file_path)
sdk = importlib.util.module_from_spec(spec)
spec.loader.exec_module(sdk)

enneo API Wrapper

Das enneo SDK bietet Wrapper für die enneo API Endpunkte, mit denen bequem auf die API zugegriffen werden kann:

  • Laden der Vertragsdaten anhand der Vertrags-ID
  • Laden der Ticket-Daten anhand der Ticket-ID
  • Ausführen benutzerdefinierter Funktionen
  • Aufrufen beliebiger enneo-API Endpunkte (GET | POST | PATCH | PUT | DELETE)
  • Lesen von Secrets (getSecret)
  • Laden von Dateien aus dem enneo-Speicher (getFileFromStorage, in Python get_file_from_storage)

API-Aufrufe laufen standardmäßig im Namen des Nutzers, der das Skript gestartet hat, und mit dessen Berechtigungen. Mit dem optionalen Parameter authorizeAs: 'serviceWorker' laufen sie stattdessen mit den Berechtigungen des Service-Workers. Danach richtet sich auch, wem die Arbeit in Zeiterfassung und Reporting zugerechnet wird.

<?php

use EnneoSDK\ApiEnneo;

require(getenv()['SDK'] ?? 'sdk.php');

/**
 * Lädt die Vertragsdaten zum Vertrag mit der ID 123
 */
$contract = ApiEnneo::getContract(contractId: 123);

/**
 * Lädt Ticketdaten zum Ticket mit der ID 456
 */
$ticket = ApiEnneo::getTicket(ticketId: 456);

/**
 * Fürt benutzerdefinierte Funktion 'user-defined-function' aus.
 * (s. Dokumentation der benutzerdefinierten Funktionen)
 * Eingegebene Parameter werden an die benutzerdefinierte Funktion übergeben
 * und können dort mittels \EnneoSDK\Input::load() geladen werden.
 */
$response = ApiEnneo::executeUdf(
    name: 'user-defined-function',
    parameters: [
        'method' => 'POST',
        'api' => 'redirect',
        'params' => $payload
    ]
);


##########################################################################
## Die Methoden get | post | patch | put | delete können verwendet werden,
## um beliebige enneo API Endpunkte aufzurufen
## (s. API Dokumentation)
##########################################################################

/**
 * Profil des aktuell eingeloggten Nutzers laden
 */
$profile = ApiEnneo::get(endpoint: '/api/mind/profile');

/**
 * OCR Zählerstandserkennung für vorgegebene Ticket-ID und URL zum Ticket-Anhang
 */
$response = ApiEnneo::post(
    endpoint: '/api/cortex/ocrMeter',
    body: [
        'ticketId' => $ticketId,
        'fileUrl' => $_ENV['ENNEO_API_URL'] . $attachment->url,
    ]
);

/**
 * Ticket schließen
 */
$response = ApiEnneo::patch(
    endpoint: '/api/mind/ticket/' . $ticketId,
    body: ['status' => 'closed']
);
# Lädt die Vertragsdaten zum Vertrag mit der ID 123
contract = sdk.ApiEnneo.get_contract(123)

# Lädt Ticketdaten zum Ticket mit der ID 456
ticket = sdk.ApiEnneo.get_ticket(456)

# Führt die benutzerdefinierte Funktion 'user-defined-function' aus
response = sdk.ApiEnneo.executeUdf(
    'user-defined-function',
    {'method': 'POST', 'api': 'redirect', 'params': payload}
)

# Profil des aktuell eingeloggten Nutzers laden
profile = sdk.ApiEnneo.get('/api/mind/profile')

# Ticket schließen
response = sdk.ApiEnneo.patch(f'/api/mind/ticket/{ticket_id}', {'status': 'closed'})

Bausteine des SDK

BausteinWofür
InputEingabedaten des Skripts laden (Input::load(), in Python load_input_data()); prüfen, ob gerade ein Chat- oder Voicebot das Gespräch führt (isBotConversation)
ApiEnneoenneo-API aufrufen (siehe oben)
ApiExterne Schnittstellen per HTTP aufrufen
SettingEinstellungen lesen und schreiben
Interaction, IntentInfo, IntentOption, FormAusgabe eines regelbasierten KI-Agenten aufbauen: Hinweise, Formularfelder und Schaltflächen
NotificationEinem Mitarbeiter eine Nachricht anzeigen (siehe unten)
HelpersHilfsfunktionen, z. B. Datum formatieren oder IBAN formatieren und prüfen
AppInfo, AppStorageAngaben zur eigenen App und deren Datenspeicher – siehe Apps entwickeln

Nachricht an einen Mitarbeiter anzeigen

Mit Notification.send kann Ihr Code – etwa ein Event-Hook – einem Mitarbeiter eine Nachricht direkt auf dem Bildschirm anzeigen, als Karte oben rechts. So lassen sich Hinweise zu geänderten Abläufen, Fehler oder Ergebnisse genau dort zeigen, wo gerade gearbeitet wird.

Die Nachricht geht direkt an die geöffneten Tabs des Mitarbeiters und wird nicht gespeichert: Ist er nicht online oder lädt er die Seite neu, sieht er sie nicht nachträglich, und sie erscheint nicht in der Benachrichtigungsglocke.

ParameterStandardBedeutung
userId–ID des Mitarbeiters, dem die Nachricht angezeigt wird
body–Text der Nachricht, bis zu 2000 Zeichen
severityinfosuccess, info, warning oder error – bestimmt Farbe und Symbol
actionUrl–Pfad innerhalb von enneo, z. B. /tickets/123, wird als Schaltfläche angeboten. Links auf externe Websites werden abgelehnt
duration0Ganze Sekunden, bis sich die Karte selbst schließt, höchstens 3600; 0 = bleibt, bis sie geschlossen wird
key–Fester Name der Nachricht – lateinische Buchstaben (ohne Umlaute), Ziffern und _ . : -, bis zu 100 Zeichen. Wird sie erneut gesendet, ersetzt sie die Karte, statt eine zweite anzuzeigen
showDontShowAgainfalseBietet „Nicht mehr anzeigen“ an; gespeichert pro Mitarbeiter in seinem Browser. Wirkt nur zusammen mit key; um eine ausgeblendete Nachricht wieder zu zeigen, einen neuen key verwenden
allowHtmlfalseZeigt body als HTML oder Markdown an: fett, kursiv, Listen, Code und Links. Ohne diese Option wird der Text unverändert angezeigt, Tags eingeschlossen

In Python heißen die Parameter user_id, action_url, show_dont_show_again und allow_html; in Node.js werden die optionalen Parameter als Objekt übergeben.

Standardmäßig erhält ein Mitarbeiter höchstens 10 Nachrichten pro Minute, aus allen Hooks zusammen, ausgeblendete eingeschlossen. send wirft einen Fehler, wenn die Nachricht abgelehnt wird: ein Feld ist ungültig, das Limit ist erreicht, oder der Code läuft nicht in der enneo-Sandbox – ein lokaler Lauf Ihres Skripts erhält diesen Fehler immer. Ist die Nachricht nicht zwingend, fangen Sie den Fehler ab, damit der Hook weiterläuft. In der Antwort gibt roomInfo.hasReceivers an, ob der Mitarbeiter enneo geöffnet hatte – nicht, ob er die Karte gesehen hat.

Warning

allowHtml nur mit eigenem, festem Text verwenden. Ticket- und Kundendaten – Betreff, Name, Nachrichtentext – stammen von außen und können selbst HTML enthalten. Fügen Sie sie nie in eine HTML-Nachricht ein. Erhalten bleiben nur Formatierung und Links; für den Inhalt der Nachricht ist Ihr Code verantwortlich. Links auf externe Websites öffnen sich in einem neuen Tab; ein Pfad innerhalb von enneo gehört in actionUrl.

<?php

use EnneoSDK\Notification;

require(getenv()['SDK'] ?? 'sdk.php');

Notification::send(
    userId: $userId,
    body: 'Bitte den KI-Agenten zuweisen statt des Tags – der Tag wird automatisch gesetzt.',
    severity: 'warning',
    key: 'assign-agent-not-tag',
    showDontShowAgain: true,
);
sdk.Notification.send(
    user_id,
    'Bitte den KI-Agenten zuweisen statt des Tags – der Tag wird automatisch gesetzt.',
    severity='warning',
    key='assign-agent-not-tag',
    show_dont_show_again=True,
)
const { Notification } = require(process.env.SDK || 'sdk.js');

(async () => {
  await Notification.send(userId, 'Bitte den KI-Agenten zuweisen statt des Tags – der Tag wird automatisch gesetzt.', {
    severity: 'warning',
    key: 'assign-agent-not-tag',
    showDontShowAgain: true,
  });
})();

Aufruf benutzerdefinierter Funktionen

Der Aufruf benutzerdefinierter Funktionen im Code erfolgt mithilfe von executeUdf:

<?php

// enneo SDK laden
require(getenv()['SDK']);

// Payload für den API Aufruf des Third-Party-Systems vorbereiten
$payload = [
    'ticket-id' => 123,
    'key' => 'value'
];

// Aufruf der benutzerdefinierten Funktion "third-party-api-call"
// diese Funktion erhält als Eingabeparameter ein Objekt:
// [
//      'method' => 'POST',
//      'api' => 'item',
//      'params' => [
//          'ticket-id' => 123,
//           'key' => 'value'
//      ]
// ]
EnneoSDK\ApiEnneo::executeUdf(
    'third-party-api-call',
    ['method' => 'POST', 'api' => 'item', 'params' => $payload]
);

SDK Code

Die SDKs sind verfügbar unter:

Obige URLs funktionieren ohne Authorisierung, d.h. können von Ihren Skripten direkt eingebunden werden.