Kontakt-Lookup-Webhook

Ü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

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.

Einrichtung

Gehe zu Einstellungen → Integrationen
Wähle Kontakt-Lookup-Webhook
Gib deine Webhook-URL ein
Setze ein Timeout (1–10 Sekunden)
Füge optional eigene Header und Query-Parameter hinzu
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:

{
  "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:

{
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "salutation": "Frau",
    "email": "[email protected]",
    "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:

{
  "contact": null
}

Eigene Eigenschaften

Das properties-Objekt ermöglicht es dir, eigene Daten zu übergeben, die mit deiner Kontakteigenschaften-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:

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,
      },
    },
  });
});

CRM

Webhooks

Kalender-Integrationen

Automatisierungsplattformen

Eigene Integrationen

Überblick

Einrichtung

Anfrage

Signaturprüfung

Antwort

Unbekannter Anrufer

Eigene Eigenschaften

Fehlerbehandlung

Beispielimplementierung

​Überblick

​Einrichtung

​Anfrage

​Signaturprüfung

​Antwort

​Unbekannter Anrufer

​Eigene Eigenschaften

​Fehlerbehandlung

​Beispielimplementierung

Überblick

Einrichtung

Anfrage

Signaturprüfung

Antwort

Unbekannter Anrufer

Eigene Eigenschaften

Fehlerbehandlung

Beispielimplementierung