
Teilen Sie:
Benjamin Aronov ist ein Entwickler-Befürworter bei Vonage. Er ist ein bewährter Community Builder mit einem Hintergrund in Ruby on Rails. Benjamin genießt die Strände von Tel Aviv, das er sein Zuhause nennt. Von Tel Aviv aus kann er einige der besten Startup-Gründer der Welt treffen und von ihnen lernen. Außerhalb der Tech-Branche reist Benjamin gerne um die Welt auf der Suche nach dem perfekten Pain au Chocolat.
Text-to-Speech-Anrufe mit Python auf AWS Lambda und Vonage
Lesedauer: 10 Minuten
Einige Abläufe der Vonage Voice API umfassen mehrere Hin- und Rückläufe: Sie stellen den Anruf her, Vonage löst Ihren Antwort-Webhook aus, Sie warten auf die Tastatureingabe, spielen eine Folgeansage ab und erfassen das Ergebnis. Bei einem PIN-Verifizierungsablauf sind das vier oder fünf Webhook-Interaktionen, bevor Sie wissen, ob der Nutzer den richtigen Code eingegeben hat.
Wenn Ihre Hauptanwendung bereits andere Aufgaben übernimmt, wird die Einbettung dieser Koordination inline schnell unübersichtlich. Eine kleine serverlose Funktion, die den gesamten Aufrufablauf verwaltet und einen einzigen Ergebnis-Callback auslöst, ist eine übersichtlichere Lösung.
Diese Funktion werden Sie hier bereitstellen. Am Ende dieses Tutorials verfügen Sie über eine Python-Anwendung auf AWS Lambda, die:
Ruft eine Nummer an und spielt eine konfigurierbare Begrüßungsansage ab.
Wartet darauf, dass der Empfänger eine PIN eingibt.
Bei einer falschen Eingabe wird eine Fehlermeldung ausgegeben und der Vorgang bis zu dreimal wiederholt.
Beendet den Anruf nach drei fehlgeschlagenen Versuchen, ohne eine Meldung anzuzeigen.
Sendet nach Beendigung des Anrufs einen Callback an Ihren Webhook mit der Transaktions-ID und dem Ergebnis der PIN-Eingabe.
Damit wird die veraltete TTS-Prompt-API durch einen wartungsfreundlichen, serverlosen Ansatz ersetzt, den Sie vollständig selbst steuern können.
Tldr; Sehen Sie sich das fertige Beispiel im GitHub-Repository der Vonage-Community.
Bevor Sie beginnen
Was ist AWS Lambda?
AWS Lambda ist ein serverloser Rechendienst von Amazon Web Services. Sie schreiben eine Funktion, stellen sie bereit, und AWS führt sie bei Bedarf als Reaktion auf eine HTTP-Anfrage oder ein Ereignis aus. Es müssen keine Server bereitgestellt, aktualisiert oder skaliert werden. Lambda übernimmt all das, und Sie zahlen nur für die tatsächlich genutzte Rechenzeit.
In diesem Tutorial werden vier AWS-Dienste behandelt:
Lambda: die Funktion, die Ihre Aufruflogik ausführt.
API-Gateway: die HTTP-Schicht, die Ihre Lambda-Funktion als eine Reihe von URLs bereitstellt, auf die Vonage zugreifen kann.
DynamoDB: Ein Schlüssel-Wert-Speicher, der den Aufrufstatus zwischen Lambda-Aufrufen speichert.
IAM: Die Berechtigungsrichtlinien, die es Lambda ermöglichen, auf DynamoDB zuzugreifen und dort Daten zu schreiben sowie Protokolle in CloudWatch zu schreiben.
Chalice, das hier verwendete Framework, erstellt alle vier automatisch und verbindet sie miteinander, wenn Sie chalice deploy.
So sieht eine erfolgreiche Umsetzung aus
So sehen die beiden Abläufe nebeneinander aus.
Ohne Lambdamuss Ihr Anwendungsserver bei jedem Schritt des Aufrufs involviert bleiben:
Ihr Server tätigt den Anruf über die Vonage-API.
Vonage löst den Antwort-Webhook Ihres Servers aus. Ihr Server gibt einen NCCO zurück.
Vonage übermittelt die PIN-Ziffern an den Eingabe-Webhook Ihres Servers. Ihr Server überprüft die PIN.
Wenn die PIN falsch ist, gibt Ihr Server einen neuen NCCO für einen erneuten Versuch zurück und wartet auf einen weiteren Eingabe-Webhook.
Nach bis zu drei Versuchen speichert Ihr Server das Ergebnis und fährt fort.
Ihre Hauptanwendung ist für die gesamte Dauer des Aufrufs für den Webhook-Datenverkehr gesperrt, und Sie müssen den Status der Wiederholungsversuche im Arbeitsspeicher oder in einer Datenbank auf Ihrer Seite verwalten.
Bei Lambdaist Ihr Server nur zu Beginn und am Ende beteiligt:
Ihr Server sendet eine einzelne POST-Anfrage an den Lambda-Endpunkt
/callEndpunkt mit der Nummer, der PIN und einer Callback-URL.Lambda stellt den Anruf her und verarbeitet jeden Vonage-Webhook selbst: Anrufannahme, Eingabe, Wiederholungsversuch und Auflegen.
Sobald der Aufruf einen Endzustand erreicht hat, sendet Lambda einen Callback mit der Transaktions-ID und dem Ergebnis an Ihren Server (
ok,failedodererror).
Ihr Server sendet eine Anfrage und wartet auf einen Rückruf. Lambda und DynamoDB übernehmen dabei die gesamte Zustandsverwaltung und die Wiederholungsversuche.
Voraussetzungen
Bevor Sie beginnen, vergewissern Sie sich, dass Sie Folgendes zur Hand haben:
Ein AWS-Account. Diese Anwendung läuft im Rahmen der kostenlosen AWS Lambda-Nutzungsstufe.
AWS CLI (Installationsanleitung) muss installiert und mit Ihren Anmeldedaten konfiguriert sein.
Kelch (Dokumentation) auf Ihrem Rechner installiert sein. Installieren Sie es mit:
pip install chalice
Ein Vonage-API-Account. Registrieren Sie sich kostenlos , falls Sie noch keines haben. Sie benötigen Ihren API-Schlüssel, Ihr API-Geheimnis und eine Vonage-Application mit einem privaten Schlüssel.
Eine Vonage-Application, bei der die Voice-Funktionen aktiviert sind und der private Schlüssel lokal gespeichert ist als
private.key. Notieren Sie sich die Anwendungs-ID.Eine virtuelle Vonage-Nummer, die mit Ihrer Anwendung verknüpft ist. Sie können eine solche Nummer unter „Numbers > Nummern kaufen“ im Vonage-Dashboard erwerben.
Hinweis: Dieses Tutorial wurde mit Python 3.11, Chalice 1.33, AWS CLI 2.x und Version 4.x des Vonage Python SDK getestet. Version 4 des SDK wurde von Grund auf neu geschrieben und ist nicht mit Code aus Version 3 kompatibel. Wenn Sie anhand eines älteren Tutorials arbeiten, lesen Sie bitte den Leitfaden zur Migration von v3 auf v4.
Bereitstellen und Konfigurieren
Die Funktion bereitstellen
Klonen Sie das Repository auf Ihren lokalen Rechner:
git clone https://github.com/Vonage-Community/blog-voice-python-tts_prompt_calls_aws_lambda.git
Wechseln Sie in den Projektordner:
cd blog-voice-python-tts_prompt_calls_aws_lambda
Stellen Sie die Funktion in Ihrem AWS-Account bereit:
chalice deployChalice fordert Sie auf, die IAM-Ausführungsrichtlinie zu bestätigen. Überprüfen Sie die aufgeführten Berechtigungen und geben Sie y , um fortzufahren:
Initial creation of lambda function.
Updating IAM policy.
The following actions will be added to the execution policy:
dynamodb:CreateTable
dynamodb:GetItem
dynamodb:PutItem
dynamodb:UpdateItem
logs:CreateLogGroup
logs:CreateLogStream
logs:PutLogEvents
Would you like to continue? [Y/n]: y
Creating deployment package.
Initiating first time deployment...
Deploying to: api
https://910e9mcan2.execute-api.us-east-1.amazonaws.com/api/
Die letzte Zeile ist die Basis-URL Ihrer bereitgestellten Funktion. Speichern Sie diese. Sie benötigen sie in den nächsten Schritten. Sie können sie jederzeit abrufen, indem Sie folgenden Befehl ausführen: chalice url.
DynamoDB einrichten
Die Funktion nutzt AWS DynamoDB, um den Anrufstatus zwischen den Interaktionen zu speichern. Jeder von Vonage gesendete Webhook ist ein separater Lambda-Aufruf, der keine Informationen über den vorherigen Aufruf enthält. Daher müssen die PIN, die Nachrichten und die Anzahl der Versuche an einer Stelle außerhalb der Funktion gespeichert werden.
Erstellen Sie nach dem ersten Deployment die erforderliche Tabelle, indem Sie eine HTTP-GET-Anfrage an den /setup Endpunkt:
curl "$(chalice url)setup"
Beachten Sie, dass chalice url bereits mit einem Schrägstrich endet, sodass vor setup. Das musst du nur einmal tun: Der Endpunkt ist idempotent, und ein erneuter Aufruf gibt einfach {"result": "already exists"}.
Anruf auslösen
Die Funktion aufrufen
Nachdem die Funktion bereitgestellt wurde, lösen Sie einen Aufruf aus, indem Sie eine HTTP-POST-Anfrage an <your-base-url>call mit den folgenden Parametern:
Parameter | Wert | Beispiel |
|---|---|---|
| Die zu wählende Nummer im E.164-Format, ohne vorangestellte |
|
| Die Vonage-Nummer in Ihrem Account, die als Anrufer-ID verwendet werden soll |
|
| Die Begrüßungsnachricht, die dem Empfänger abgespielt wurde |
|
| Die PIN, die der Empfänger eingeben soll (nur Ziffern, maximal 20) |
|
| Die URL, an die das Ergebnis gesendet wird |
|
| Die für den Callback verwendete HTTP-Methode |
|
| Die Ansage, die nach erfolgreicher PIN-Eingabe abgespielt wird |
|
| Die Meldung, die bei der Eingabe einer falschen PIN abgespielt wurde |
|
Authentifizierung
Die Lambda-Funktion speichert Ihre Vonage-Anmeldedaten nicht. Sie übermitteln diese bei jeder Anfrage, und sie werden ausschließlich für diesen Aufruf verwendet.
Sie haben zwei Authentifizierungsmöglichkeiten: Sie können Ihren privaten Schlüssel direkt in einer cURL-Anfrage übergeben oder ein JWT generieren und es als Bearer-Token senden. Der /call Endpunkt akzeptiert sowohl Form-Encoded- als auch JSON-Body-Daten, sodass beide Varianten für dieselbe Route funktionieren. Der JWT-Ansatz wird empfohlen. Ihr privater Schlüssel verlässt Ihren Rechner zu keinem Zeitpunkt, und das stattdessen gesendete Token ist kurzlebig und auf eine einzelne Application beschränkt.
cURL (Authentifizierung mit privatem Schlüssel)
Ersetzen Sie die URL durch Ihre eigene Basis-URL, bevor Sie das Programm ausführen:
curl -X "POST" "https://<your-base-url>/call" \
--data-urlencode "private_key=$(cat private.key)" \
-d "app_id=<your-application-id>" \
-d "to=<recipient-number>" \
-d "from=<your-vonage-number>" \
-d "text=Enter the PIN" \
-d "pin_code=1234" \
-d "callback=https://example.com/callback" \
-d "callback_method=post" \
-d "bye_text=Thank you" \
-d "failed_text=Try again"Wichtig: Geben Sie Ihre private.key Datei. Halten Sie sie aus der Versionskontrolle heraus und machen Sie sie nicht in gemeinsam genutzten Befehlsverläufen oder Skripten sichtbar.
Python (JWT)
Installieren Sie das Vonage Python SDK und „requests“:
pip install "vonage>=4,<5" requests
Das SDK nutzt eine Monorepo-Struktur, sodass durch die Installation des vonage Paket wird automatisch vonage-jwtmit ein, das Sie zum Signieren des Tokens verwenden werden. Eine separate Installation ist nicht erforderlich.
Erstellen Sie ein JWT mit Ihrer Anwendungs-ID und Ihrem privaten Schlüssel und senden Sie es anschließend als Bearer-Token:
import requests
from vonage_jwt import JwtClient
APP_ID = "your-vonage-application-id"
PRIVATE_KEY = "./private.key" # A file path, or the key contents as a string
jwt_client = JwtClient(APP_ID, PRIVATE_KEY)
token = jwt_client.generate_application_jwt().decode()
data = {
"to": "TO_NUMBER",
"from": "CALLERID_NUMBER",
"text": "Enter the PIN",
"pin_code": "1234",
"callback": "https://example.com/callback",
"callback_method": "post",
"bye_text": "Thank you",
"failed_text": "Try again",
}
response = requests.post(
"https://<your-base-url>/call",
json=data,
headers={"Authorization": f"Bearer {token}"},
)
print(response.json())
Ein Detail, bei dem man kurz innehalten sollte: generate_application_jwt() gibt Bytes zurück, keinen String. Lassen Sie das .decode() und der f-String interpoliert stattdessen problemlos den `repr`-Wert, was Authorization: Bearer b'eyJhbGci...' und dir einen 401-Fehler beschert, der überhaupt nicht nach einem Kodierungsproblem aussieht.
Die Methode akzeptiert außerdem ein optionales Wörterbuch mit Claims, falls Sie die Standardwerte überschreiben möchten. Ein wichtiger Standardwert: Tokens verfallen nach 15 Minuten. Ein Aufruf zur PIN-Abfrage umfasst mehrere Webhook-Roundtrips und die Eingabe durch einen Benutzer über eine Tastatur. Wenn Sie also davon ausgehen, dass sich die Empfänger Zeit lassen, oder wenn Sie Aufrufe in eine Warteschlange stellen, anstatt sie sofort auszuführen, sollten Sie eine längere Ablaufzeit festlegen:
import time
claims = {"exp": int(time.time()) + 3600} # One hour
token = jwt_client.generate_application_jwt(claims).decode()Die maximal zulässige Gültigkeitsdauer eines JWT beträgt 24 Stunden. Halten Sie diese so kurz wie möglich, soweit es Ihr Ablauf zulässt.
Bei beiden Methoden ist die Antwort ein JSON-Objekt, das eine Transaktions-ID enthält:
{ "tid": "6a2827c9-4c68-46fc-b179-115f055dc0eb" }Speichern Sie den tid Wert. Er dient als Referenz für den Aufruf und wird im Callback angezeigt, sobald die Interaktion abgeschlossen ist.
So funktioniert der Anrufablauf
Sobald ein Anruf getätigt wird, steuert Vonage den Ablauf über eine Reihe von Webhooks. Hier erfahren Sie, was in den einzelnen Schritten geschieht.
Die PIN abrufen
Der vom NCCO zurückgegebene „your answer“-Webhook ist der Ort, an dem die eigentliche Arbeit stattfindet. Er spricht Ihre Nachricht aus und sammelt anschließend die Ziffern:
[
{
"action": "talk",
"text": "Enter your PIN",
"language": "en-US",
"style": 0,
"bargeIn": True,
},
{
"action": "input",
"type": ["dtmf"],
"dtmf": {"maxDigits": 4, "timeOut": 10, "submitOnHash": False},
"eventUrl": ["https://<your-base-url>/input/<tid>?attempt=1"],
"eventMethod": "POST",
},
]
Die input Aktion stellt Entwickler an zwei Stellen vor Probleme.
Erstens müssen die Eingabetypen explizit in einem type Array explizit deklariert werden müssen, wobei die DTMF-Optionen (Dual-Tone Multi-Frequency) unter einem dtmf Taste verschachtelt werden. In älteren Beispielen wurde ein pauschaler maxDigits direkt auf die Aktion gesetzt; diese Form wird nicht mehr akzeptiert.
Der zweite Punkt betrifft die Form der Rückmeldung. Vonage stellt das Ergebnis eventUrl wie folgt (vollständige Referenz zum Eingabeereignis):
{
"from": "14155550101",
"to": "14155550100",
"dtmf": { "digits": "1234", "timed_out": false },
"uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2026-01-01T12:00:00.000Z"
}
dtmf ist ein Objekt, keine Zeichenkette. Ein direkter Vergleich mit der erwarteten PIN schlägt jedes Mal stillschweigend fehl: Der Code sieht korrekt aus, es wird keine Ausnahme ausgelöst, und jedem Aufrufer wird mitgeteilt, dass seine korrekte PIN falsch war. Lesen Sie dtmf["digits"].
bargeIn Bei der talk Aktion ermöglicht es dem Empfänger, bereits mit der Eingabe zu beginnen, bevor die Nachricht vollständig abgespielt wurde – was für jeden, der die Ansage bereits kennt, wichtiger ist, als es zunächst klingt. Dies erfordert eine input Aktion unmittelbar danach.
Rückrufe
Nach Beendigung des Anrufs sendet die Lambda-Funktion eine POST- (oder GET-)Anfrage an die von Ihnen angegebene Webhook-URL. Der Callback enthält die folgenden Parameter:
Parameter | Wert | Beispiel |
|---|---|---|
| Die im E.164-Format angegebene Rufnummer |
|
| Die Transaktions-ID |
|
| Das Ergebnis des Telefonats |
|
Das status Feld enthält einen der folgenden Werte:
ok: Der Anruf wurde abgeschlossen und der Empfänger hat die richtige PIN eingegeben.failed: Der Anruf wurde verbunden, aber der Empfänger hat innerhalb von drei Versuchen nicht die richtige PIN eingegeben.error: Der Anruf wurde nicht zustande gebracht (besetzt, abgelehnt, unbeantwortet, abgebrochen oder vor der Eingabe der PIN aufgelegt).
Bei diesem letzten Punkt lohnt es sich, sorgfältig vorzugehen. Es ist verlockend, den Callback nur dann auszulösen, wenn der Aufrufstatus completed, doch completed bedeutet, dass der Anruf verbunden wurde und bis zum Ende ausgeführt wurde. Ein Anruf, der nie beantwortet wurde, erreicht den Endstatus unanswered, und wenn Sie nicht darauf achten, wartet Ihre Anwendung ewig auf ein Ergebnis, das niemals eintrifft. Die Funktion behandelt completed, failed, rejected, busy, cancelled, unanswered, sowie timeout als Terminal und erstellt Berichte über alle diese.
Nächste Schritte
Ihre Funktion ist live und führt echte Anrufe durch. Hier sind einige Punkte, die es sich lohnt, näher zu untersuchen:
Passen Sie die Anzahl der Wiederholungsversuche an.
MAX_ATTEMPTSOben auf der Seiteapp.pylegt fest, wie viele Versuche dem Empfänger gewährt werden.DTMF_TIMEOUTDaneben wird festgelegt, wie lange Vonage zwischen den einzelnen Ziffern wartet, bevor die Nummer übermittelt wird.Voice ändern. Die Vonage Voice API unterstützt mehrere Sprachen und Stimmen, die mit dem
languageundstylemit dentalkAktion festgelegt werden. (Ältere Beispiele verwendenvoiceName; dieser wurde durch dieses Paar ersetzt.) Beide werden alsTALK_LANGUAGEundTALK_STYLEUmgebungsvariablen verfügbar. Die vollständige Liste finden Sie in der Text-to-Speech-Dokumentation.Füge die Authentifizierung vor
/call. Der Endpunkt ist standardmäßig offen: Jeder, der die URL kennt, kann darüber Aufrufe tätigen. Ein API-Gateway-Autorisierer oder ein API-Schlüssel ist die Mindestvoraussetzung, bevor dies auch nur annähernd in die Produktion geht.DynamoDB bereinigen. Aufrufdetails werden nach jedem Aufruf in DynamoDB gespeichert und niemals gelöscht. Fügen Sie ein TTL-Attribut oder einen Bereinigungsjob hinzu, um die Speicherkosten zu verwalten.
Die Bereitstellung abbauen. Um alle in diesem Tutorial erstellten AWS-Ressourcen zu entfernen, führen Sie folgenden Befehl aus
chalice delete. Dadurch werden die Lambda-Funktion, die API-Gateway-Endpunkte und die zugehörige IAM-Rolle entfernt. Die DynamoDB-Tabelle wird nicht automatisch gelöscht; entfernen Sie sie separat über die AWS-Konsole oder mit der AWS-CLI.Entdecken Sie die Voice API. Die Überblick über die Vonage Voice API umfasst die gesamte Bandbreite an Optionen zur Anrufsteuerung, einschließlich Aufzeichnung, Konferenzschaltung und Bearbeitung eingehender Anrufe.
Zusammenfassung
Das haben Sie versandt:
Eine Lambda-Funktion, die auf API Gateway und DynamoDB basiert und mit einem einzigen
chalice deploy.Ein Anrufablauf, der Webhooks für die Annahme, die PIN-Erfassung, Wiederholungsversuche und das Auflegen verarbeitet, ohne dass Ihre Hauptanwendung daran beteiligt ist.
Zwei Authentifizierungswege: privater Schlüssel über cURL für schnelle Tests, JWT für alles, was im Code ausgeführt wird.
Zwei von der NCCO
inputaufgezeigte Fallstricke: Das erforderlichetypeArray unddtmf["digits"]anstelle vondtmfselbst.
Eine Anfrage rein, ein Rückruf raus. Lambda kümmert sich um alles dazwischen.
Teilen Sie:
Benjamin Aronov ist ein Entwickler-Befürworter bei Vonage. Er ist ein bewährter Community Builder mit einem Hintergrund in Ruby on Rails. Benjamin genießt die Strände von Tel Aviv, das er sein Zuhause nennt. Von Tel Aviv aus kann er einige der besten Startup-Gründer der Welt treffen und von ihnen lernen. Außerhalb der Tech-Branche reist Benjamin gerne um die Welt auf der Suche nach dem perfekten Pain au Chocolat.