Zum Hauptinhalt springen

​
Ü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

  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: 
{
  "event": "contact_lookup",
  "phone_number": "+14155551234"
}
FeldTypBeschreibung
eventstringImmer "contact_lookup"
phone_numberstringDie Telefonnummer des Anrufers 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
    }
  }
}
FeldTypErforderlichBeschreibung
first_namestringJaVorname des Kontakts (1–50 Zeichen)
last_namestringJaNachname des Kontakts (1–50 Zeichen)
salutationstringNeinAnrede oder Titel (z.B. „Herr”, „Frau”, „Dr.”)
emailstringNeinE-Mail-Adresse des Kontakts
external_idstringNeinDie Kennung des Kontakts in deinem System. Wenn ein Kontakt mit dieser ID bereits existiert, wird er aktualisiert statt ein Duplikat zu erstellen.
external_urlstringNeinEine URL zum Kontakt in deinem System
phone_numberstringNeinDie Telefonnummer des Kontakts (Standard: die Nummer des Anrufers)
propertiesobjectNeinEigene 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,
      },
    },
  });
});