> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kontakt-Lookup-Webhook

> Identifiziere unbekannte Anrufer, indem du ihre Telefonnummer in deinem System nachschlägst, bevor der Anruf beginnt

## Überblick

Der Kontakt-Lookup-Webhook ermöglicht es dir, unbekannte eingehende Anrufer zu identifizieren, indem ihre Telefonnummer in deinem System nachgeschlagen wird, bevor der Anruf verbunden wird. Wenn aktiviert, sendet telli eine POST-Anfrage an deinen Endpunkt mit der Telefonnummer des Anrufers, und dein Endpunkt antwortet mit den Kontaktdaten.

Das ist nützlich, wenn du:

* Anrufer mit Namen begrüßen möchtest
* Anrufe basierend auf Kundendaten weiterleiten möchtest
* Eigene Eigenschaften über dynamische Variablen an den Prompt deines Agenten übergeben möchtest

<Warning>
  Der Webhook wird aufgerufen, bevor der Anruf verbunden wird. Das konfigurierte Timeout verlängert die Klingelzeit für den Anrufer. Halte deinen Endpunkt schnell und setze das Timeout so niedrig wie möglich.
</Warning>

## Einrichtung

1. Gehe zu **Einstellungen → Integrationen**
2. Wähle **Kontakt-Lookup-Webhook**
3. Gib deine Webhook-URL ein
4. Setze ein Timeout (1–10 Sekunden)
5. Füge optional eigene Header und Query-Parameter hinzu
6. Aktiviere die Integration und klicke auf **Speichern**

## Anfrage

Wenn ein eingehender Anruf von einer unbekannten Nummer eingeht, sendet telli eine POST-Anfrage an deine Webhook-URL:

```json theme={null}
{
  "event": "contact_lookup",
  "phone_number": "+14155551234",
  "to_number": "+14155550000"
}
```

| Feld           | Typ    | Beschreibung                                       |
| -------------- | ------ | -------------------------------------------------- |
| `event`        | string | Immer `"contact_lookup"`                           |
| `phone_number` | string | Die Telefonnummer des Anrufers im E.164-Format     |
| `to_number`    | string | Die angerufene telli-Telefonnummer im E.164-Format |

Alle eigenen Header und Query-Parameter, die du in den Integrationseinstellungen konfiguriert hast, werden in der Anfrage mitgesendet.

### Signaturprüfung

Die Anfrage enthält einen `x-telli-signature` Header, mit dem du überprüfen kannst, ob die Anfrage von telli stammt. Die Signatur ist ein HMAC-SHA256-Hash des Anfragekörpers, signiert mit dem API-Key deines Accounts.

## Antwort

Dein Endpunkt sollte eine JSON-Antwort mit den Kontaktdaten zurückgeben:

```json theme={null}
{
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "salutation": "Frau",
    "email": "jane@example.com",
    "external_id": "usr_12345",
    "external_url": "https://crm.example.com/contacts/12345",
    "phone_number": "+14155551234",
    "properties": {
      "plan": "enterprise",
      "account_manager": "John Smith",
      "priority": 1
    }
  }
}
```

| Feld           | Typ    | Erforderlich | Beschreibung                                                                                                                                                                                                                                  |
| -------------- | ------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `first_name`   | string | Ja           | Vorname des Kontakts (1–50 Zeichen)                                                                                                                                                                                                           |
| `last_name`    | string | Ja           | Nachname des Kontakts (1–50 Zeichen)                                                                                                                                                                                                          |
| `salutation`   | string | Nein         | Anrede oder Titel (z.B. „Herr", „Frau", „Dr.")                                                                                                                                                                                                |
| `email`        | string | Nein         | E-Mail-Adresse des Kontakts                                                                                                                                                                                                                   |
| `external_id`  | string | Nein         | Die Kennung des Kontakts in deinem System. Wenn ein Kontakt mit dieser ID bereits existiert, wird er aktualisiert statt ein Duplikat zu erstellen.                                                                                            |
| `external_url` | string | Nein         | Eine URL zum Kontakt in deinem System                                                                                                                                                                                                         |
| `phone_number` | string | Nein         | Die Telefonnummer des Kontakts (Standard: die Nummer des Anrufers)                                                                                                                                                                            |
| `properties`   | object | Nein         | Eigene Kontakteigenschaften. Schlüssel müssen mit deinen konfigurierten Eigenschaftsschlüsseln übereinstimmen. Werte müssen dem Datentyp der Eigenschaft entsprechen (String, Zahl, Boolean, Datum, Select-Wert oder Array für Multi-Select). |

### Unbekannter Anrufer

Wenn die Telefonnummer nicht in deinem System gefunden wird, gib einen leeren Kontakt zurück:

```json theme={null}
{
  "contact": null
}
```

### Eigene Eigenschaften

Das `properties`-Objekt ermöglicht es dir, eigene Daten zu übergeben, die mit deiner [Kontakteigenschaften](/de/platform/contact-properties)-Konfiguration übereinstimmen. Die Eigenschaftsschlüssel müssen mit den Schlüsseln übereinstimmen, die du unter **Einstellungen → Kontakteigenschaften** definiert hast. Werte, die keinem definierten Eigenschaftsschlüssel entsprechen, werden ignoriert.

## Fehlerbehandlung

* Wenn dein Endpunkt einen Nicht-2xx-Statuscode zurückgibt, wird der Anruf mit einem unbekannten Kontakt fortgesetzt
* Wenn dein Endpunkt nicht innerhalb des konfigurierten Timeouts antwortet, wird der Anruf mit einem unbekannten Kontakt fortgesetzt
* Wenn der Antwortkörper nicht dem erwarteten Format entspricht, wird der Anruf mit einem unbekannten Kontakt fortgesetzt

In allen Fehlerfällen wird der Anruf nie blockiert — der Anrufer wird immer verbunden.

## Beispielimplementierung

Hier ist ein minimales Beispiel mit Node.js und Express:

```javascript theme={null}
app.post("/telli/contact-lookup", (req, res) => {
  const { phone_number } = req.body;

  // Kontakt in deiner Datenbank nachschlagen
  const contact = db.findContactByPhone(phone_number);

  if (!contact) {
    return res.json({ contact: null });
  }

  res.json({
    contact: {
      first_name: contact.firstName,
      last_name: contact.lastName,
      email: contact.email,
      external_id: contact.id,
      properties: {
        plan: contact.plan,
        account_manager: contact.accountManager,
        priority: contact.priority,
      },
    },
  });
});
```