https://a.storyblok.com/f/270183/1368x665/5a90dba70f/26sep_blg_apintw_devrel_update_existing_imgs_audio_stream_python-1.jpg

Mit Python und Vonage einen Audiostream in ein Telefongespräch einspeisen

Zuletzt aktualisiert am March 13, 2023

Lesedauer: 12 Minuten

Dieser Artikel wurde im August 2026 aktualisiert.

Es gibt viele Gründe, warum Sie einen Audiostream in ein Gespräch einspielen möchten. Ein alltäglicher Anwendungsfall ist beispielsweise, wenn Entwickler den Anrufer in die Warteschleife legen möchten, um ihn zu beruhigen, und dabei Musik abspielen können, die seinen Stresspegel senkt.

Einige Beispielszenarien sind:

  • Wartemusik für Anrufer abspielen

  • Telefonkonferenz: Spielen Sie Musik in eine Telefonkonferenz ein, bis die Beschlussfähigkeit erreicht ist

  • Voraufgezeichnete Ansage: Nützlich, wenn Vonage Ihre Sprache in seiner Text-to-Speech-Engine nicht unterstützt

  • Anrufbeantworter: Wenn Sie anrufen und eine Nachricht hinterlassen, kann diese bei einem späteren Anruf wiedergegeben werden.

Im Folgenden erfahren Sie, wie Sie die Szenarien 1 und 2 umsetzen können. Die übrigen Szenarien werden in anderen Blogbeiträgenbehandelt.

Es gibt auch zwei Methoden für die Wiedergabe eines Audiostroms in einem Anruf:

  1. Verwendung eines Anrufsteuerungsobjekts (NCCO)

  2. Verwendung der Voice API

Sie werden Methode 1 für Szenario 1 und Methode 2 für Szenario 2 verwenden.

So streamen Sie Audio in einen Anruf mit Vonage

Call Control Objects (NCCOs) bieten eine bequeme Möglichkeit zur Steuerung eines eingehenden Anrufs. NCCOs bestehen aus einer JSON-Konfiguration, die beschreibt, wie der Anruf zu behandeln ist. Es gibt eine detaillierte Referenzhandbuch zu NCCOs in dem die vielen Aktionen beschrieben werden, die ausgeführt werden können. In unseren Szenarien ist nur eine Aktion von Interesse, stream. Es gibt eigentlich zwei Arten, wie Sie die stream Aktion verwenden: synchron und asynchron. Asynchron bedeutet, dass der Anrufer den Ton unterbrechen kann stream über die Telefontastatur unterbrechen. Es gibt einige Optionen für Stream-Aktionen, die von Interesse sind:

Syntax

Beschreibung

streamUrl

Ein Array, das eine einzelne URL zu einer MP3- oder WAV-Audiodatei (16 Bit) enthält, die in den Anruf oder die Konversation gestreamt werden soll.

level

Stellen Sie den Audiopegel des Streams im Bereich -1 >=level<=1 mit einer Genauigkeit von 0,1 ein. Der Standardwert ist 0.

bargeIn

Wenn diese Option auf true, wird diese Aktion beendet, sobald der Benutzer eine Taste auf dem Tastenfeld drückt. Nutzen Sie diese Funktion, damit Benutzer eine Option auswählen können, ohne die gesamte Ansage in Ihrem IVR-System (Interactive Voice Response) anhören zu müssen. Wenn Sie bargeIn auf true bei einer weiteren Stream-Aktion auf „Ein“, muss die nächste Aktion im NCCO-Stapel eine Eingabeaktion sein. Der Standardwert ist false.

loop

Die Anzahl der Wiederholungen der Audio-Wiedergabe, bevor der Anruf beendet wird. Der Standardwert ist 1. Setzen Sie den Wert auf 0, um die Wiedergabe endlos zu wiederholen.

Weitere Informationen finden Sie in der Dokumentation , um mehr über die Stream-Optionen zu erfahren.

Hier ist ein Beispiel-Codeausschnitt zum Abspielen von Audio in einem Anruf mithilfe des Vonage Python SDK durch die Definition eines answer Webhooks:

@app.route("/webhooks/answer", methods=["POST"])
def answer_call():
    """
    Answer a call to your Vonage virtual number by playing music
    """
    ncco: list[NccoAction] = [
        Stream(streamUrl=[STREAM_URL]),
    ]

    return [action.model_dump(by_alias=True, exclude_none=True) for action in ncco]

Die unterstützten Audiodateiformate sind MP3 und 16-Bit-WAV.

Wir haben bereits eine Vonage-Starteranwendung entwickelt, mit der Sie Anrufe entgegennehmen und während des Gesprächs Musik abspielen können – und zwar in zwei verschiedenen Szenarien. Bei dieser Starteranwendung müssen Sie Ihre Anmeldedaten in die .env Datei eintragen und die App über GitHub Codespaces bereitstellen. Ein Codespace ist eine Entwicklungsumgebung, die in der GitHub-Cloud gehostet wird. GitHub Codespaces lassen sich projektbezogen anpassen, und Benutzer können das zu verwendende Linux-basierte Betriebssystem festlegen, häufig verwendete Ports weiterleiten, Umgebungsvariablen setzen usw. Sie können auch die Starteranwendung bearbeiten und damit experimentieren.

Voraussetzungen

Registrieren Sie sich für einen Vonage-API-Account

Erstellen einer neuen Vonage-Anwendung

  • Um eine Anwendung zu erstellen, gehen Sie auf die Seite Erstellen einer Anwendung auf dem Vonage Dashboard und legen Sie einen Namen für Ihre Anwendung fest.

  • Wenn Sie eine API verwenden möchten, die Webhooks nutzt, benötigen Sie einen privaten Schlüssel. Klicken Sie auf "Generate public and private key", der Download sollte automatisch starten. Bewahren Sie ihn sicher auf; dieser Schlüssel kann bei Verlust nicht erneut heruntergeladen werden. Er folgt der Namenskonvention privat_<Ihre App-ID>.key. Dieser Schlüssel kann nun zur Authentifizierung von API-Aufrufen verwendet werden. Hinweis: Ihr Schlüssel funktioniert erst, wenn Ihre Anwendung gespeichert ist.

  • Wählen Sie die benötigten Funktionen (z. B. Voice, Nachrichten, RTC usw.) und stellen Sie die erforderlichen Webhooks bereit (z. B. Ereignis-URLs, Antwort-URLs oder URLs für eingehende Nachrichten). Diese werden im Lernprogramm beschrieben.

  • Zum Speichern und Bereitstellen klicken Sie auf "Neue Anwendung generieren", um die Einrichtung abzuschließen. Ihre Anwendung ist nun bereit für die Verwendung mit Vonage-APIs.

Einrichten Ihrer Umgebung

Fork dieses Repository. Öffne es in Codespaces, indem du auf „Create codespace on main“ klickst. Alternativ kannst du die App mit Python und ngrokbereitstellen. Die Anleitung für diese Methode findest du in der README-Datei des Repositorys README.

Abrufen und Konfigurieren Ihrer Geheimnisse

Sie benötigen Ihre Vonage-Anwendungs-ID und Ihre private.key , damit diese Beispielanwendung funktioniert.

  1. Im Vonage Developer Dashboard für Ihre Anwendung auf die Schaltfläche „Öffentlichen und privaten Schlüssel generieren“. Dadurch wird eine Datei heruntergeladen. Bewahren Sie diese Datei sicher und vertraulich auf!

  2. Erstellen Sie in Ihrem Codespace eine Datei mit dem Namen .env und fügen Sie den Inhalt von .env.template darin ein. Ersetzen Sie den Platzhalter für VONAGE_APPLICATION_ID durch Ihre eigene Anwendungs-ID.

  3. Erstellen Sie in Ihrem Codespace eine Datei mit dem Namen private.key. Kopieren Sie den Inhalt Ihrer heruntergeladenen private.key Datei in diese Datei ein und aktualisieren Sie den Platzhalterwert für VONAGE_PRIVATE_KEY in Ihrer .env Datei so, dass er auf Ihre neu erstellte private Schlüsseldatei verweist.

Führen Sie im Codespace-Terminal die folgenden Befehle aus:

echo "https://${CODESPACE_NAME}-9000.preview.app.github.dev/webhooks/answer"

Führen Sie anschließend diesen Befehl aus:

echo "https://${CODESPACE_NAME}-9000.preview.app.github.dev/webhooks/event"

Kopieren Sie die Ausgaben dieser Befehle und fügen Sie sie in die Antwort-URL und Ereignis-URL gemäß den Feldern in den Einstellungen der Vonage-Applications ein.

Terminal output in GitHub Codespaces showing the generated Answer URL and Event URL for the Vonage webhook configuration.Copy the generated URLs and paste them into the Answer URL and Event URL fields in your Vonage Application settings.Audio über einen NCCO in Ihr Gespräch einbinden

In diesem Szenario rufen Nutzer eine Vonage-Nummer an, und über ein NCCO wird Musik mit einer stream Aktion. Wir verwenden dazu die folgende scenario-1.py Datei verwenden:

from dotenv import load_dotenv
from flask import Flask, request, jsonify
from vonage_voice import NccoAction, Stream

from os import environ as env

# Load environment variables from a .env file:
load_dotenv(".env")

# Load in configuration from environment variables:
STREAM_URL = env["STREAM_URL"]


app = Flask(__name__)


@app.route("/webhooks/answer", methods=["POST"])
def answer_call():
    """
    Answer a call to your Vonage virtual number by playing music
    """
    ncco: list[NccoAction] = [
        Stream(streamUrl=[STREAM_URL]),
    ]

    return [action.model_dump(by_alias=True, exclude_none=True) for action in ncco]


@app.route("/webhooks/event", methods=["POST"])
def events():
    return "200"


if __name__ == "__main__":
    app.run(host="localhost", port=9000)

Probieren Sie es aus

Mit den folgenden Schritten können Sie Ihren Code in Codespaces ausführen.

Installieren Sie die Abhängigkeiten:

pip install -r requirements.txt

Starten Sie Ihre App mit dem folgenden Befehl:

python3 scenario-1.py

Öffnen Sie im Terminal die Registerkarte Port Registerkarte. Klicken Sie auf Private in der Spalte Visibility und ändern Sie sie in Public.

The GitHub Codespaces Ports tab showing the Visibility column being changed from Private to Public for port 9000.Change the port visibility to Public so Vonage can reach your local webhook.Der Ablauf der Ereignisse in diesem Szenario ist wie folgt:

  1. Wählen Sie Ihre Vonage-Nummer

  2. Vonage nimmt den Anruf entgegen

  3. Ein Callback wird an der answer von Ihnen angegebenen Webhook-URL

  4. Ihre Anwendung empfängt den Callback und antwortet mit einem NCCO

  5. Während Ihres Anrufs wird Musik abgespielt

Audio über die Voice API in Ihren Anruf einbinden

In diesem Szenario rufen Sie Ihre Vonage-Nummer an und werden in eine Konferenz eingewählt (in unserem Fall die „Soothing Conference“). Anschließend können Sie die /stream URL navigieren, um das Streaming in die Konferenz zu starten. Die Musik wird dann mithilfe der Voice API in Ihre Konferenz eingespielt.

Probieren Sie es aus

Mit den folgenden Schritten können Sie Ihren Code in Codespaces ausführen.

Installieren Sie die Abhängigkeiten:

pip install -r requirements.txt

Starten Sie Ihre App mit dem folgenden Befehl:

python3 scenario-2.py

Öffnen Sie im Terminal die Registerkarte Port Registerkarte. Klicken Sie auf Private in der Spalte Visibility und ändern Sie sie in Public.

The GitHub Codespaces Ports tab showing the Visibility column being changed from Private to Public for port 9000.Change the port visibility to Public so Vonage can reach your local webhook.Jetzt kannst du Audio streamen!

Tun Sie diese zusätzlichen Dinge:

  1. Wählen Sie Ihre Vonage-Nummer

  2. Führen Sie den folgenden Befehl im neuen Terminalfenster aus echo "https://${CODESPACE_NAME}-9000.preview.app.github.dev/stream" und navigieren Sie anschließend zu dem Link (falls Sie auf einem lokalen Rechner arbeiten, localhost:9000/stream), und die Musik wird in Ihrer Konferenz abgespielt

Die folgenden Aktionen werden durchgeführt:

  1. Vonage nimmt den Anruf entgegen

  2. Der Callback wird an der answer von Ihnen angegebenen Webhook-URL

  3. Ihre Anwendung empfängt den Callback und antwortet mit einem NCCO

  4. Die Anrufer nahmen an einer Telefonkonferenz teil

  5. Musik, die auf Ihrer Konferenz gespielt wird

Nachbereitung

Herzlichen Glückwunsch! Mit dem Workflow und den vorbereiteten Code-Beispielen können Sie passendes Audiomaterial in ein Gespräch einbinden und entsprechende Musik abspielen, wenn Anrufer in der Warteschleife sind.

Weitere Lektüre und Ressourcen

Haben Sie eine Frage oder möchten Sie uns mitteilen, was Sie gerade bauen?

Bleiben Sie auf dem Laufenden und halten Sie sich über die neuesten Nachrichten, Tipps und Veranstaltungen für Entwickler auf dem Laufenden.

Teilen Sie:

https://a.storyblok.com/f/270183/400x409/b965ab37c0/oleksii-borysenko.png
Oleksii BorysenkoVonage Ehemalige

Oleksii ist ein Developer Advocate bei Vonage, Autor und Geschichtenerzähler. Seine Interessen umfassen KI/ML, Unified Communications, Bildungstechnologien, Cloud-Technologien und Open Source.