Konfigurieren Sie die intelligente Anrufweiterleitung für eine gemeinsam genutzte Rufnummer, damit Anrufende mithilfe des Widgets „Weiterleiten an (über API)“ in einem Anrufablauf effizient mit ihrer Kontaktperson verbunden werden. Die Authentifizierung erfolgt über Zendesk OAuth.

 

Hinweis: Zendesk stellt API-Token als Authentifizierungsmethode ein. Dieser Artikel verwendet OAuth als Ersatzmethode. Wenn Sie für diese Konfiguration derzeit ein API-Token verwenden, lesen Sie unten den Abschnitt „Warum in diesem Artikel OAuth anstelle eines API-Tokens verwendet wird“.
Hinweis: Im Video-Tutorial wird möglicherweise die vorherige Version des Abschnitts „Antwort testen“ gezeigt. Maßgeblich sind stets die schriftlichen Schritte in diesem Artikel, da sie die aktuellsten Anweisungen enthalten.

In diesem Leitfaden erfahren Sie: 

  • Warum in diesem Artikel OAuth anstelle eines API-Tokens verwendet wird.

  • Wie das Widget „Weiterleiten an (über API)“ die Effizienz und das Kundenerlebnis verbessert.
  • Wie Sie die intelligente Anrufweiterleitung an den Eigentümer des Zendesk-Kontakts einrichten.
    • Schritt 1: Benutzerdefiniertes Nutzerfeld in Zendesk erstellen
    • Schritt 2: Vertraulichen OAuth-Client in Zendesk erstellen
    • Schritt 3: Widget „Weiterleiten an (über API)“ im Anrufablauf-Editor konfigurieren
    • Schritt 4: Konfiguration testen
Hinweis: Das Widget „Weiterleiten an (über API)“ ist nur im Professional-Abonnement verfügbar. Wenn Sie kein Professional-Abonnement haben, wenden Sie sich an Ihren Customer Success Manager (CSM).

Warum in diesem Artikel OAuth anstelle eines API-Tokens verwendet wird

Zendesk schafft API-Token als Authentifizierungsmethode für Support-API-Anfragen schrittweise ab und setzt stattdessen auf OAuth. Bestehende API-Token funktionieren während eines Übergangszeitraums weiterhin, werden von Zendesk jedoch letztlich vollständig deaktiviert.

Achtung: Wenn diese Weiterleitung bei Ihnen bereits mit einem API-Token funktioniert, warten Sie nicht, bis sie nicht mehr funktioniert. Richten Sie die OAuth-Konfiguration in einem zweiten Widget „Weiterleiten an (über API)“ ein, prüfen Sie, ob sie funktioniert, und stellen Sie erst dann Ihr produktives Widget um. Die Schritte für die Umstellung finden Sie unten unter „Produktivschaltung“.

Das Widget „Weiterleiten an (über API)“ authentifiziert sich bei Zendesk mithilfe des OAuth-Client-Credentials-Flows. Aircall fordert mit Ihrer Client-ID und Ihrem Client-Secret ein Zugriffstoken von Ihrem Zendesk-Account an und sendet dieses Token anschließend als Authorization: Bearer-Header an die Zendesk-API. Aircall speichert das Token zwischen und fordert nach dessen Ablauf automatisch ein neues an. Daher muss kein Token manuell ausgetauscht werden.

Hinweis: Den genauen Zeitplan von Zendesk für die Einstellung finden Sie in der Zendesk-Ankündigung zur Entfernung von API-Token.
 

Wie das Widget „Weiterleiten an (über API)“ die Effizienz und das Kundenerlebnis verbessert

Die intelligente Anrufweiterleitung für eine gemeinsam genutzte Rufnummer bietet erhebliche Vorteile und verbessert die Effizienz, Genauigkeit und das Kundenerlebnis. Durch die intelligente Weiterleitung eingehender Anrufe anhand von CRM-Daten stellt sie sicher, dass alle Anrufenden schnell mit dem jeweils am besten geeigneten Agenten verbunden werden. Dadurch verkürzen sich die Wartezeiten und die Lösungsquoten beim ersten Anruf verbessern sich.

Ein häufiger Anwendungsfall für das Aircall-Widget „Weiterleiten an (über API)“ in einem Anrufablauf besteht darin, eingehende Anrufe von VIP-Kunden direkt an den Eigentümer ihres Zendesk-Kontakts (den zuständigen Kundensupport-Agenten) weiterzuleiten. So wird verhindert, dass das gesamte Team durch nicht zugehörige Kundenanrufe unterbrochen wird. Außerdem müssen Anrufende nicht in die Warteschleife gesetzt werden, während sie an den ihnen zugewiesenen Agenten weitergeleitet werden.

Intelligente Anrufweiterleitung an den Eigentümer des Zendesk-Kontakts einrichten

Schritt 1: Benutzerdefiniertes Feld in Zendesk erstellen

Achtung: Dieser Schritt setzt Kenntnisse zu benutzerdefinierten Zendesk-Feldern und Authentifizierungsmethoden voraus.

Erstellen Sie zunächst in Zendesk eine benutzerdefinierte Eigenschaft, in der die E-Mail-Adresse des Kontakteigentümers gespeichert wird.

  1. Navigieren Sie im Zendesk Admin Center zu nicht verfügbar → Konfiguration → Nutzerfelder und wählen Sie Feld hinzufügen aus.

    • Feldtyp: Text

    • Anzeigename: E-Mail-Adresse des Eigentümers

    • Feldschlüssel: owner_email

    Screenshot 2024-11-04 at 7.17.32 PM.png

  2. Das Feld wird automatisch allen Endnutzerprofilen hinzugefügt. Sobald es erstellt wurde und im Endnutzerprofil sichtbar ist, tragen Sie dort eine E-Mail-Adresse ein. Sie benötigen diese später, um im Widget „Weiterleiten an (über API)“ die Gültigkeit des Pfads zu testen.

    Screenshot 2024-11-04 at 7.13.45 PM.png
Hinweis: Die eingegebene E-Mail-Adresse muss mit der E-Mail-Adresse eines vorhandenen Aircall-Nutzers übereinstimmen. Andernfalls kann der Anruf nicht an diese Person weitergeleitet werden.

Schritt 2: Vertraulichen OAuth-Client in Zendesk erstellen

Achtung: Die Gewährung von Client-Anmeldedaten ist nur für vertrauliche OAuth-Clients verfügbar. Ein öffentlicher Client kann für diese Einrichtung nicht verwendet werden. Zum Erstellen eines OAuth-Clients sind Zendesk-Adminrechte erforderlich.
  1. Gehen Sie im Zendesk Admin Center zu Apps und Integrationen > APIs > OAuth-Clients und klicken Sie dann auf OAuth-Client hinzufügen.
  2. Füllen Sie die Felder aus:
    • Name: ein beliebiger Name, zum Beispiel „Aircall – Weiterleiten an (über API)“
    • Kennung: wird automatisch anhand des Namens ausgefüllt. Dieser Wert ist Ihre Client-ID. Sie können ihn bei Bedarf ändern.
    • Client-Typ: Vertraulich. Dies ist erforderlich.
    • Weiterleitungs-URLs: Die Gewährung von Client-Anmeldedaten verwendet diesen Wert nicht. Wenn sich das Formular ohne Angabe einer URL nicht speichern lässt, geben Sie eine absolute HTTPS-URL wie https://localhost ein.
    • Bereiche: optional. Wenn Sie dieses Feld leer lassen, kann der Client jeden Bereich anfordern. Wenn Sie einen Wert festlegen, dient er als Obergrenze: Das Widget kann keinen Bereich anfordern, der nicht in dieser Liste enthalten ist. Geben Sie in diesem Fall den Bereich an, den Sie in Schritt drei im Widget eintragen.
    • Token ablaufen lassen: Sie können diese Einstellung unverändert lassen. Bei OAuth-Clients, die am oder nach dem 30. April 2026 erstellt wurden, ist das Kontrollkästchen deaktiviert, da die von diesen Clients ausgestellten Token bereits standardmäßig ablaufen.
  3. Klicken Sie auf Speichern. Die Seite wird aktualisiert und das Feld „Geheimnis“ wird angezeigt.
  4. Kopieren Sie die Kennung und das Geheimnis und bewahren Sie beide an einem sicheren Ort auf.
 
Achtung: Das Geheimnis wird nur einmal vollständig angezeigt. Nachdem Sie die Seite verlassen haben, sind nur noch die ersten neun Zeichen sichtbar. Falls Sie es verlieren, müssen Sie einen neuen OAuth-Client erstellen.
 
Achtung: Aktionen, die mit einem Client-Anmeldedaten-Token ausgeführt werden, werden dem Zendesk-Nutzer zugeschrieben, der den OAuth-Client erstellt hat – normalerweise einem Admin. Dies wirkt sich auf Ihre Audit-Protokolle aus. Wenn dieser Nutzer später gelöscht oder herabgestuft wird oder anderweitig die zum Verwalten von OAuth-Clients erforderlichen Berechtigungen verliert, funktionieren die von diesem Client ausgestellten Token nicht mehr und diese Weiterleitung schlägt fehl. Falls einer dieser Punkte für Sie relevant ist, erstellen Sie den OAuth-Client über ein dediziertes Dienstkonto, bevor Sie fortfahren.

Schritt drei: Widget „Weiterleiten an (über API)“ im Anrufablauf-Editor einrichten

Achtung: Dieser Schritt setzt Kenntnisse der Zendesk REST API und von Anrufabläufen voraus.

  1. Gehen Sie zu Aircall Dashboard > Rufnummern und öffnen Sie die zu konfigurierende Rufnummer mit dem Anrufablauf.

  • Wichtig: Die Aircall-Nutzer, an die Anrufe über die API weitergeleitet werden, müssen der Anrufablaufkonfiguration nicht zugewiesen sein. Wenn sie zugewiesen sind und den weitergeleiteten Anruf verpassen, erhalten sie eine Benachrichtigung über einen verpassten Anruf in ihrer To-do-Liste. Sind sie der Rufnummer jedoch nicht zugewiesen, erhalten sie diese Benachrichtigungen nicht.

  1. Navigieren Sie zu der Rufnummer, für die Sie das Widget „Weiterleiten an (über API)“ konfigurieren möchten. Fügen Sie das Widget „Weiterleiten an (über API)“ an der gewünschten Stelle Ihrer Anrufablaufkonfiguration hinzu, um den Widget-Editor zu öffnen.

  2. Legen Sie für Authentifizierung den Wert OAuth fest und klicken Sie dann auf Anmeldedaten festlegen. Füllen Sie das Anmeldedatenformular wie folgt aus:

    Anmelde-URL https://MyDomainName.zendesk.com/oauth/tokens (ersetzen Sie MyDomainName durch Ihre Zendesk-Subdomain; verwenden Sie Ihre zentrale Zendesk-Subdomain und keine Domain mit Hostzuordnung)
    Client-IDDie Kennung Ihres OAuth-Clients
    Client-GeheimnisDas Geheimnis Ihres OAuth-Clients
    Bereich users:read read als Ausgangspunkt. Zendesk veröffentlicht keine Zuordnung von Bereichen zu Endpunkten. Betrachten Sie dies daher als Ausgangspunkt und bestätigen Sie die Angabe mit dem Test in Schritt vier. Wenn der Test einen Bereichsfehler zurückgibt, nennt Zendesk die erforderlichen Bereiche. Geben Sie genau diese ein.
  • Einige Tipps zum Einrichten von OAuth:
    • Wählen Sie zuerst den Wert für „Authentifizierung“ aus und geben Sie anschließend die Anmeldedaten ein. Wenn Sie die Auswahl für „Authentifizierung“ ändern, werden alle bereits im Widget gespeicherten Anmeldedaten gelöscht und müssen erneut eingegeben werden.
    • Wenn im OAuth-Anmeldedatenformular kein Feld „Bereich“ angezeigt wird, aktualisieren Sie Ihr Aircall Dashboard. Das Feld „Bereich“ ist für Zendesk erforderlich. Ohne dieses Feld lehnt Zendesk die Token-Anfrage ab.
    • Der Bereich ist eine durch Leerzeichen getrennte Liste. Verwenden Sie möglichst den kleinsten funktionierenden Satz. Beobachtungen zufolge verlangt Zendesk zusätzlich zum ressourcenspezifischen Bereich einen allgemeinen Bereich „read“. Daher wird oben „users:read read“ vorgeschlagen.

  1. Kehren Sie zum Widget-Editor zurück und vervollständigen Sie die Anfragekonfiguration:

    • URL: https://MyDomainName.zendesk.com/api/v2/users/search.json?query={{callerNumber}}
      (Ersetzen Sie „MyDomainName“ durch den tatsächlichen Namen Ihrer Zendesk-Domain.)

    • Methode: GET

  2. Konfigurieren Sie die Antworteinstellungen wie folgt:

    • Antworttyp: Nutzer:in (ID oder E-Mail-Adresse)

    • Pfad: users[0].user_fields.owner_email

Schritt 4: Konfiguration testen

Führen Sie im dafür vorgesehenen Feld Antwort testen einen Test durch:

  • Geben Sie eine gültige Rufnummer im internationalen E.164-Format ein.

  • Stellen Sie sicher, dass eine JSON-Nutzlast zurückgegeben wird.

  • Vergewissern Sie sich, dass der Pfad gültig ist, um den Wert zu finden, der zur Weiterleitung des eingehenden Anrufs verwendet wird.

  • Prüfen Sie, ob die E-Mail-Adresse des vorhandenen Kontakts mit der E-Mail-Adresse eines vorhandenen Aircall-Nutzers übereinstimmt.

Screenshot 2025-09-16 at 7.08.50 PM.png
Tipp: Passen Sie die Klingeleinstellungen direkt unter dem Testfeld an Ihre Geschäftsabläufe an.

 Sie können nun mit dem Testen eingehender Anrufe für die intelligente Anrufweiterleitung an den Eigentümer des Zendesk-Kontakts über das Widget „Ring-to (via API)“ beginnen.

Live-Schaltung

Sobald Ihre Tests abgeschlossen sind und die Weiterleitung wie erwartet funktioniert, müssen Sie in Zendesk das Feld „E-Mail-Adresse des Eigentümers“ für jedes Endnutzerprofil ausfüllen, für das Anrufe automatisch weitergeleitet werden sollen.

Wenn Sie dieses Widget bisher mit einem API-Token authentifiziert haben, stellen Sie Ihr Live-Widget jetzt auf die OAuth-Anmeldedaten um. Entfernen Sie das alte API-Token aus dem Zendesk Admin Center, sobald Sie bestätigt haben, dass die OAuth-Konfiguration funktioniert.

Fehlerbehebung

SymptomUrsache und Lösung
Fehler beim Anfordern des Zugriffstokens oder HTTP 401 bei der SucheDie Anmeldedaten wurden abgelehnt. Vergewissern Sie sich, dass der OAuth-Client „Vertraulich“ ist und die Client-ID exakt mit der Kennung übereinstimmt. Wenn das Secret erneut kopiert wurde, nachdem Sie die Seite im Admin Center verlassen hatten, ist es auf neun Zeichen gekürzt. Erstellen Sie einen neuen Client und verwenden Sie das vollständige Secret.
Ein einzelner Test oder Anruf schlägt fehl und derselbe Test ist unmittelbar danach erfolgreichDies kann genau dann auftreten, wenn ein zwischengespeichertes Zugriffstoken abläuft und erneuert wird. Wiederholen Sie den Test. Wenn dies nicht nur gelegentlich, sondern regelmäßig auftritt, behandeln Sie es als tatsächliches Problem mit den Anmeldedaten oder dem Geltungsbereich und gehen Sie die folgenden Zeilen durch.
{"error":"Forbidden","description":"You are missing the following required scopes: ..."}Das Token wurde ausgestellt, verfügt aber nicht über den vom Endpunkt benötigten Geltungsbereich. Bearbeiten Sie die OAuth-Anmeldedaten des Widgets und legen Sie für „Geltungsbereich“ die in der Fehlermeldung genannten Geltungsbereiche fest.
HTTP 400 mit invalid_scope Der vom Widget angeforderte Geltungsbereich liegt außerhalb der Liste „Geltungsbereiche“, die für den OAuth-Client in Zendesk konfiguriert ist. Fügen Sie den Geltungsbereich entweder zu den zulässigen Geltungsbereichen des Clients hinzu oder ändern Sie den Geltungsbereich des Widgets so, dass er innerhalb dieser bleibt.
Anmeldedaten scheinen gelöscht worden zu seinDurch Ändern der Authentifizierungsauswahl werden die gespeicherten Anmeldedaten gelöscht. Geben Sie sie nach Auswahl der Methode erneut ein.
Der Test gibt eine Nutzlast zurück, aber der Anruf wird nicht weitergeleitetDer Wert im konfigurierten Pfad muss einem vorhandenen Aircall-Nutzer entsprechen. Vergewissern Sie sich, dass der Wert „E-Mail-Adresse des Eigentümers“ im Zendesk-Profil mit der E-Mail-Adresse eines Aircall-Nutzers übereinstimmt.
Die Weiterleitung hat zuvor funktioniert und wurde ohne Konfigurationsänderung beendetVergewissern Sie sich, dass der Zendesk-Nutzer, der den OAuth-Client erstellt hat, weiterhin existiert und weiterhin berechtigt ist, OAuth-Clients zu verwalten. Tokens mit Client-Anmeldedaten agieren im Namen dieses Nutzers und funktionieren nicht mehr, wenn er diesen Zugriff verliert.

Fachdienstleistungen

Wenn Sie zusätzliche Hilfe bei der Implementierung dieser Konfiguration für die intelligente Anrufweiterleitung benötigen oder mehr über ähnliche Automatisierungen zur Verbesserung Ihrer Abläufe erfahren möchten, wenden Sie sich an unser Kundenerfolgsteam, um einen Termin mit unseren technischen Beratern zu vereinbaren.