Mit Node.js Audio in einen Telefonanruf streamen

Einführung

Wenn Sie Ihre Kundin anrufen, haben Sie ihre ungeteilte Aufmerksamkeit. Warum nutzen Sie diese Gelegenheit nicht, um ihr die neuesten Nachrichten über Ihr Unternehmen mitzuteilen, eine inspirierende Botschaft Ihres CEO zu übermitteln oder ihr sogar Ihren neuesten Werbejingle vorzuspielen?

In diesem Blog-Beitrag erfahren Sie, wie Sie eine Audiodatei in einem aktiven Anruf programmatisch abspielen können, indem Sie die Vonage Voice API und Node.js abspielt.

Bevor Sie beginnen

Um dieses Beispiel durchzuarbeiten, benötigen Sie Node.js. Wenn Sie es nicht bereits haben, installieren Sie es von der Node.js-Website.

Sie können eine Numbers im Vonage Developer Dashboard bereitstellen, aber wir werden Sie durch die Verwendung der Vonage CLI um eine Nummer zu erwerben, eine Sprachanwendung zu erstellen und dann Ihre Nummer damit zu verknüpfen.

Schließlich sollten Sie den Quellcode, der in diesem Artikel verwendet wurde, auf GitHub.

Klonen Sie das Repository und cd in das Stammverzeichnis der Anwendung.

Installieren und Konfigurieren der Vonage CLI

Installieren Sie die Vonage CLI global mit dem folgenden Befehl:

npm install @vonage/cli -g

dann, konfigurieren Sie die CLI mit Ihrem Vonage API-Schlüssel und -Geheimnis, die Sie im Developer Dashboard finden:

Vonage auth set –api-key=’VONAGE_API_KEY –api-secret=’VONAGE_API_SECRET’

Ersetzen Sie die VONAGE_API_KEY und VONAGE_API_SECRET durch Ihre Angaben, um die CLI zu authentifizieren.

Sie können Ihre Authentifizierung mit dem folgenden Befehl überprüfen, um sicherzustellen, dass alles funktioniert:

vonage auth check

Wenn Sie die CLI nicht global, sondern in Ihrem lokalen Projekt installiert haben, können Sie ein zusätzliches Flag zur Überprüfung hinzufügen:

vonage auth check –local

Kaufen Sie eine Vonage-Nummer

Sie benötigen eine Nummer, von der aus Sie anrufen können. Erwerben Sie eine, indem Sie den folgenden Befehl ausführen und dabei die Landesvorwahl entsprechend ersetzen. Wenn Sie sich zum Beispiel in den USA befinden, ersetzen Sie [COUNTRYCODE] durch US:

vonage numbers search [COUNTRYCODE]

Sie können die Rufnummer erwerben, indem Sie den unten stehenden Code von Ihrem Terminal aus ausführen. Es ist wichtig zu beachten, dass einige Länder eine Adressvalidierung erfordern und der Kauf über das Vonage-Dashboard und nicht über die Befehlszeile getätigt werden muss.

vonage numbers buy [COUNTRYCODE] [MSIDSN]

Notieren Sie sich die Telefonnummer, die der Befehl zurückgibt.

Erstellen der Voice-Applikation

Um die Voice API zu verwenden, müssen Sie eine Voice API Anwendung. Dies ist nicht dasselbe wie die Webanwendung, die Sie erstellen. Es handelt sich lediglich um einen Container für die Konfigurations- und Sicherheitsinformationen, die Sie für die Verbindung mit den APIs von Vonage benötigen.

vonage apps create "Play audio app" --private-key-file=~/private.key

Sie erhalten die folgenden Daten zum Notieren:

Name: play audio app

Anwendung ID: 7a319bf9-49e7-413d-914b-402fe8e68228

Verbesserung der KI: Aus

Privater/öffentlicher Schlüssel: Einstellen

Sie werden feststellen, dass wir dem Befehl das folgende Argument gegeben haben private-key-file. Dadurch wird Ihr privater Schlüssel für Sie heruntergeladen, sobald der Befehl ausgeführt wurde: Suchen Sie diese Schlüsseldatei (im Befehl habe ich das UNIX-ähnliche ~/ locationverwendet, was der Home-Ordner ist; Sie sollten ihn auf etwas wie. C:\Users\YOUR-USER-NAME wenn Sie Powershell unter Windows verwenden) und legen Sie die Datei im Stammverzeichnis des begleitenden Blog-Artikel-Codes.

Wir haben die Anwendung noch nicht so eingestellt, dass sie die Voice API verwendet. Führen Sie daher den folgenden Befehl aus, um die Voice-Funktion hinzuzufügen:

vonage apps capabilities update [VONAGE_APPLICATION_ID] --voice-answer-url=https://example.com/answer --voice-event-url=https://example.com/event-status

Sie werden feststellen, dass wir die voice-answer-url und die voice-event-url hier auf der Anwendungsebene setzen. Dies sind vorerst Platzhalter, und Sie brauchen diese Werte nicht zu ändern. Der Grund hierfür ist, dass der Code, der für den Aufruf verwendet wird, diese Werte während der HTTP-Aufrufe dynamisch erstellt.

Initialisieren der Abhängigkeiten

Um diese App zu erstellen, benötigen wir die Mindestanforderungen, um einen Voice-Anruf zu tätigen und die Anrufinstanz zu aktualisieren, um Audio in den Anruf zu spielen. Sie benötigen das Folgende:

• dotenv - eine leichtgewichtige Bibliothek, mit der Sie eine Datei mit Umgebungsvariablen einlesen können (der De-facto-Standard nennt sie .env. Wir benötigen diese Datei, um den API-Schlüssel und das Geheimnis aus dem Vonage Dashboard zur Laufzeit zu injizieren.

• express - Das leichteste und am weitesten verbreitete Node-Framework für grundlegende HTTP-Funktionen.

• @vonage/server-sdk - die REST-Client-Bibliothek für Node.js.

• @vonage/voice - Vonage Voice SDK für Node.js

Wir können eines dieser Projekte über die Befehlszeile installieren. Zunächst müssen wir das Projekt als npm-Projekt initialisieren, das Ihnen dann eine Reihe von Fragen zur Definition des Gesamtprojekts stellt. Sie können zunächst die Standardeinstellungen wählen. Sie werden auch gefragt, ob es Pakete gibt, die Sie installieren möchten, aber wir überspringen das, um zu klären, wie wir die Abhängigkeiten später hinzufügen. Sie können auch yarn verwenden, deshalb habe ich es als separates Terminal-Snippet eingefügt. Wählen Sie aus, was für Sie funktioniert:

npm init

yarn init

Klicken Sie auf return, um alle Standardwerte auszuwählen - Sie können dieses Paket nennen, wie Sie wollen, da es in diesem Zusammenhang nicht wichtig ist. Sobald Sie dies getan haben, erstellt npm oder yarn eine package.json Datei für Sie. Von hier aus können wir dann die einzelnen Pakete hinzufügen:

npm install dotenv express @vonage/server-sdk @vonage/voice

Öffnen Sie Ihre Anwendung für das Internet

Wir müssen unsere Anwendung dem Internet aussetzen, damit die Server von Vonage unserer Anwendung die Voice API Webhooks senden können. Wir empfehlen die Verwendung von ngrok für diese Aufgabe.

Sie können mehr darüber erfahren, wie Sie ngrok zum Laufen bringen um ngrok auf Port 3000 zu installieren und auszuführen (dies ist der Standardport von express.js). Zum Beispiel:

ngrok http 3000

ngrok gibt Ihnen eine temporäre URL, wie zum Beispiel https://914288e7.ngrok.io. Notieren Sie sich diese.

Lassen Sie ngrok laufen, während Sie die Anwendung verwenden; andernfalls ändern sich die URLs, und Sie müssen sie neu konfigurieren.

Konfigurieren Sie die Umgebung

Kopieren. example.env auf .env und geben Sie die Daten ein, die Sie aus den obigen Schritten gewonnen haben:

VONAGE_APPLICATION_ID= The Voice API application ID

VONAGE_APPLICATION_PRIVATE_KEY_PATH= private.key

VONAGE_NUMBER= The number you rented from Vonage

TO_NUMBER= The number you want the application to call

BASE_URL= The ngrok temporary URL

Jetzt können Sie die Anwendung in Aktion erleben!

Ausführen der Anwendung

Starten Sie die Anwendung, indem Sie den folgenden Befehl ausführen:

node server.js

Wenn Ihre express.js-App zufrieden ist, sollten Sie ein Protokoll erhalten, das besagt, dass die App auf Port 3000 lauscht. Besuchen Sie http://localhost:3000/call in Ihrem Browser. Dies macht einen GET Anfrage an den /call Endpunkt in Ihrer Anwendung und veranlasst diese, den TO_NUMBER in .env.

Sie hören eine Nachricht, dann ertönt 20 Sekunden lang Musik, dann wird die Verbindung getrennt.

Wie funktioniert es?

Schauen wir uns an, wie das alles im Code zusammengesetzt ist. Die Anwendung besteht aus drei Teilen:

1. Tätigen Sie den ausgehenden Anruf.

2. Geben Sie Vonage das NCCO-Objekt, das definiert, was passiert, wenn der Endkunde den Anruf entgegennimmt.

3. Streamen Sie den Ton der gehaltenen Musik in einen aktiven Anruf.

Tätigen Sie den ausgehenden Anruf

Der folgende Code wird ausgeführt, wenn Sie eine GET Anfrage an den /call Endpunkt senden:

try {

   console.log("Making the outbound call...");

   const resp = await voice.createOutboundCall(

     {

       to: [{ type: "phone", number: TO_NUMBER }],

       from: { type: "phone", number: VONAGE_NUMBER },

       answer_url: [answer_url],

       answer_method: HttpMethod.POST, // This will hit the NCCO response

       event_url: [event_url], // Event URL to track events like answered

     }

   );

   console.log("Outbound call response:", resp);

   res.status(200).send("Call initiated!");

 } catch (error) {

   console.error("Error making the outbound call:", error);

   res.status(500).send("Failed to make call.");

 }

Die dotenv Bibliothek kümmert sich um den Import der .env Datei-Variablen, damit wir wissen, wen wir anwählen müssen. Die answer_url sagt Vonage, was zu tun ist, wenn das Telefon abgenommen wird - was wir hier tun werden, ist, einen NCCO zurückzugeben, den wir mit der NCCO Builder-Klasse im Node SDK erstellen werden.

Definition der Antwort NCCO

Wir definieren die answer_url als Endpunkt in unserer express.js-App mit folgendem Code:

app.post("/audio/answer", (req, res) => {

 const builder = new NCCOBuilder();

 builder.addAction(

   new Talk('Here is some soothing music for you')

 )

 builder.addAction(

   new Stream(audio_url)

 );

 // Send back the generated NCCO

 res.json(builder.build());

});

Erstens ist es app.post() der die Route für die Anwendung definiert. Was als nächstes geschieht, besteht aus zwei Teilen: Vonage erwartet Anweisungen in Form eines NCCO, die ihm sagen, was zu tun ist, wenn das Telefon abgenommen wird.

1. Sagen Sie dem Endkunden, dass Musik auf dem Weg ist

Wie Sie sehen können, haben wir ein neues NCCOBuilder Objekt erstellt haben. Diese Klasse handhabt alle notwendigen Methoden und verpackt den Aufbau des NCCO-JSON-Objekts ordentlich für den Entwickler. Die erste Aufgabe besteht darin, dem Endbenutzer mitzuteilen, dass eine schöne Musik abgespielt wird, also erstellt der Code ein. Talk() Objekt, das ein String-Argument als Text-to-Speech übernimmt. Mit dem addAction()Objekt können Sie beliebige Wertobjekte hinzufügen, die Sie Vonage während des Anrufs anweisen möchten. Dies kann die Erfassung von Benutzereingaben über. DTMF, das Erfassen von Audioaufnahmen und Text-to-Speech.

2. Streamen Sie den Ton in einen aktiven Anruf

Dieser NCCO wird synchron aufgebaut, d. h. die Anweisungen in der NCCO-Nutzlast werden nacheinander ausgeführt. Die nächste Anweisung besteht darin, eine öffentliche URL unserer gehosteten Musikdatei anzugeben, die in den Aufruf gestreamt werden soll. Dies ist der Talk() Aktion. Wir geben dem Builder eine neue sequenzielle Aktion, die er ausführen soll, nämlich eine Stream() Aktion. Das erste Argument ist eine Zeichenkette mit der URL, auf die wir verweisen wollen und die wir bereits als audio_url Variable definiert haben.

Und da haben Sie es! Zwei Befehle an Vonage für den laufenden Anruf beim Abheben des Telefons, und jetzt haben wir schöne entspannende Musik, während wir in einer fiktiven, vermutlich stressigen Warteschlange auf... Konzertkarten oder einen Arzttermin warten.

Schlussfolgerung

In diesem Beitrag haben Sie gelernt, wie man Audio in ein bestehendes Gespräch einspielt und wie die NCCO actions die den Gesprächsablauf steuern. Sie können gerne experimentieren und verschiedene Audiodateien und NCCO actions. Die folgenden Ressourcen können Ihnen dabei helfen:

• Voice API-Referenz

• NCCO-Referenz

• Verwendung von SSML in TTS (Text-to-Speech)

• Die REST-API Client-Bibliothek für Node.js