SMS-Support für Anrufende mit dem Widget „Weiterleitung per API“ anbieten

Lange Wartezeiten gehören zu den schnellsten Möglichkeiten, Anrufende zu frustrieren. Statt Kund:innen in einer Warteschlange warten zu lassen oder abzuweisen, wenn alle Agenten beschäftigt sind, können Sie ihnen über Ihr Sprachmenü Support per SMS anbieten. Wenn Anrufende diese Option auswählen, sendet Aircall eine Textnachricht von einer Ihrer SMS-fähigen Rufnummern an sie. Sie können in ihrem eigenen Tempo antworten, und die Konversation landet im Aircall-Posteingang Ihrer Agenten, wo sie wie jede andere SMS-Konversation bearbeitet wird.

Dies ist in zwei häufigen Situationen hilfreich:

• Proaktive Auswahl: Bieten Sie SMS von Anfang an an, damit Anrufende, die Nachrichten bevorzugen, nie in der Warteschleife warten müssen.
• Überlauf, alle Agenten beschäftigt: Wenn kein Agent verfügbar ist, bieten Sie SMS als Möglichkeit an, dennoch Hilfe zu erhalten, statt nur in der Warteschlange zu warten oder aufzulegen.

Da SMS nur Anrufende in den Ländern erreichen, die von Ihrer sendenden Rufnummer abgedeckt werden, funktioniert dies am besten, wenn sich Ihre Anrufenden und Ihre Rufnummern im selben Markt befinden. Um Anrufenden überall Nachrichten anzubieten, können Sie im selben Zweig auch WhatsApp anbieten: Eine WhatsApp-fähige Rufnummer erreicht alle Anrufenden, die die App verwenden, unabhängig von ihrem Land. Siehe Anrufenden WhatsApp-Support über das Widget „Weiterleitung per API“ anbieten.

Hinweis: Bei dieser Einrichtung wird eine API-Anfrage innerhalb eines Anrufablaufs erstellt, einschließlich eines JSON-Texts und einer Basic-Authentifizierung. Sie müssen kein:e Entwickler:in sein, sollten aber mit detaillierten technischen Schritt-für-Schritt-Anleitungen zurechtkommen.

Funktionsweise

1. Ein:e Kund:in ruft Ihre Aircall-Rufnummer an und gelangt in Ihren Anrufablauf.
2. Die anrufende Person erreicht einen Punkt, an dem SMS angeboten wird – entweder als Menüoption („Drücken Sie die 1, um Hilfe per Textnachricht zu erhalten, statt zu warten“) oder als Überlaufzweig, der ausgelöst wird, wenn kein Agent verfügbar ist.
3. In diesem Zweig sendet das Widget Weiterleitung per API eine Anfrage an den Nachrichten-Endpunkt von Aircall. Darin wird angegeben, von welcher SMS-fähigen Rufnummer die Nachricht gesendet werden soll, welcher Text gesendet werden soll und an welche Rufnummer er gesendet werden soll (die eigene Rufnummer der anrufenden Person).
4. Die anrufende Person erhält die SMS und kann antworten. Ihre Antwort landet in derselben Konversation im Aircall-Posteingang und ist für Ihre Agenten sichtbar.
5. Der Anruf endet mit einer kurzen gesprochenen Bestätigung.

Achtung: Das Widget „Weiterleitung per API“ sendet die Anfrage, kann den Anruf jedoch nicht anhand der API-Antwort verzweigen. Alles nach dem Widget – eine Bestätigungsnachricht, das Beenden des Anrufs oder eine alternative Route – muss unabhängig davon erfolgen, ob die Nachricht tatsächlich gesendet wurde.

Bevor Sie beginnen

Stellen Sie vor Beginn sicher, dass die folgenden Voraussetzungen bereits erfüllt sind:

• Abonnement: Sie nutzen das Aircall-Abonnement Professional. Sowohl das Widget „Weiterleitung per API“ als auch der direkte Zugriff auf die Nachrichten-API sind Professional-Funktionen; Custom-Abonnements enthalten alle Funktionen von Professional. Wenden Sie sich für ein Upgrade an Ihre:n Aircall-Account-Manager:in.
• Zugriff: Sie haben Admin-Zugriff auf das Aircall-Dashboard und den Anrufablauf-Editor.
• Eine SMS-fähige sendende Rufnummer: Die Rufnummer, von der die Textnachricht gesendet wird, muss in Ihrem Account für SMS aktiviert sein.

Die benötigten IDs und Anmeldedaten (Rufnummern-ID, API-Schlüssel-ID und Token) werden in den nachfolgenden Schritten 1 und 2 abgerufen. Sie müssen diese nicht im Voraus zusammenstellen. Allgemeine Hintergrundinformationen zur Funktionsweise der Aircall-API finden Sie unter Aircall für Entwickler:innen: API-Referenzen. Spezifische Hintergrundinformationen zu Nachrichten finden Sie unter Aircall-Nachrichten-API und SMS-Übersicht für Entwickler:innen.

Schritt 1: Rufnummer auswählen, von der die SMS gesendet wird

Die Nachricht wird von einer Ihrer Aircall-Rufnummern gesendet, und diese Rufnummer bestimmt, wo sich die Konversation befindet. Wählen Sie sie aus, bevor Sie etwas erstellen.

Schritte

1. Vergewissern Sie sich, dass die Rufnummer für SMS aktiviert ist. Informationen zur Verfügbarkeit nach Land und Rufnummerntyp finden Sie unter SMS (geschäftliche Textnachrichten).
2. Prüfen Sie, wer die Antworten sehen soll. Alle dieser Rufnummer zugewiesenen Agenten sehen die Konversation und können über ihre Aircall-App antworten. Wählen Sie daher eine Rufnummer, die bereits vom richtigen Team verwaltet wird.
3. Entscheiden Sie, ob Sie die von der anrufenden Person gewählte Rufnummer wiederverwenden möchten. Die Ausführung eines Anrufablaufs hindert eine Rufnummer nicht daran, SMS zu senden. Daher kann die von der anrufenden Person gewählte Rufnummer auch als Absender dienen, sofern sie SMS-fähig ist. Viele Sprachrufnummern sind dies nicht. Daher ist es am sichersten, eine Rufnummer fest zu codieren, von der Sie wissen, dass sie für SMS aktiviert ist.

Hinweis: Optional kann in der Anfrage mit dem Feld agentId ein bestimmter Agent angegeben werden, wodurch die ausgehende Nachricht diesem Nutzer zugeordnet wird. Dieser Nutzer muss der sendenden Rufnummer zugewiesen sein, andernfalls wird die Anfrage abgelehnt. Wenn Sie das Feld weglassen, wird die Nachricht im Aircall Workspace dem „externen Tool“ zugeordnet.

Schritt 2: Rufnummern-ID und API-Anmeldedaten zusammenstellen

Für die Anfrage benötigen Sie zwei Angaben, die beide außerhalb des Anrufablauf-Editors abgerufen werden.

API-ID und API-Token

Navigieren Sie zu Aircall-Dashboard > Integrationen > API-Schlüssel und klicken Sie auf API-Schlüssel erstellen. Geben Sie einen Schlüsselnamen ein und kopieren Sie anschließend die API-ID und das API-Token, bevor Sie das Fenster schließen. Das Token wird nicht erneut angezeigt. Mit diesen Anmeldedaten authentifiziert sich das Widget. Weitere Informationen finden Sie unter Aircall-API-Schlüssel abrufen.

Rufnummern-ID

Die ID der SMS-fähigen Rufnummer, von der die Textnachricht gesendet wird. Sie können sie auf zwei Arten abrufen:

• Über die Dashboard-URL (am schnellsten): Öffnen Sie Rufnummern, wählen Sie die Rufnummer aus und lesen Sie die ID aus der Adressleiste ab. In https://dashboard.aircall.io/numbers/1186183/call-distribution lautet die Rufnummern-ID 1186183.
• Über die API: Rufen Sie den Endpunkt Alle Rufnummern auflisten auf. Jede Rufnummer in der Antwort enthält eine id.

In beiden Fällen tragen Sie diesen Wert in die Anfrage-URL ein.

Achtung: Die Rufnummern-ID gehört in den URL-Pfad der Anfrage, nicht in den Anfragetext.

Schritt 3: Anrufablauf im Anrufablauf-Editor erstellen

Schritte

1. Gehen Sie zu Aircall Dashboard > Rufnummern > Rufnummern.
2. Wählen Sie die Rufnummer aus und klicken Sie auf die grüne Schaltfläche Bearbeiten, um den Anrufablauf-Editor zu öffnen.
3. Legen Sie fest, wo SMS angeboten werden:

   • Als Menüoption: Fügen Sie ein Sprachmenü-Widget hinzu, zum Beispiel: „Um per SMS fortzufahren, anstatt zu warten, drücken Sie die 1. Um in der Leitung zu bleiben, drücken Sie die 2.“

     

   • Als Überlauf: Platzieren Sie das Widget Anrufen über API in dem Zweig, der erreicht wird, wenn kein Agent verfügbar ist.

     

Schritt 4: Widget „Anrufen über API“ konfigurieren

Fügen Sie im SMS-Zweig das Widget Anrufen über API hinzu und konfigurieren Sie die Anfrage wie folgt. Diese Anfrage verwendet den Endpunkt Nachricht in Agentenkonversation senden, durch den die Konversation für Agenten sichtbar wird.

Authentifizierung

Der Endpunkt verwendet die HTTP-Basic-Authentifizierung. Wählen Sie in den Authentifizierungseinstellungen des Widgets Basic aus und geben Sie Folgendes ein:

• Benutzername: Ihre API-ID

• Passwort: Ihr API-Token

  

Das Widget erstellt die Autorisierung für Sie; eine manuelle Codierung ist nicht erforderlich.

Anfragekonfiguration

• Methode: POST
• URL: https://api.aircall.io/v1/numbers/1018591/messages/native/send, ersetzen Sie 1018591 durch Ihre eigene Rufnummern-ID aus Schritt 2.

Anfragetext:

{
  "to": "{{callerNumber}}",
  "body": "Thanks for calling! Reply to this text and an agent will help you shortly."
}

Anfragetext, einem bestimmten Agenten zugeordnet (optional):

{
  "to": "{{callerNumber}}",
  "body": "Thanks for calling! Reply here and an agent will pick this up shortly.",
  "agentId": 456789
}

Feldreferenz:

• to (erforderlich): die Rufnummer, an die die SMS gesendet wird. Verwenden Sie das E.164-Format mit einem + und der Landesvorwahl. Verwenden Sie {{callerNumber}}, damit der Anrufablauf-Editor zur Laufzeit die Rufnummer des Anrufers einfügt. Sie wird bereits im E.164-Format ausgegeben.
• body (erforderlich): der zu sendende Text mit bis zu 1.600 Zeichen. Längere Nachrichten werden abgelehnt.
• agentId (optional, Ganzzahl): die Aircall-Nutzer-ID, der die Nachricht zugeordnet werden soll. Der Nutzer muss der sendenden Rufnummer zugewiesen sein.
• Die Rufnummern-ID ist kein Feld des Anfragetexts, sondern das Segment :id der URL.

Variablen des Anrufablaufs, die Sie in der URL oder im Anfragetext verwenden können: {{callerNumber}}, {{targetNumber}}, {{callUUID}} und {{lineId}}. Wenn Ihr Anrufablauf ein Eingabe-Sprachmenü-Widget enthält, ist die erfasste Eingabe als zusätzliche Variable verfügbar, die nach diesem Widget benannt ist. Die Ersetzung funktioniert sowohl in der URL als auch im Anfragetext.

Am übersichtlichsten ist es, die ID der sendenden Rufnummer wie oben fest in die URL einzutragen. Stattdessen können Sie {{lineId}} verwenden. Diese Variable wird in die vom Anrufer gewählte Rufnummer aufgelöst, jedoch nur, wenn diese Rufnummer selbst SMS-fähig ist.

Achtung: {{callerNumber}} sendet die SMS an die Rufnummer, von der aus der Anrufer anruft. Wenn diese Rufnummer keine SMS empfangen kann, eine Festnetznummer oder eine internationale Rufnummer außerhalb der für Ihre Rufnummer zulässigen Ziele ist, schlägt die Zustellung fehl. Berücksichtigen Sie dies bei der Entscheidung, ob Sie jedem Anrufer die SMS-Option anbieten möchten.

Antwortkonfiguration

Bevor der Anrufablauf veröffentlicht werden kann, benötigt das Widget eine Antwortkonfiguration, obwohl dieser Anrufablauf nicht auf Grundlage der Antwort weiterleitet (der Anruf wird im nächsten Schritt unabhängig vom Ergebnis beendet). Füllen Sie diese Felder mit einem Platzhalter aus, der absichtlich nicht aufgelöst wird:

• Antworttyp: Aircall-Rufnummer (intern)
• Pfad: null

Die SMS wird gesendet, bevor das Widget die Antwort prüft. Die Nachricht wird daher trotzdem versendet. Da der Pfad nie aufgelöst wird, behandelt das Widget die Antwort als ungültig und fährt einfach mit dem nächsten Schritt Ihres Anrufablaufs fort, was hier beabsichtigt ist.

Hinweis: Alle öffentlichen API-Endpunkte von Aircall haben ein gemeinsames Limit von 120 Anfragen pro Minute. Jede Rufnummer hat außerdem eigene stündliche, tägliche und monatliche Nachrichtenlimits, die jeweils nach UTC zurückgesetzt und mit dem Endpunkt zum Überspringen des Posteingangs geteilt werden (US-amerikanische und kanadische Langwahlnummern und gebührenfreie Rufnummern: 5.000 / 10.000 / 100.000; britische, australische, deutsche, spanische und französische Plattformrufnummern: 500 / 2.000 / 20.000; französische Mobilfunknummern: 100 / 1.000 / 10.000). Dies sollte einen typischen Anrufablauf nicht beeinträchtigen, ist aber bei Tests mit hohem Volumen wissenswert. Anfragen vom Widget laufen nach 10 Sekunden ab und werden nicht erneut versucht.

Schritt 5: Anrufablauf abschließen

Da das Widget nicht auf die API-Antwort reagieren kann, schließen Sie den Zweig unabhängig vom Ergebnis ordnungsgemäß ab.

Schritte

1. Klicken Sie nach dem Widget auf + und fügen Sie eine Audionachricht wie diese hinzu: „Wir haben Ihnen gerade eine SMS gesendet. Sie können dort antworten, sobald Sie bereit sind. Vielen Dank.“
2. Beenden Sie den Anruf oder leiten Sie ihn ersatzweise an die Voicemail oder ein anderes Team weiter.

Hinweis: Der Anrufablauf-Editor stellt die Schritte nach einem „Ring to via API“-Widget ausgegraut dar, da er davon ausgeht, dass der Anruf den Anrufablauf verlässt, um bei einem Ziel zu klingeln. Bei dieser Konfiguration verlässt der Anruf den Anrufablauf nicht, sodass diese Schritte ausgeführt werden. Die ausgegraute Darstellung ist eine bekannte Anzeigeeigenheit und kann bedenkenlos ignoriert werden.

Schritt 6: Anrufablauf testen

Testen Sie zuerst die Anfrage im Widget und führen Sie anschließend einen echten Anruf durch, sobald sie funktioniert.

Über das Widget testen

Das Widget kann einen Anrufer simulieren. Daher müssen Sie den Anrufablauf nicht veröffentlichen oder die Rufnummer anrufen, um zu prüfen, ob die SMS versendet wird.

Schritte

1. Suchen Sie im Widget das Feld Testanfrage und geben Sie eine Nutzlast mit der zu simulierenden Rufnummer ein:

{
  "callerNumber": "+15551234567"
}

2. Klicken Sie auf Testanfrage. Das Widget verhält sich so, als hätte diese Rufnummer angerufen und diesen Punkt im Anrufablauf erreicht. Die SMS wird tatsächlich versendet. Verwenden Sie daher eine Rufnummer, die Sie überprüfen können.
3. Vergewissern Sie sich, dass die SMS ankommt und die Konversation im Aircall-Posteingang angezeigt wird.

Hinweis: Der Test meldet auch dann einen Fehler, wenn die Nachricht ordnungsgemäß versendet wurde. Das ist zu erwarten: Die Antwortkonfiguration verweist absichtlich auf einen Pfad, der nie aufgelöst wird. Daher stuft das Widget die Antwort als ungültig ein. Ignorieren Sie den Fehler und überprüfen Sie das Ergebnis stattdessen auf dem Smartphone und im Posteingang.

Gesamten Anrufablauf testen

Schritte

1. Klicken Sie oben rechts auf Veröffentlichen.
2. Rufen Sie die Rufnummer von einem Smartphone aus an, das SMS empfangen kann.
3. Rufen Sie den SMS-Zweig auf, indem Sie die Option auswählen oder die Überlaufbedingung auslösen.
4. Vergewissern Sie sich, dass Sie die SMS erhalten, der Wortlaut stimmt, die gesprochene Bestätigung abgespielt wird und eine Antwort eine Konversation im Aircall-Posteingang öffnet oder fortsetzt.

Wenn die Nachricht nicht ankommt, lesen Sie die nachstehende Tabelle zur Fehlerbehebung.

Fehlerbehebung

Die vollständige Liste der Antwortcodes für diesen Endpunkt finden Sie in der API-Referenz.

Häufig gestellte Fragen

Sehen meine Agents die SMS-Konversation, wenn der Anrufer antwortet?

Ja. Diese Anfrage verwendet den Endpunkt Nachricht in Agent-Konversation senden. Daher werden sowohl die ausgehende Nachricht als auch die Antwort des Kunden im Aircall-Posteingang aller Agents angezeigt, die die Absenderrufnummer verwalten, sowie in Nachrichten-Webhook-Ereignissen.

Benötige ich eine genehmigte Vorlage für die Nachricht?

Nein. Der Text kann frei formuliert und mit bis zu 1.600 Zeichen direkt in den Anfragekörper geschrieben werden. Es muss keine Vorlage genehmigt und kein Nachrichtenzeitfenster eingehalten werden.

Was ist mit Anrufern in anderen Ländern?

SMS über die API werden nur innerhalb eines Landes unterstützt, mit Ausnahme von USA–Kanada. Einem Anrufer kann daher nur von einer Rufnummer eine SMS gesendet werden, die sein Land abdeckt. Wenn Ihre Anrufer über mehrere Länder verteilt sind, fügen Sie entweder für jeden Markt eine lokale SMS-fähige Rufnummer hinzu oder bieten Sie stattdessen im selben Zweig Nachrichten über WhatsApp an. WhatsApp ist nicht an das Land des Anrufers gebunden, sodass eine einzige WhatsApp-fähige Rufnummer alle Personen erreicht, die die App verwenden. Siehe Anrufern mit dem „Ring to via API“-Widget WhatsApp-Support anbieten.

Kann ich stattdessen ein Bild oder eine PDF-Datei senden?

Nein. MMS wird an diesem Endpunkt nicht unterstützt. Wenn Sie Medien versenden müssen, verwenden Sie den Endpunkt „Send Message Skipping Aircall Inbox“. Diese Nachrichten werden jedoch nicht in der Aircall-App angezeigt, sodass Agents die Konversation nicht übernehmen können.

Kann ich die Nachricht von derselben Rufnummer senden, die der Anrufer gewählt hat?

Ja, sofern diese Rufnummer SMS-fähig und nicht für Nachrichten konfiguriert ist, die den Posteingang überspringen. Die Ausführung eines Anrufablaufs, einschließlich eines Ablaufs mit Sprachmenü, hindert eine Rufnummer nicht daran, SMS zu senden. In der Praxis sind viele Sprachtelefonierufnummern nicht für SMS aktiviert. Deshalb ist in diesem Artikel eine bekanntermaßen SMS-fähige Rufnummer fest codiert. Wenn die gewählte Rufnummer SMS-fähig ist, können Sie stattdessen {{lineId}} in der URL verwenden.

Kann ich die Nachricht mit Anruferdaten personalisieren?

Ja, im Rahmen der vom Anrufablauf-Editor bereitgestellten Möglichkeiten. Sie können {{callerNumber}}, {{targetNumber}}, {{callUUID}} oder {{lineId}} in den Textkörper einfügen sowie alle Eingaben, die zuvor im Anrufablauf von einem Eingabe-Sprachmenü-Widget erfasst wurden. Für weiterführende Angaben, beispielsweise einen Namen aus Ihrem CRM, benötigen Sie eine Middleware, die den Anrufer nachschlägt und selbst die Aircall-API aufruft.

Was geschieht, wenn die Rufnummer des Anrufers keine SMS empfangen kann?

Die Zustellung schlägt fehl, und das Widget kann den Anrufer nicht darüber informieren. Da die Nachricht an die Rufnummer gesendet wird, von der aus der Anrufer angerufen hat, sollte in diesem Zweig immer eine gesprochene Ausweichoption sowie eine Weiterleitung an eine Warteschlange oder Voicemail eingerichtet sein.