Aircall Help Center | Smartflows-Widgets: Technische Dokumentation zu „Ring to (via API)”

Das Widget intelligente Anrufweiterleitung: Ring to (via 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 werden soll.

Dieses Widget bietet leistungsstarke und flexible Funktionen für dynamische Anrufweiterleitung, indem es Aircall mit Drittsystemen wie CRMs oder Helpdesks verbindet.

Achtung: Das Widget Ring to (via API) ist nur im Professional-Tarif verfügbar. Für ein Upgrade wenden Sie sich an Ihre:n Aircall Account Manager:in.

Voraussetzungen

Vor der Konfiguration des Widgets sicherstellen, dass die folgenden Anforderungen erfüllt sind.

Authentifizierungsdaten

Die Authentifizierungsmethode hängt von der externen Plattform ab, deren Daten Sie abrufen möchten. Unterstützte Methoden sind unter anderem:

Basic Authentication
Bearer Token
API-Schlüssel
OAuth

Beispiel (Aircall API):

Navigieren Sie im Aircall Dashboard zu Integrations & API > API-Schlüssel.
Erstellen Sie einen neuen API-Schlüssel.
Speichern Sie sowohl die API-Schlüssel-ID als auch das Token.
Gehen Sie in der Konfiguration des Widgets Ring to (via API) zu Zugangsdaten 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 verstehen.

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.

Kenntnisse in JSON

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 das Team von Aircall Fachdienstleistungen Beratung sowie Unterstützung bei der Implementierung bereitstellen.

Hinweise zur Verwendung

Das Widget Ring to (via API) ermöglicht eine dynamische („smarte“) Anrufweiterleitung auf Basis externer Daten. Es kann jedes System abfragen, das REST-APIs und Standard-Authentifizierungsmethoden unterstützt.

Hinweis: Anfragen von Ring to (via API) laufen nach 10 Sekunden ab. Stellen Sie sicher, dass Ihr Endpunkt innerhalb dieses Zeitlimits antwortet, da das Widget andernfalls das Weiterleitungsziel möglicherweise nicht abrufen kann.

Die API-Antwort muss Daten in einem Format zurückgeben, das Aircall für die Weiterleitung interpretieren kann. Unterstützte Antworttypen sind:

Antworttyp	Beschreibung
Nutzer:in	Leitet an eine bestimmte Agentin bzw. einen bestimmten Agenten weiter, und zwar mithilfe der Aircall Nutzer-ID oder E-Mail-Adresse.
Team	Leitet an ein bestimmtes Aircall Team weiter, und zwar mithilfe seiner Team-ID.
Aircall-Nummer	Leitet intern an eine andere Aircall-Nummer weiter, und zwar mithilfe ihrer Nummern-ID.
Externe Nummer	Leitet extern an eine Telefonnummer weiter (muss im internationalen E.164-Format vorliegen).
Dynamisches Ziel (ID)	Ermöglicht Ihrer externen API, sowohl den Zieltyp als auch die Ziel-ID dynamisch festzulegen.

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

Pfad zum Zieltyp (user, team, number oder external)
Pfad zum Zielwert (die eindeutige ID des Ziels)

Hinweis: Bei Antworten mit dynamischem Ziel akzeptiert das Widget nur die folgenden Werte für den Zieltyp: agent, team, internal und external.

Wenn das aufgelöste Ziel ein Team ist, gelten die Standard-Klingelregeln. Wenn es sich um eine:n Nutzer:in oder eine Nummer handelt, gelten diese Regeln nicht.

Jede erweiterte Logik (z. B. bedingte Weiterleitung, Priorisierung) muss in Ihrem externen System verarbeitet werden, bevor die API-Antwort zurückgegeben wird.

Konfigurationsschritte

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

Schritte:

Fügen Sie im Editor von Smartflows ein Widget Ring to (via API) hinzu.
Wählen Sie die HTTP-Methode (GET oder POST) je nach dem API-Bereich aus, den Sie verwenden möchten.
- Beispiel: Wenn Sie den Endpunkt Search Calls der Aircall API verwenden, wählen Sie GET.
Geben Sie die API-URL ein, zum Beispiel:
```
https://api.aircall.io/v1/calls/search?order=desc&phone_number={{callerNumber}}
```
Dadurch werden die neuesten Anrufe gesucht, die der Telefonnummer der anrufenden Person zugeordnet sind.
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 Aircall API-Dokumentation.

Antwortkonfiguration

Legen Sie im Abschnitt Antwortkonfiguration fest, wie die API-Antwort geparst wird, um das Weiterleitungsziel zu bestimmen.

Unterstützte Antworttypen:

Nutzer:in (ID oder E-Mail)
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 mit dynamischem Ziel:

{
  "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 ist, werden die Klingelregeln entsprechend angewendet.

Konfiguration testen

Verwenden Sie das Feld „Test response“, um API-Anfragen zu simulieren und zu bestätigen, dass Ihre 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 Anfrage-Textkörper verwendet wird. Wenn Sie den Test ausführen, ersetzt das Widget diese Variablen und zeigt die geparsten Ergebnisse an.

Tritt ein Fehler auf, finden Sie im Abschnitt Errors der Aircall API-Dokumentation Hinweise zur Fehlerbehebung.

Klingeleinstellungen

Passen Sie nach der Konfiguration und dem Testen Ihrer API-Integration die Klingeleinstellungen an, um festzulegen, wie Anrufe verteilt werden. Diese Einstellungen funktionieren genauso wie im standardmäßigen Widget Ring to.

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

Tipp: Wenn Sie diese Funktion nutzen möchten, aber nicht über das nötige technische Fachwissen verfügen, wenden Sie sich an unser Account-Management-Team. Dieses stellt den Kontakt zu unserem technischen Team her, um Unterstützung und Implementierungsberatung bereitzustellen.

Dieses Widget bietet leistungsstarke und flexible Funktionen für dynamische Anrufweiterleitung, indem es Aircall mit Drittsystemen wie CRMs oder Helpdesks verbindet.

Achtung: Das Widget Ring to (via API) ist nur im Professional-Tarif verfügbar. Für ein Upgrade wenden Sie sich an Ihre:n Aircall Account Manager:in.

Voraussetzungen

Vor der Konfiguration des Widgets sicherstellen, dass die folgenden Anforderungen erfüllt sind.

Authentifizierungsdaten

Die Authentifizierungsmethode hängt von der externen Plattform ab, deren Daten Sie abrufen möchten. Unterstützte Methoden sind unter anderem:

Basic Authentication
Bearer Token
API-Schlüssel
OAuth

Beispiel (Aircall API):

Navigieren Sie im Aircall Dashboard zu Integrations & API > API-Schlüssel.
Erstellen Sie einen neuen API-Schlüssel.
Speichern Sie sowohl die API-Schlüssel-ID als auch das Token.
Gehen Sie in der Konfiguration des Widgets Ring to (via API) zu Zugangsdaten 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 verstehen.

Kenntnisse in JSON

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 das Team von Aircall Fachdienstleistungen Beratung sowie Unterstützung bei der Implementierung bereitstellen.

Hinweise zur Verwendung

Hinweis: Anfragen von Ring to (via API) laufen nach 10 Sekunden ab. Stellen Sie sicher, dass Ihr Endpunkt innerhalb dieses Zeitlimits antwortet, da das Widget andernfalls das Weiterleitungsziel möglicherweise nicht abrufen kann.

Die API-Antwort muss Daten in einem Format zurückgeben, das Aircall für die Weiterleitung interpretieren kann. Unterstützte Antworttypen sind:

Antworttyp	Beschreibung
Nutzer:in	Leitet an eine bestimmte Agentin bzw. einen bestimmten Agenten weiter, und zwar mithilfe der Aircall Nutzer-ID oder E-Mail-Adresse.
Team	Leitet an ein bestimmtes Aircall Team weiter, und zwar mithilfe seiner Team-ID.
Aircall-Nummer	Leitet intern an eine andere Aircall-Nummer weiter, und zwar mithilfe ihrer Nummern-ID.
Externe Nummer	Leitet extern an eine Telefonnummer weiter (muss im internationalen E.164-Format vorliegen).
Dynamisches Ziel (ID)	Ermöglicht Ihrer externen API, sowohl den Zieltyp als auch die Ziel-ID dynamisch festzulegen.

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

Pfad zum Zieltyp (user, team, number oder external)
Pfad zum Zielwert (die eindeutige ID des Ziels)

Hinweis: Bei Antworten mit dynamischem Ziel akzeptiert das Widget nur die folgenden Werte für den Zieltyp: agent, team, internal und external.

Wenn das aufgelöste Ziel ein Team ist, gelten die Standard-Klingelregeln. Wenn es sich um eine:n Nutzer:in oder eine Nummer handelt, gelten diese Regeln nicht.

Jede erweiterte Logik (z. B. bedingte Weiterleitung, Priorisierung) muss in Ihrem externen System verarbeitet werden, bevor die API-Antwort zurückgegeben wird.

Konfigurationsschritte

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

Schritte:

Fügen Sie im Editor von Smartflows ein Widget Ring to (via API) hinzu.
Wählen Sie die HTTP-Methode (GET oder POST) je nach dem API-Bereich aus, den Sie verwenden möchten.
- Beispiel: Wenn Sie den Endpunkt Search Calls der Aircall API verwenden, wählen Sie GET.
Geben Sie die API-URL ein, zum Beispiel:
```
https://api.aircall.io/v1/calls/search?order=desc&phone_number={{callerNumber}}
```
Dadurch werden die neuesten Anrufe gesucht, die der Telefonnummer der anrufenden Person zugeordnet sind.
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 Aircall API-Dokumentation.

Antwortkonfiguration

Legen Sie im Abschnitt Antwortkonfiguration fest, wie die API-Antwort geparst wird, um das Weiterleitungsziel zu bestimmen.

Unterstützte Antworttypen:

Nutzer:in (ID oder E-Mail)
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 mit dynamischem Ziel:

{
  "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 ist, werden die Klingelregeln entsprechend angewendet.

Konfiguration testen

Verwenden Sie das Feld „Test response“, um API-Anfragen zu simulieren und zu bestätigen, dass Ihre konfigurierten Pfade die richtigen Werte zurückgeben.

Beispiel für eine Testeingabe:

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

Tritt ein Fehler auf, finden Sie im Abschnitt Errors der Aircall API-Dokumentation Hinweise zur Fehlerbehebung.

Klingeleinstellungen

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

Tipp: Wenn Sie diese Funktion nutzen möchten, aber nicht über das nötige technische Fachwissen verfügen, wenden Sie sich an unser Account-Management-Team. Dieses stellt den Kontakt zu unserem technischen Team her, um Unterstützung und Implementierungsberatung bereitzustellen.