){kind=small}
Synthèse vocale avec appels de relance, à l'aide de Python sur AWS Lambda
Temps de lecture : 5 minutes
L'API Nexmo Voice API offre une grande flexibilité dans les scénarios d'appel que vous pouvez activer, mais pour ce faire, vous devez souvent effectuer plusieurs interactions avec l'API. Pour certains scénarios, vous pouvez souhaiter disposer d'un seul appel d'API à partir de votre logique métier qui invoque une série d'interactions avec l'API Voice. C'est un scénario idéal pour construire une application sans serveur que vous pouvez ensuite appeler et la laisser gérer les interactions avec l'API Voice.
Dans cet exemple, nous allons vous montrer comment passer un appel Text to Speech qui diffusera un message à un destinataire puis lui demandera d'entrer quelques chiffres sur son clavier, par exemple pour confirmer un code PIN, vous obtiendrez alors un rappel vers une URL que vous aurez spécifiée une fois l'interaction terminée. Cette solution est très similaire à l'API TTS Prompt que Nexmo proposait, mais elle offre une plus grande flexibilité.
Actuellement, l'application appelle un numéro, diffuse un message initial et attend que l'utilisateur entre le code PIN que vous avez spécifié. S'il se trompe, un message d'erreur s'affiche et il peut réessayer, jusqu'à 3 tentatives sont autorisées, mais cela peut être modifié dans votre code.
S'ils ne parviennent pas à saisir le code PIN correct à la troisième tentative, l'appel sera interrompu sans message.
S'il réussit à saisir le code PIN, un autre message lui sera diffusé, puis l'appel prendra fin. Une fois l'appel terminé, vous recevrez un rappel sur votre webhook avec l'identifiant de transaction de l'appel et le résultat des tentatives de saisie du code PIN.
Voir le code source sur GitHub
Pour ce tutoriel, vous allez :
Besoin d'un Account AWS (vous pouvez exécuter ceci sur le niveau gratuit Lambda).
Disposer de l'outil outil AWS CLI et Chalice installés et configurés sur votre machine
Créez une application Nexmo Voice et enregistrez la clé privée dans un fichier local nommé
private.keyainsi qu'une note sur l'ID de l'Application
To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.
This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.
Pour déployer la fonction sur votre propre compte AWS :
Commencez par cloner le répertoire Git sur votre machine locale :
git clone https://github.com/nexmo-community/voice-ttsprompt-lambda.git
Basculer dans le dossier :
cd voice-ttsprompt-lambda
Déployer la fonction sur AWS :
chalice deploy
Vous verrez la sortie suivante lorsque votre fonction sera déployée, confirmez "Y" que vous voulez ajouter la politique d'exécution.
Initial creation of lambda function.
Updating IAM policy.
The following actions will be added to the execution policy:
dynamodb:PutItem
logs:PutLogEvents
dynamodb:CreateTable
logs:CreateLogStream
dynamodb:GetItem
logs:CreateLogGroup
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/La dernière ligne est l'URL de base de votre fonction nouvellement déployée, notez-la, vous pouvez la récupérer à tout moment avec la commande chalice url
Il y a très peu de choses à configurer car Chalice s'occupe de la plupart des configurations AWS lors du premier déploiement. Cependant, vous devrez créer la table DynamoDB qui est utilisée pour stocker l'état des appels. Pour ce faire, vous devez envoyer une requête HTTP GET à l'URL de votre fonction. /setup de votre fonction.
Vous pouvez maintenant invoquer votre nouvelle fonction avec une seule requête HTTP POST à votre URL de base avec /call à la fin. Vous devez passer les paramètres suivants
| Parameter | Value | Example |
|---|---|---|
| to | The number to be called in e.164 format | 14155550100 |
| from | The Nexmo number on your account to use for CallerID | 14155550101 |
| text | The initial message played to the called party | "Enter your pin" |
| pin_code | The PIN that the user should enter | 1234 |
| callback | The URL on your server where the result should be sent | http://example.com/callback |
| callback_method | The HTTP method used for your callback webhook | GET or POST |
| bye_text | The message to be played on a successful pin entry | "Thank you, goodbye" |
| failed_text | The message to be played on an incorrect pin with retry | "Incorrect, try again" |
L'application Lambda ne détient aucun de vos identifiants Nexmo au lieu de cela ceux-ci sont transmis au moment où vous invoquez la fonction et ne sont utilisés que pour cette requête.
Vous pouvez le faire de deux manières, soit en générant un JWT Nexmo avec nos bibliothèques et en le plaçant dans les en-têtes de la requête, soit en envoyant simplement la clé privée et l'identifiant de l'application dans le cadre d'une requête cURL. Il est recommandé d'utiliser la méthode d'authentification JWT.
Modifiez l'URL pour qu'elle corresponde à celle qui vous a été donnée lorsque vous avez déployé votre fonction.
curl -X "POST" "https://910e9mcan2.execute-api.us-east-1.amazonaws.com/api/call" \
--data-urlencode "private_key=`cat private.key`" \
-d "app_id=684027bc-a2e7-48b1-b4bd-adc02324e09c" \
-d "to=447970513607" \
-d "from=447520616161" \
-d "text='Enter the PIN'" \
-d "pin_code=1234" \
-d "callback=https://2bwz8nkbmfgc.runscope.net/callback" \
-d "callback_method=post" \
-d "bye_text='Thank You'" \
-d "failed_text='Try again'"
Modifiez l'URL pour qu'elle corresponde à celle qui vous a été donnée lorsque vous avez déployé votre fonction.
Vous aurez besoin de la bibliothèque Nexmo python : installez-la avec pip install nexmo
# you need the Nexmo client lib to generate your JWT
import nexmo
import requests
client = nexmo.Client(application_id=APP_ID, private_key=PRIVATE_KEY, key='dummy', secret='dummy')
headers = client._Client__headers()
data = {
'to': 'TO_NUMBER',
'from': 'CALLERID_NUMBER',
'text': 'Enter the pin',
'pin_code' : '1234',
'callback' : 'https://example.com/callback',
'callback_method' : 'post',
'bye_text' : 'thankyou',
'failed_text' : 'try again'
}
response = requests.post("https://910e9mcan2.execute-api.us-east-1.amazonaws.com/api/call", json=data, headers=headers)Pour l'une ou l'autre méthode, la réponse sera un objet JSON contenant un identifiant de transaction ("tid"). Il s'agit de la référence pour l'appel et elle sera utilisée dans le rappel avec le résultat.
Exemple de réponse : { "tid": "6a2827c9-4c68-46fc-b179-115f055dc0eb" }
Lorsque l'appel est terminé, la fonction Lambda fait une demande de rappel à un webhook que vous avez spécifié lorsque vous l'avez invoqué - cela contiendra des détails sur l'appel et le résultat :
| Parameter | Value | Example |
|---|---|---|
| to | The number called in e.164 format | 14155550100 |
| tid | The transaction ID | 6a2827c9-4c68-46fc-b179-115f055dc0eb |
| status | The result | ok |
Les valeurs d'état suivantes peuvent être renvoyées :
okl'appel a abouti et l'utilisateur a saisi le code PIN correctfailedl'appel a abouti mais l'utilisateur n'a pas saisi le bon code PINerror: l'appel n'a pas été achevé
Vous pouvez modifier le code pour ajuster des paramètres tels que le nombre de tentatives dont bénéficie l'utilisateur sur l'épingle, ou peut-être voulez-vous changer le nom de la personne qui a répondu à l'invitation. voiceName utilisés dans les messages-guides.
Les détails de chacun de vos appels seront stockés dans AWS DynamoDB, vous pouvez vouloir nettoyer ces entrées de temps en temps en fonction de vos besoins.