Skip to main content

​
Data that Enneo passes to your code (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
}
Variable names such as customerId or my-custom-parameter can be set by you under Settings -> Customer and Contract Search -> Customer Recognition via AI -> Search Parameters Customer Identification, including the prompt used for recognition. The above values are examples.

​
Data structure that Enneo expects as a return value (Output)

{
  "contractId": "100001", // contract id of the found contract
  "customerId": "200001", // customer id associated to the found contract. cannot be null
}
Remarks:
  • Enneo always expects exactly one or no contract. If the search parameters produce more than one result, you need to narrow down the search to exactly one result before calling Enneo.
  • If the search yields no results, Enneo expects an empty object ({}) or a null result (null).
  • If you want to override the Enneo legitimation, you can add the customerLegitimation and customerLegitimationMessage properties. You can find more information on the relevant documentation page ([/en/guides/customer-recognition/contract-legitimation]).

​
Sample implementation

<?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?' . 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, but requirement to be removed in a future enneo version
];
} 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/en/guides/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);