Kundenerkennung
Suche nach Merkmalen
Suche nach Merkmalen
Daten welche enneo an ihren Code übergibt (Input)
{
"customerId": "C-abcd-123",
"contractId": "123",
"my-custom-parameter": "abcd", // to be configured in enneo settings
"any-other-parameter-the-ai-found": "abcd",
"ticketId": 123, // always provided natively by enneo, regardless of AI search results
}Die Variabelnamen, z.B. customerId oder my-custom-parameter, können durch Sie unter Einstellungen -> Kunden- und Vertragssuche -> Kundenerkennung mittels KI -> Suchparameter Kundenidentifikation selbst festgelegt werden, incl. des zur Erkennung verwendeten Prompts. Obige Werte sind Beispiele.
Datenstruktur welche enneo als Rückgabewert erwartet (Output)
{
"contractId": "100001", // contract id of the found contract. cannot be null
"customerId": "200001", // customer id associated to the found contract. cannot be null
}Anmerkungen:
- Enneo erwartet immer genau einen oder keinen Vertrag. Wenn die Suchparameter mehr als ein Ergebnis liefern, müssen Sie die Suche so einschränken, dass genau ein Ergebnis vorliegt, bevor Sie enneo aufrufen.
- Wird ein Vertrag gefunden, müssen beide IDs zurückgegeben werden —
contractIdundcustomerId. Fehlt eine von beiden, weist enneo das Ergebnis mit einem Fehler zurück. - Falls die Suche keine Ergebnisse liefert, erwartet enneo
null(empfohlen), ein leeres Objekt ({}) oder ein leeres Array ([]). Alle drei bedeuten „kein Vertrag gefunden“ und sind kein Fehler. - Falls Sie die enneo-Legitimation überschreiben möchten, können Sie die Eigenschaften
customerLegitimationundcustomerLegitimationMessagehinzufügen. Weitere Informationen finden Sie auf der entsprechenden Dokumentationsseite ([/de/system-integration/customer-recognition/contract-legitimation]).
Mehrstufige Vertragsstrukturen
Enneo kennt zwei Ebenen: Kunde und Vertrag. Die contractId muss dabei nicht die Vertragsnummer aus Ihrem ERP sein. Sie ist der Schlüssel, unter dem enneo den Vertrag speichert und zwischenspeichert und den es später unverändert an searchContractByIdExecutor übergibt. Was sie bezeichnet, legen Sie fest.
Das hilft, wenn ein Anliegen ein Objekt unterhalb des Vertrags betrifft, etwa eine einzelne Verbrauchsstelle in einem Bündelvertrag mit tausenden Verbrauchsstellen, oder wenn es darauf ankommt, welcher Ansprechpartner schreibt. Geben Sie dann eine contractId zurück, die dieses Objekt mit bezeichnet:
- Zusammengesetzte ID: Die Bestandteile werden mit einem festen Trennzeichen verbunden, z. B.
BV-1001_48213für BündelvertragBV-1001und Verbrauchsstelle48213. IhrsearchContractByIdExecutorzerlegt die ID wieder und lädt die Daten genau dieser Verbrauchsstelle. - Such-ID: eine eigene ID, die Sie in Ihrem System über eine Mapping-Tabelle auf die Bestandteile abbilden.
Betrifft das Anliegen den Bündelvertrag als Ganzes, geben Sie nur BV-1001 zurück. Die Detailtiefe ergibt sich so aus dem jeweiligen Ticket.
Beachten Sie dabei:
- Alles, was die nachgeladenen Daten beeinflusst, gehört in die
contractId. Enneo cacht Verträge procontractId, sodass Tickets zu verschiedenen Verbrauchsstellen getrennte Daten erhalten. - Die
customerIdbleibt für alle Varianten gleich, z. B. die Bündelkundennummer. Enneo prüft, dass diecustomerIddes geladenen Vertrags mit der aus der Suche übereinstimmt. - Dasselbe Objekt ergibt immer dieselbe ID: feste Reihenfolge der Bestandteile und ein Trennzeichen, das in ihnen nicht vorkommt.
- Höchstens 50 Zeichen für
contractIdundcustomerId. - Jede Variante erscheint in enneo als eigener Vertrag. KI-Agenten erhalten die
contractIdund können sie unverändert an Ihr ERP weitergeben oder selbst zerlegen.
Beispielimplementierung
Das Beispiel ruft ein Demo-ERP auf. Ersetzen Sie <DEMO_TOKEN> durch den Demo-Token aus dem Standardcode unter Einstellungen → Integration in Umsysteme → Kunden- und Vertragssuche in Ihrer Enneo-Instanz. Der Token gibt nur die Demo-Daten frei; Ihr eigenes System verwendet stattdessen seine eigene Authentifizierung.
<?php
// Load enneo SDK. Input is made available through $in
use EnneoSDK\ApiEnneo;
use EnneoSDK\Setting;
use EnneoSDK\Api;
require(getenv()['SDK']);
// These variables can be detected by the AI, if provided by the customer in his request
// If you leave the default setting unchanged, $in contains:
// $in->contractId, $in->customerId, $in->firstname, $in->lastname, $in->phone, $in->company, $in->email, $in->meterNumber, $in->address, $in->postalCode, $in->city
// But feel free to change them, and the detection prompt, to your own needs. Head over to the setting at "Customer and contract search" -> "Search Parameters Customer Identification"
// Get additional metadata from the ticket that you might need, e.g. channel-dependent authorization
// Note: Customer identification and thus this code is one of the first steps in ticket processing, so tags, ai agents, sentiment etc. are not (yet) available and will therefore not be included by the ticket API call
try {
//$ticket = ApiEnneo::get('/api/mind/ticket/'.$in->ticketId);
} catch (Exception $e) {}
// You can also do preprocessing, e.g. input manipulation operations, as in this example
if (isset($in->contractId) && ($in->contractId == 7155559 || $in->contractId == 71559)) {
$in->contractId = 715559;
}
// Do we have a contract id? Then let's do a direct contract search
if ($in->contractId ?? false) {
// Search for the contract id
try {
$contract = ApiEnneo::get('/api/mind/contract/'.$in->contractId);
} catch (Exception $e) {$contract = null;}
if ($contract?->id) {
echo json_encode(['contractId' => $contract->id, 'customerId' => $contract->customerId]);
exit;
}
}
// Do we have a customer id? Then let's do a direct customer search and return the first contract
if ($in->customerId ?? false) {
try {
$customer = ApiEnneo::get('/api/mind/customer/byCustomerId/'.$in->customerId);
} catch (Exception $e) {$customer = null;}
if ($customer?->id) {
foreach ($customer->contractIds as $contractId) {
echo json_encode(['contractId' => $contractId, 'customerId' => $customer->id]);
exit;
}
}
}
// Maybe the LLM just detected a customer ID as contract ID and vice versa. Let's try
if ($in->contractId ?? false) { // Case the LLM found a contract ID that actually was a customer ID
try {
$customer = ApiEnneo::get('/api/mind/customer/byCustomerId/'.$in->contractId);
} catch (Exception $e) {$customer = null;}
if ($customer?->id) {
foreach ($customer->contractIds as $contractId) {
echo json_encode(['contractId' => $contractId, 'customerId' => $customer->id]);
exit;
}
}
}
if ($in->customerId ?? false) { // Case the LLM found a customer ID that actually was a contract ID
try {
$contract = ApiEnneo::get('/api/mind/contract/'.$in->customerId);
} catch (Exception $e) {$contract = null;}
if ($contract?->id) {
echo json_encode(['contractId' => $contract->id, 'customerId' => $contract->customerId]);
exit;
}
}
// Otherwise, let's pass on the remaining search terms to a user-defined API
// Add your handling code here that finds the customers based on the input data
$contractRawData = Api::call(method: 'GET', url: 'https://admin.enneo.ai/api/seed-contracts/search?token=<DEMO_TOKEN>&' . http_build_query($in));
if ($contractRawData) {
$results = [
'contractId' => $contractRawData[0]->id, // e.g. "123". Mandatory to be provided
'customerId' => $contractRawData[0]->customerId, // e.g. "C-456789". Mandatory to be provided
];
} else {
$results = [];
}
// Note: You may choose to override the default enneo legitimation. In this case, you can set these variables. Further details are available at https://docs.enneo.ai/de/system-integration/customer-recognition/contract-legitimation
//$searchResults[0]['customerLegitimation'] = 10; // Either 0, 10, 20 or 30, see the docs for further information
//$searchResults[0]['customerLegitimationMessage'] = "Customer did not provide his special code";
// Finally, return the matching contracts in this data structure
echo json_encode($results);