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

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

Dieses Widget bietet leistungsstarke und flexible dynamische Routing-Funktionen, indem es Aircall mit Drittanbietersystemen wie CRMs oder Helpdesks verbindet.

WICHTIG:
Das Ring to (via API)-Widget ist nur im **Professional-Tarif** verfügbar. Für ein Upgrade wenden Sie sich bitte an Ihren Aircall-Kundenbetreuer.

Voraussetzungen

Stellen Sie vor der Konfiguration des Widgets sicher, 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:

Basic Authentication
Bearer Token
API-Schlüssel
OAuth

Beispiel (Aircall API):

Navigieren Sie zu Integrationen & API > API-Schlüssel im Aircall-Dashboard.
Erstellen Sie einen neuen API-Schlüssel.
Speichern Sie sowohl die API-Schlüssel-ID als auch das Token.
Gehen Sie in der Ring to (via API)-Widget-Konfiguration zu Credentials 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 die 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: P:
Wenn Sie Hilfe bei der Konfiguration des Widgets benötigen, kann das Professional Services Team von Aircall Beratungs- und Implementierungsunterstützung bieten.

Hinweise zur Verwendung

Das Ring to (via API)-Widget ermöglicht ein dynamisches („smartes“) Anrufrouting basierend auf externen Daten. Es kann jede Plattform abfragen, die REST-APIs und Standard-Authentifizierungsmethoden unterstützt.

HINWEIS:
Anfragen, die vom Ring to (via API) gestellt werden, laufen nach 10 Sekunden ab. Stellen Sie sicher, dass Ihr Endpunkt innerhalb dieses Zeitlimits antwortet, sonst kann das Widget das Routing-Ziel möglicherweise nicht abrufen.

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

Antworttyp	Beschreibung
Benutzer	Leitet an einen bestimmten Agenten weiter, basierend auf seiner Aircall-Benutzer-ID oder E-Mail.
Team	Leitet an ein bestimmtes Aircall-Team weiter, basierend auf dessen Team-ID.
Aircall-Nummer	Leitet intern an eine andere Aircall-Nummer weiter, basierend auf deren Nummern-ID.
Externe Nummer	Leitet extern an eine Telefonnummer weiter (muss im internationalen E.164-Format sein).
Dynamisches Ziel (ID)	Ermöglicht es Ihrer externen API, sowohl den Zieltyp als auch die Ziel-ID dynamisch anzugeben.

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

Pfad zum Zieltyp (Benutzer, Team, Nummer oder extern)
Pfad zum Zielwert (die eindeutige ID des Ziels)

HINWEIS:
Für Antworten mit Dynamischem Ziel akzeptiert das Widget nur die folgenden Werte für den Zieltyp: user, team, internal und external.

Wenn das aufgelöste Ziel ein Team ist, gelten die Standardklingelregeln. Wenn es sich um einen Benutzer oder eine Nummer handelt, gelten diese Regeln nicht.

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

Konfigurationsschritte

Das Widget bestimmt basierend auf dem konfigurierten API-Aufruf, ob es an einen Benutzer, Team, Aircall-Nummer, Externe Nummer oder Dynamisches Ziel (ID) weiterleitet.

Schritte:

Fügen Sie im Smartflows-Editor ein Ring to (via API)-Widget hinzu.
Wählen Sie die HTTP-Methode (GET oder POST), abhängig vom API-Endpunkt, den Sie verwenden möchten.
- Beispiel: Wenn Sie den Search Calls-Endpunkt 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}}
```
Dies sucht nach den neuesten Anrufen, die mit der Telefonnummer des Anrufers verbunden sind.
Verwenden Sie Variablen wie callerNumber, targetNumber oder callUUID, um anrufbezogene Daten dynamisch in Ihre Anfrage einzufügen. Eine vollständige Liste der Abfrageparameter finden Sie in der Aircall API-Dokumentation.

Antwortkonfiguration

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

Unterstützte Antworttypen:

Benutzer (ID oder E-Mail)
Team (ID)
Aircall-Nummer (intern)
Externe Nummer (E.164-Format)
Dynamisches Ziel (ID)

Beispiel JSON-Pfad:

calls[0].user.id

Dieser Pfad verweist auf das erste Element im „calls“-Array und ruft die Benutzer-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.

Testen der Konfiguration

Verwenden Sie das Testantwortfeld, um API-Anfragen zu simulieren und zu bestätigen, dass Ihre konfigurierten Pfade die korrekten Werte zurückgeben.

Beispiel für Testeingaben:

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

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

Wenn ein Fehler auftritt, konsultieren Sie den Abschnitt Fehler in der Aircall API-Dokumentation für Hilfestellungen zur Fehlerbehebung.

Klingeleinstellungen

Nachdem Sie Ihre API-Integration konfiguriert und getestet haben, passen Sie die Klingeleinstellungen an, um zu definieren, wie Anrufe verteilt werden. Diese Einstellungen funktionieren genauso wie im Standard-Ring to-Widget.

Weitere Details finden Sie in unserem Help Center-Artikel Smartflows-Routing-Übersicht.

Tipp: P:
Wenn Sie Hilfe bei der Konfiguration oder beim Testen Ihrer API-Einrichtung benötigen, kann das Professional Services Team von Aircall praktische Unterstützung bei Implementierung und Fehlerbehebung bieten.

Dieses Widget bietet leistungsstarke und flexible dynamische Routing-Funktionen, indem es Aircall mit Drittanbietersystemen wie CRMs oder Helpdesks verbindet.

WICHTIG:
Das Ring to (via API)-Widget ist nur im **Professional-Tarif** verfügbar. Für ein Upgrade wenden Sie sich bitte an Ihren Aircall-Kundenbetreuer.

Voraussetzungen

Stellen Sie vor der Konfiguration des Widgets sicher, 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:

Basic Authentication
Bearer Token
API-Schlüssel
OAuth

Beispiel (Aircall API):

Navigieren Sie zu Integrationen & API > API-Schlüssel im Aircall-Dashboard.
Erstellen Sie einen neuen API-Schlüssel.
Speichern Sie sowohl die API-Schlüssel-ID als auch das Token.
Gehen Sie in der Ring to (via API)-Widget-Konfiguration zu Credentials 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 die 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: P:
Wenn Sie Hilfe bei der Konfiguration des Widgets benötigen, kann das Professional Services Team von Aircall Beratungs- und Implementierungsunterstützung bieten.

Hinweise zur Verwendung

HINWEIS:
Anfragen, die vom Ring to (via API) gestellt werden, laufen nach 10 Sekunden ab. Stellen Sie sicher, dass Ihr Endpunkt innerhalb dieses Zeitlimits antwortet, sonst kann das Widget das Routing-Ziel möglicherweise nicht abrufen.

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

Antworttyp	Beschreibung
Benutzer	Leitet an einen bestimmten Agenten weiter, basierend auf seiner Aircall-Benutzer-ID oder E-Mail.
Team	Leitet an ein bestimmtes Aircall-Team weiter, basierend auf dessen Team-ID.
Aircall-Nummer	Leitet intern an eine andere Aircall-Nummer weiter, basierend auf deren Nummern-ID.
Externe Nummer	Leitet extern an eine Telefonnummer weiter (muss im internationalen E.164-Format sein).
Dynamisches Ziel (ID)	Ermöglicht es Ihrer externen API, sowohl den Zieltyp als auch die Ziel-ID dynamisch anzugeben.

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

Pfad zum Zieltyp (Benutzer, Team, Nummer oder extern)
Pfad zum Zielwert (die eindeutige ID des Ziels)

HINWEIS:
Für Antworten mit Dynamischem Ziel akzeptiert das Widget nur die folgenden Werte für den Zieltyp: user, team, internal und external.

Wenn das aufgelöste Ziel ein Team ist, gelten die Standardklingelregeln. Wenn es sich um einen Benutzer oder eine Nummer handelt, gelten diese Regeln nicht.

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

Konfigurationsschritte

Das Widget bestimmt basierend auf dem konfigurierten API-Aufruf, ob es an einen Benutzer, Team, Aircall-Nummer, Externe Nummer oder Dynamisches Ziel (ID) weiterleitet.

Schritte:

Fügen Sie im Smartflows-Editor ein Ring to (via API)-Widget hinzu.
Wählen Sie die HTTP-Methode (GET oder POST), abhängig vom API-Endpunkt, den Sie verwenden möchten.
- Beispiel: Wenn Sie den Search Calls-Endpunkt 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}}
```
Dies sucht nach den neuesten Anrufen, die mit der Telefonnummer des Anrufers verbunden sind.
Verwenden Sie Variablen wie callerNumber, targetNumber oder callUUID, um anrufbezogene Daten dynamisch in Ihre Anfrage einzufügen. Eine vollständige Liste der Abfrageparameter finden Sie in der Aircall API-Dokumentation.

Antwortkonfiguration

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

Unterstützte Antworttypen:

Benutzer (ID oder E-Mail)
Team (ID)
Aircall-Nummer (intern)
Externe Nummer (E.164-Format)
Dynamisches Ziel (ID)

Beispiel JSON-Pfad:

calls[0].user.id

Dieser Pfad verweist auf das erste Element im „calls“-Array und ruft die Benutzer-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.

Testen der Konfiguration

Verwenden Sie das Testantwortfeld, um API-Anfragen zu simulieren und zu bestätigen, dass Ihre konfigurierten Pfade die korrekten Werte zurückgeben.

Beispiel für Testeingaben:

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

Wenn ein Fehler auftritt, konsultieren Sie den Abschnitt Fehler in der Aircall API-Dokumentation für Hilfestellungen zur Fehlerbehebung.

Klingeleinstellungen

Weitere Details finden Sie in unserem Help Center-Artikel Smartflows-Routing-Übersicht.

Tipp: P:
Wenn Sie Hilfe bei der Konfiguration oder beim Testen Ihrer API-Einrichtung benötigen, kann das Professional Services Team von Aircall praktische Unterstützung bei Implementierung und Fehlerbehebung bieten.