Aircall Help Center | Smartflows-Widgets: Ring to (via API) technische Dokumentation

Das Widget Smart Routing: Ring to (via API) verwendet eine API-Antwort, um zu bestimmen, an welche:n Aircall Nutzer:in, welches Team, welche interne Nummer oder welche externe Nummer ein Anruf weitergeleitet wird, basierend auf Daten, die außerhalb von Aircall gespeichert sind.

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 plan verfügbar. Für ein Upgrade wenden Sie sich an Ihre:n Aircall Account Manager:in.

Voraussetzungen

Vor der Konfiguration des Widgets muss sichergestellt sein, dass die folgenden Anforderungen erfüllt sind.

Authentifizierungsdaten

Die Authentifizierungsmethode hängt von der externen Plattform ab, deren Daten Sie abrufen möchten. Zu den unterstützten Methoden gehören:

Basic Authentication
Bearer Token
API-Schlüssel
OAuth

Beispiel (Aircall API):

Gehen Sie im Aircall Dashboard zu Integrations & API > API keys.
Erstellen Sie einen neuen API-Schlüssel.
Speichern Sie sowohl die API key ID als auch das token.
Gehen Sie in der Konfiguration des Widgets Ring to (via API) zu Credentials und legen Sie Folgendes fest:
- Username = API key ID
- Password = API token

Weitere Informationen dazu, wo Sie Ihren Aircall API-Schlüssel finden, finden Sie in unserem Artikel Where to find my Aircall API Key.

Kenntnisse über die API der Plattform

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

Auch wenn Where to find my Aircall API Key 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) zum Datenaustausch mit APIs. 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 Technical team Beratung und Unterstützung bei der Implementierung anbieten. Wenden Sie sich dazu an unser Account Management team.

Hinweise zur Verwendung

Das Widget Ring to (via API) ermöglicht eine dynamische („intelligente“) 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) haben nach 10 Sekunden ein Timeout. 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. Zu den unterstützten Antworttypen gehören:

Antworttyp	Beschreibung
Nutzer:in	Leitet an eine:n bestimmte:n Agent:in weiter, und zwar anhand der Aircall User ID oder E-Mail-Adresse.
Team	Leitet an ein bestimmtes Aircall Team weiter, und zwar anhand seiner Team ID.
Aircall-Nummer	Leitet intern an eine andere Aircall-Nummer weiter, und zwar anhand ihrer Number ID.
Externe Nummer	Leitet extern an eine Telefonnummer weiter (muss im internationalen Format E.164 vorliegen).
Dynamisches Ziel (ID)	Ermöglicht es 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 (user, team, number oder external)
Pfad zum Zielwert (die eindeutige ID des Ziels)

Hinweis: Für Antworten mit Dynamic Target akzeptiert das Widget für den Zieltyp nur die folgenden Werte: 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 Smartflows-Editor ein Widget Ring to (via API) hinzu.
Wählen Sie die HTTP-Methode (GET oder POST) entsprechend dem API-Abschnitt, 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 wird nach den neuesten Anrufen gesucht, die mit der Telefonnummer der anrufenden Person verknüpft 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 Response configuration 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 (Format E.164)
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 User ID ab.

Beispiel für eine JSON-Antwort für Dynamic Target:

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

Beispieleingabe für den Test:

{
  "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 Request-Body 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 Standard-Widget Ring to.

Weitere Informationen finden Sie in unserem Hilfe-Center-Artikel Smartflows routing overview.

Tipp: Wenn Sie diese Funktion nutzen möchten, aber nicht über das nötige technische Fachwissen verfügen, kontaktieren Sie unser Account Management team. Das Team verbindet Sie mit unserem technischen Team für Support und Implementierungshinweise.

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 plan verfügbar. Für ein Upgrade wenden Sie sich an Ihre:n Aircall Account Manager:in.

Voraussetzungen

Vor der Konfiguration des Widgets muss sichergestellt sein, dass die folgenden Anforderungen erfüllt sind.

Authentifizierungsdaten

Die Authentifizierungsmethode hängt von der externen Plattform ab, deren Daten Sie abrufen möchten. Zu den unterstützten Methoden gehören:

Basic Authentication
Bearer Token
API-Schlüssel
OAuth

Beispiel (Aircall API):

Gehen Sie im Aircall Dashboard zu Integrations & API > API keys.
Erstellen Sie einen neuen API-Schlüssel.
Speichern Sie sowohl die API key ID als auch das token.
Gehen Sie in der Konfiguration des Widgets Ring to (via API) zu Credentials und legen Sie Folgendes fest:
- Username = API key ID
- Password = API token

Weitere Informationen dazu, wo Sie Ihren Aircall API-Schlüssel finden, finden Sie in unserem Artikel Where to find my Aircall API Key.

Kenntnisse über die API der Plattform

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

JSON-Kenntnisse

Das Widget verwendet JSON (JavaScript Object Notation) zum Datenaustausch mit APIs. 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 Technical team Beratung und Unterstützung bei der Implementierung anbieten. Wenden Sie sich dazu an unser Account Management team.

Hinweise zur Verwendung

Hinweis: Anfragen von Ring to (via API) haben nach 10 Sekunden ein Timeout. 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. Zu den unterstützten Antworttypen gehören:

Antworttyp	Beschreibung
Nutzer:in	Leitet an eine:n bestimmte:n Agent:in weiter, und zwar anhand der Aircall User ID oder E-Mail-Adresse.
Team	Leitet an ein bestimmtes Aircall Team weiter, und zwar anhand seiner Team ID.
Aircall-Nummer	Leitet intern an eine andere Aircall-Nummer weiter, und zwar anhand ihrer Number ID.
Externe Nummer	Leitet extern an eine Telefonnummer weiter (muss im internationalen Format E.164 vorliegen).
Dynamisches Ziel (ID)	Ermöglicht es 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 (user, team, number oder external)
Pfad zum Zielwert (die eindeutige ID des Ziels)

Hinweis: Für Antworten mit Dynamic Target akzeptiert das Widget für den Zieltyp nur die folgenden Werte: 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 Smartflows-Editor ein Widget Ring to (via API) hinzu.
Wählen Sie die HTTP-Methode (GET oder POST) entsprechend dem API-Abschnitt, 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 wird nach den neuesten Anrufen gesucht, die mit der Telefonnummer der anrufenden Person verknüpft 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 Response configuration 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 (Format E.164)
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 User ID ab.

Beispiel für eine JSON-Antwort für Dynamic Target:

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

Beispieleingabe für den Test:

{
  "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 Hilfe-Center-Artikel Smartflows routing overview.

Tipp: Wenn Sie diese Funktion nutzen möchten, aber nicht über das nötige technische Fachwissen verfügen, kontaktieren Sie unser Account Management team. Das Team verbindet Sie mit unserem technischen Team für Support und Implementierungshinweise.