Zum Hauptinhalt gehen
Anfragen einreichen oder anzeigen
English (United Kingdom) Español (España) Français (France) Italiano (Italia)

Smartflows-Widgets: Technische Dokumentation zu „Anrufen bei“ (über API)

Das Widget intelligente Anrufweiterleitung: Weiterleiten an (über API) verwendet eine API-Antwort, um anhand von außerhalb von Aircall gespeicherten Daten zu bestimmen, an welche:n Aircall-Nutzer:in, welches Team, welche interne Nummer oder welche externe Nummer ein Anruf weitergeleitet wird.

Dieses Widget bietet leistungsstarke und flexible Funktionen zur dynamischen Weiterleitung, indem es Aircall mit Drittsystemen wie CRMs oder Helpdesks verbindet.

ACHTUNG:
Das Widget Weiterleiten an (über API) ist nur im **Professional-Tarif** verfügbar. Wenden Sie sich für ein Upgrade an Ihre:n Aircall-Kundenbetreuer:in.

Voraussetzungen

Stellen Sie vor der Konfiguration des Widgets sicher, dass die folgenden Voraussetzungen erfüllt sind.

Anmeldedaten für die Authentifizierung

Die Authentifizierungsmethode hängt von der externen Plattform ab, deren Daten Sie abrufen möchten. Folgende Methoden werden unterstützt:

  • Basisauthentifizierung
  • Bearer-Token
  • API-Schlüssel
  • OAuth

Beispiel (Aircall API):

  1. Navigieren Sie im Aircall Dashboard zu Integrationen > API-Schlüssel.
  2. Erstellen Sie einen neuen API-Schlüssel.
  3. Speichern Sie sowohl die API-Schlüssel-ID als auch das Token.
  4. Gehen Sie in der Konfiguration des Widgets Weiterleiten an (über API) zu Anmeldedaten und legen Sie Folgendes fest:
    • Benutzername = API-Schlüssel-ID
    • Passwort = API-Token

Weitere Informationen zum Auffinden Ihres Aircall API-Schlüssels finden Sie in unserem Artikel Wo finde ich meinen Aircall API-Schlüssel?.

Kenntnisse der Plattform-API

Sie müssen die Struktur und Endpunkte der öffentlichen API der externen Plattform kennen.

Während Wo finde ich meinen Aircall API-Schlüssel? die Aircall API als Beispiel verwendet, können Sie auch Plattformen wie HubSpot, Salesforce, Zendesk, Intercom, Pipedrive oder interne CRMs verwenden.

JSON-Kenntnisse

Das Widget verwendet JSON (JavaScript Object Notation), um Daten mit APIs auszutauschen. Sie sollten mit grundlegenden JSON-Strukturen vertraut sein, um Datenpfade korrekt zu konfigurieren.

TIPP:
Wenn Sie Unterstützung bei der Konfiguration des Widgets benötigen, kann unser Technikteam Sie bei der Beratung und Implementierung unterstützen. Wenden Sie sich an unser Account-Management-Team.

Hinweise zur Verwendung

Das Widget Weiterleiten an (über API) ermöglicht eine dynamische („intelligente“) Anrufweiterleitung auf Grundlage externer Daten. Es kann jedes System abfragen, das REST-APIs und Standardauthentifizierungsmethoden unterstützt.

HINWEIS:
Anfragen von Weiterleiten an (über API) werden nach 10 Sekunden wegen Zeitüberschreitung abgebrochen. Stellen Sie sicher, dass Ihr Endpunkt innerhalb dieses Zeitlimits antwortet. Andernfalls kann das Widget das Weiterleitungsziel möglicherweise nicht abrufen.

Die API-Antwort muss Daten in einem Format zurückgeben, das Aircall für die Weiterleitung interpretieren kann. Folgende Antworttypen werden unterstützt:

Antworttyp Beschreibung
Nutzer:in Leitet anhand der Aircall-Nutzer-ID oder E-Mail-Adresse an eine:n bestimmte:n Agent:in weiter.
Team Leitet anhand der Team-ID an ein bestimmtes Aircall-Team weiter.
Aircall-Nummer Leitet anhand der Nummern-ID intern an eine andere Aircall-Nummer weiter.
Externe Nummer Leitet extern an eine Telefonnummer weiter (muss im internationalen E.164-Format angegeben sein).
Dynamisches Ziel (ID) Ermöglicht Ihrer externen API, sowohl den Zieltyp als auch die Ziel-ID dynamisch anzugeben.

Bei Verwendung von Dynamisches Ziel (ID) müssen Sie im Widget zwei JSON-Pfade definieren:

  • Pfad zum Zieltyp (Nutzer:in, Team, Nummer oder extern)
  • Pfad zum Zielwert (die eindeutige ID des Ziels)
HINWEIS:
Bei Antworten für ein dynamisches Ziel akzeptiert das Widget für den Zieltyp nur die folgenden Werte: agent, team, internal und external.

Wenn das ermittelte Ziel ein Team ist, gelten die standardmäßigen Klingelregeln. Wenn es sich um eine:n Nutzer:in oder eine Nummer handelt, gelten diese Regeln nicht.

Jede erweiterte Logik (z. B. bedingte Weiterleitung oder Priorisierung) muss vor der Rückgabe der API-Antwort in Ihrem externen System verarbeitet werden.

Konfigurationsschritte

Das Widget bestimmt anhand des konfigurierten API-Aufrufs, ob bei Nutzer:in, Team, Aircall-Nummer, Externe Nummer oder Dynamisches Ziel (ID) geklingelt wird.

Schritte:

  1. Fügen Sie im Smartflows-Editor ein Widget des Typs Weiterleiten an (über API) hinzu.
  2. Wählen Sie abhängig vom gewünschten API-Abschnitt die HTTP-Methode (GET oder POST) aus.
    • Beispiel: Wählen Sie bei Verwendung des Endpunkts Anrufe suchen der Aircall API GET aus.

  3. Geben Sie die API-URL ein, zum Beispiel:

    https://api.aircall.io/v1/calls/search?order=desc&phone_number={{callerNumber}}

    Damit wird nach den neuesten Anrufen gesucht, die mit der Telefonnummer des Anrufers verknüpft sind.

  4. Verwenden Sie Variablen wie callerNumber, targetNumber oder callUUID, um anrufspezifische Daten dynamisch in Ihre Anfrage einzufügen. Eine vollständige Liste der Abfrageparameter finden Sie in der Dokumentation der Aircall API.

Antwortkonfiguration

Definieren Sie im Abschnitt Antwortkonfiguration, wie die API-Antwort analysiert wird, um das Weiterleitungsziel zu bestimmen.

Unterstützte Antworttypen:

  • Nutzer:in (ID oder E-Mail-Adresse)
  • Team (ID)
  • Aircall-Nummer (intern)
  • Externe Nummer (E.164-Format)
  • Dynamisches Ziel (ID)

Beispiel für einen JSON-Pfad:

calls[0].user.id

Dieser Pfad verweist auf das erste Element im Array „calls“ und ruft die Nutzer-ID ab.

Beispiel für eine JSON-Antwort des dynamischen Ziels:

{
  "calls": [
    {
      "target_type": "team",
      "target_id": 12345
    }
  ]
}
  • Pfad zum Zieltyp: calls[0].target_type
  • Pfad zum Zielwert: calls[0].target_id

Wenn der Zieltyp Team lautet, werden die Anrufregeln entsprechend angewendet.

Konfiguration testen

Verwenden Sie das Feld „Testantwort“, um API-Anfragen zu simulieren und zu prüfen, ob die konfigurierten Pfade die richtigen Werte zurückgeben.

Beispiel für eine Testeingabe:

{
  "callerNumber": "+15551234567",
  "targetNumber": "+15557654321",
  "callUUID": "abcd-1234-efgh-5678",
  "lineId": 12345
}

Jeder Schlüssel im JSON entspricht einer Variablen, die in Ihrer URL oder Ihrem Anfragetext verwendet wird. Beim Ausführen des Tests ersetzt das Widget diese Variablen und zeigt die analysierten Ergebnisse an.

Wenn ein Fehler auftritt, finden Sie im Abschnitt Fehler der Aircall-API-Dokumentation Hinweise zur Fehlerbehebung.

Anrufeinstellungen

Nachdem Sie Ihre API-Integration konfiguriert und getestet haben, passen Sie die Anrufeinstellungen an, um festzulegen, wie Anrufe verteilt werden. Diese Einstellungen funktionieren genauso wie im standardmäßigen Widget Anruf weiterleiten an.

Weitere Informationen finden Sie in unserem Hilfe-Center-Artikel Übersicht über das Smartflows-Routing.

TIPP:
Wenn Sie diese Funktion nutzen möchten, Ihnen jedoch das technische Fachwissen fehlt, wenden Sie sich an unser Account-Management-Team. Dieses bringt Sie mit unserem technischen Team zusammen, das Sie bei der Implementierung unterstützt und berät.
Jordan W.