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 Pythonget_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
| Baustein | Wofür |
|---|---|
Input | Eingabedaten des Skripts laden (Input::load(), in Python load_input_data()); prüfen, ob gerade ein Chat- oder Voicebot das Gespräch führt (isBotConversation) |
ApiEnneo | enneo-API aufrufen (siehe oben) |
Api | Externe Schnittstellen per HTTP aufrufen |
Setting | Einstellungen lesen und schreiben |
Interaction, IntentInfo, IntentOption, Form | Ausgabe eines regelbasierten KI-Agenten aufbauen: Hinweise, Formularfelder und Schaltflächen |
Notification | Einem Mitarbeiter eine Nachricht anzeigen (siehe unten) |
Helpers | Hilfsfunktionen, z. B. Datum formatieren oder IBAN formatieren und prüfen |
AppInfo, AppStorage | Angaben 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.
| Parameter | Standard | Bedeutung |
|---|---|---|
userId | – | ID des Mitarbeiters, dem die Nachricht angezeigt wird |
body | – | Text der Nachricht, bis zu 2000 Zeichen |
severity | info | success, 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 |
duration | 0 | Ganze 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 |
showDontShowAgain | false | Bietet „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 |
allowHtml | false | Zeigt 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.