Partager:
){kind=small}
Liz Acosta est conseillère en développement chez Vonage. Si son parcours professionnel, d'étudiante en cinéma à spécialiste du marketing, puis ingénieur et enfin défenseur des développeurs, peut sembler peu conventionnel, il est tout à fait typique des relations avec les développeurs ! Liz aime les pizzas, les plantes, les carlins et Python.
Traiter un appel téléphonique entrant avec Python
Temps de lecture : 14 minutes
Dans ce tutoriel, vous apprendrez à utiliser l'interface Python FastAPI pour développer une application vocale qui reçoit des appels téléphoniques entrants en utilisant l Voice API de Vonage. Les logiciels qui reçoivent et acheminent les appels téléphoniques aident les entreprises à améliorer l'expérience de leurs clients. Il permet une assistance plus personnalisée et plus efficace. Ce tutoriel vous guidera à travers trois scénarios courants de flux d'appels d'assistance à la clientèle :
A la fin de ce tutoriel, vous comprendrez comment gérer efficacement les appels entrants avec Vonage en utilisant une application FastAPI Python et le logiciel ngrok. Ce guide vous donnera les moyens d'étendre les capacités de votre application pour vous connecter avec les utilisateurs en temps réel, ce qui rendra votre application plus interactive et plus engageante. Que vous construisiez une solution de service à la clientèle ou un outil de communication, la maîtrise de ces compétences améliorera la fonctionnalité et l'expérience utilisateur de votre projet.
Les applications vocales de Voice emploient objets de contrôle d'appel de Vonage (NCCO) pour construire des flux d'appels avec des actions NCCO. En d'autres termes, un NCCO est un tableau JSON d'actions qui peuvent contrôler les appels entrants. Un NCCO typique ressemble à ceci :
[
{"action": "talk",
"text": "Hello, one moment please, your call is being forwarded to our agent."},
{"action": "connect",
"from": VONAGE_NUMBER,
"endpoint": [{"type": 'phone',
"number": YOUR_SECOND_NUMBER}]}
]
Dans cet exemple particulier, il y a deux actions : talk et connect. Une action est généralement accompagnée d'un ensemble d'options clé-valeur configurables :
Pour l'action
talkl'optiontextfournit le script de synthèse vocale. Pour en savoir plus, consultez la documentation sur l'action documentation de l'action NCCO Talk.L'action
connectest configurée avec deux options :from, etendpoint. Voir la référence de l'action Référence de l'action NCCO Connect pour plus de détails sur la configuration.
Les talk et connect sont exécutées de manière synchrone dans l'ordre où elles sont énumérées. Certaines actions peuvent être configurées pour être asynchrones. Cela peut s'avérer utile lors de l'élaboration d'un flux d'appels dans lequel un appelant peut choisir parmi un menu d'options, comme la sélection d'une langue. Dans un tel scénario, vous ne voudriez pas que l'appelant doive attendre la fin du menu des langues pour poursuivre l'appel. C'est quelque chose qu'il faut faire de manière asynchrone. Pour comprendre comment cela fonctionne, consultez le guide des actions asynchrones du NCCO.
En résumé, les NCCO fournissent les éléments de base nécessaires à l'élaboration de flux d'appels sophistiqués adaptés à vos besoins spécifiques.
Pour mener à bien ce tutoriel, nous nous appuierons sur des concepts techniques et des outils extérieurs à Vonage qui peuvent être utiles dans d'autres domaines du développement logiciel.
Un webhook est la manière dont une application web transmet des données ou des notifications d'événements à une autre application de ce type, ce qui permet une communication automatique au lieu qu'une application doive constamment interroger l'autre pour obtenir des mises à jour. En général, il s'agit d'interagir sur le web via une API à l'aide d'une requête HTTP. Dans ce tutoriel particulier, nous utiliserons un webhook pour notifier à votre application web que quelqu'un a appelé votre numéro virtuel et pour renvoyer un NCCO des actions du flux d'appels.
FastAPI est un framework web de haute performance pour la construction d'API de services basés sur HTTP en Python. Ce qui différencie FastAPI des autres frameworks web Python, c'est son alignement étroit avec Pydanticune bibliothèque de validation de données pour Python. Ce couplage permet à FastAPI de valider, sérialiser et désérialiser les données. Cela fournit une méthode plus déclarative pour spécifier la structure et les types de données pour les requêtes entrantes telles que les corps HTTP et les réponses sortantes. FastAPI génère également automatiquement des fichiers OpenAPI automatiquement. Toutes ces caractéristiques combinées le rendent particulièrement adapté aux API REST modernes, au développement de microservices et aux applications qui nécessitent des fonctionnalités en temps réel.
Dans ce tutoriel, nous allons créer une application web et l'exécuter localement sur votre machine. Comme elle sera exécutée localement, elle ne pourra pas être accédée par l'Internet public, et si votre application Web ne peut pas être accédée, alors Vonage ne pourra pas faire de demande au webhook. C'est là que le tunneling entre en jeu. Le tunneling expose les serveurs locaux à l'internet public par le biais d'URL publiques temporaires ou statiques. ngrok est une plateforme logicielle qui fournit ce service.
En résumé, nous allons créer une application web FastAPI Python avec un webhook et utiliser ngrok pour rendre votre application locale accessible via un tunnel vers une URL publique afin que Vonage puisse réellement poster vers le webhook et traiter un appel entrant comme défini dans le code.
Dans ce tutoriel, nous utiliserons FastAPI pour définir un webhook auquel l'API Voice peut adresser une requête lorsque quelqu'un appelle votre numéro virtuel. Nous utiliserons ngrok pour exposer le webhook à l'internet public. Et nous utiliserons Vonage pour acheter un numéro virtuel ainsi que l'API Voice pour compléter le traitement des appels entrants.
Si vous préférez, vous pouvez extraire le code pour traitement d'un appel entrant sur le GitHub de la communauté Vonage.
Pour réaliser ce tutoriel, vous aurez besoin des éléments suivants :
Python 3.8+
Un Un Account ngrok et l'installation
Un numéro de téléphone supplémentaire pour servir d'"agent" à contacter
Avant de commencer à construire, mettons tout en ordre.
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.
L'API Voice doit pouvoir accéder à votre webhook afin de pouvoir lui adresser des requêtes. L'URL du point de terminaison doit donc être accessible sur l'internet public.
Pour ce faire, nous utiliserons dans ce tutoriel le logiciel ngrok. Consultez notre tutoriel ngrok pour apprendre à l'installer et à l'utiliser.
Dans une fenêtre de terminal, créez un répertoire pour ce projet et naviguez-y :
mkdir vonage-inbound-call && cd vonage-inbound-call
Maintenant que tout est prêt, il est temps de commencer à construire.
Ce tutoriel vous guidera à travers trois flux d'appels différents :
Avant d'aborder chaque scénario, nous allons d'abord créer une application Vonage et préparer notre environnement de développement en effectuant les opérations suivantes :
L'API Voice doit pouvoir accéder à votre webhook afin de pouvoir lui adresser des requêtes. Pour ce faire, l'URL du point de terminaison doit être exposée à l'internet public. C'est à cela que sert ngrok.
Dans une fenêtre de terminal séparée, exécutez :
ngrok http 3000Cette commande générera les URLs publiques vers lesquelles votre serveur local se connectera sur le port 3000. Prenez note de l'URL publique - elle devrait ressembler à ceci :
Forwarding https://0a6ec0a950eb.ngrok-free.app -> http://localhost:3000
Vous devez d'abord créer une application Voice API. L'"application" dont il est question ici est un conteneur pour les informations de configuration et de sécurité dont vous avez besoin pour l'API Voice. Il ne s'agit pas de la même chose que l'application web FastAPI que nous allons également créer.
Créez votre application Voice API dans le tableau de bord du développeur en accédant à la section Applications dans le menu de gauche et en cliquant sur le bouton "Créer une nouvelle application". Le menu de création de l'application s'ouvre alors. Donnez un nom à votre application inbound-call.
Dans le cadre de la Capacités cochez l'option pour Voicece qui fait apparaître une liste de champs de texte. Dans le champ de texte intitulé URL de réponseindiquez l'URL publique ngrok modifiée avec le webhook que vous avez défini dans votre application FastAPI. Cela ressemblera à quelque chose comme : https://96b34a48a639.ngrok-free.app/webhooks/answer.
Cliquez sur le bouton "Générer une nouvelle application".
A screenshot of the Create an application menu in the Vonage developer dashboard.Maintenant que votre application a été créée, vous pouvez y associer votre numéro en cliquant sur le bouton lier dans le tableau des numéros disponibles. Votre application est maintenant prête à répondre aux appels entrants. Les scénarios que nous allons coder indiquent à l'application ce qu'elle doit faire lorsque le crochet Web est appelé. /answer est appelé.
Les environnements virtuels Python vous permettent d'installer des paquets dans un endroit isolé du reste de votre système. Cela permet d'éviter l'encombrement du système et les conflits avec les différentes versions de Python et les différents paquets. Consultez notre article de blog sur les environnements virtuels pour en savoir plus.
Dans le répertoire de votre projet, exécutez les commandes suivantes pour créer et activer un environnement virtuel :
python3 -m venv venv && source venv/bin/activateVous devriez maintenant voir l'invite de votre terminal préfacée par (venv). Pour désactiver votre environnement virtuel, exécutez la commande deactivate pour désactiver votre environnement virtuel.
Afin d'installer les dépendances dont nous avons besoin pour ce tutoriel, exécutez ce qui suit :
pip install vonage python-dotenv 'fastapi[standard]'Nous avons maintenant tout ce qu'il faut pour commencer à coder.
Dans ce scénario particulier, nous répondrons à un appel entrant vers un numéro virtuel en diffusant un message de synthèse vocale.
Créez un fichier appelé scenario-1.py qui contient le code suivant :
from fastapi import FastAPI, Query
from vonage_voice import Talk
app = FastAPI()
@app.get('/webhooks/answer')
async def answer_call(from_: str = Query(..., alias='from')):
from_ = '-'.join(from_)
return [Talk(text=f'Thank you for calling from {from_}').model_dump(by_alias=True, exclude_none=True)]
Ce code crée le /webhooks/answer . Lorsque ce point d'accès reçoit une requête de l'API Voice, il crée et itère à travers un fichier NCCO avec une Talk action. C'est cette liste qui est responsable de la synthèse vocale que l'appelant entend lorsqu'il compose le numéro. Pour en savoir plus sur la réponse aux appels avec la synthèse vocale, consultez nos exemples de code.
Il est maintenant temps de tester votre application.
Dans votre fenêtre de terminal, exécutez :
fastapi dev --port 3000 scenario-1.pyCela va démarrer un serveur local avec votre point de terminaison webhook sur le port 3000. Votre application est prête à recevoir des appels !
Appelez le numéro virtuel que vous avez lié à l'application dans le tableau de bord. Si tout fonctionne correctement, vous devriez être accueilli par le message de synthèse vocale que vous avez défini dans votre code Python.
Après les tests, mettez fin au serveur afin de pouvoir coder le scénario suivant.
Dans ce scénario, nous inclurons l'action NCCO Connect qui mettra l'appelant en contact avec un agent après avoir terminé l'action. Talk l'action.
Créez un nouveau fichier appelé scenario-2.py et ajoutez le code suivant :
from fastapi import FastAPI, Query
from vonage_voice import Talk, Connect, NccoAction, PhoneEndpoint
VONAGE_VIRTUAL_NUMBER = 'Replace-this-text-with-your-Vonage-virtual-number'
AGENT_NUMBER = 'Replace-this-text-with-your-agent-number'
app = FastAPI()
@app.get('/webhooks/answer')
async def answer_call():
ncco: list[NccoAction] = [
Talk(text="Hello, one moment please while your call is being forwarded to our agent."),
Connect(from_=VONAGE_VIRTUAL_NUMBER,
endpoint=[PhoneEndpoint(number=AGENT_NUMBER)]),]
return [action.model_dump(by_alias=True, exclude_none=True) for action in ncco]Ce code crée le /webhooks/answer . Lorsque ce point d'accès reçoit une requête de l'API Voice, il crée et itère à travers un fichier NCCO avec une action Talk puis une action Connect action. L'action Connect action vous demande de fournir à la fois votre numéro virtuel Vonage et un numéro d'agent supplémentaire pour les variables VONAGE_VIRTUAL_NUMBER et AGENT_NUMBERrespectivement. Pour en savoir plus sur la connexion d'appels avec la Voice API ici.
Arrêtez toutes les applications en cours d'exécution provenant d'autres scénarios de ce tutoriel et exécutez-les :
fastapi dev --port 3000 scenario-2.pyPour tester ce scénario particulier, vous aurez besoin de deux numéros de téléphone : Un pour appeler le numéro virtuel avec et un autre numéro de téléphone pour se connecter. Composez votre numéro virtuel Vonage et si tout a été mis en œuvre correctement, vous devriez être accueilli par le message de synthèse vocale, puis votre deuxième numéro (le numéro de l'agent) devrait sonner.
Dans ce scénario, nous traitons un appel entrant en mettant l'appelant en attente et en diffusant de la musique jusqu'à ce qu'un agent soit disponible. L'appel est ensuite transféré à l'agent.
Il s'agit du flux d'appels que nous allons mettre en œuvre :
Lorsque l'appel est pris, l'appelant entend un message vocal.
L'appelant est mis en attente et de la musique lui est diffusée.
Après un délai simulé de 30 secondes, l'appel est transféré à un deuxième agent de liaison national.
Le deuxième NCCO diffuse un message vocal et met l'appelant en relation avec un agent.
Étant donné que ce scénario particulier utilise l Voice API pour mettre à jour un appel en coursnous avons besoin de l'identifiant de l'application Vonage et d'une clé privée pour créer un client. Cela permet de s'assurer que l'utilisateur qui effectue la mise à jour est autorisé et qu'il est propriétaire de l'appel - il serait assez déstabilisant d'entendre soudainement de la musique d'attente lors d'un appel avec un ami ! L'identifiant de l'application et la clé privée peuvent être obtenus via le tableau de bord des développeurs de Vonage.
Dans le menu Applications du tableau de bord du développeur, cliquez sur l'application que vous avez créée pour ce tutoriel, puis sur "Modifier." Une fois la fenêtre d'édition ouverte, cliquez sur le bouton "Generate public and private key". Cela déclenchera le téléchargement de votre clé privée sous la forme d'un fichier portant l'extension .key. Gardez ce fichier privé et ne le partagez pas dans un endroit où il pourrait être compromis. Cliquez sur le bouton "Enregistrer les modifications" et notez également votre ID de l'application.
A screenshot of the application Edit menu in the Vonage developer dashboard showing where to generate a public and private key.
A screenshot of the inbound-call application in the Vonage developer dashboard showing where you can find the application ID.Déplacez votre fichier de clé privée dans le même répertoire que celui où se trouve votre code Python. Dans le même répertoire, créez un fichier appelé .env et ajoutez-y ce qui suit :
APPLICATION_ID=Replace-this-with-your-application-ID
PRIVATE_KEY=Replace-this-with-the-name-of-your-private-key-file
Créez un nouveau fichier appelé scenario-3.py et ajoutez le code suivant :
import os
from dotenv import load_dotenv
from threading import Timer
from fastapi import FastAPI, Query
from vonage import Auth, Vonage
from vonage_voice import Talk, Connect, NccoAction, PhoneEndpoint, Stream
load_dotenv()
APPLICATION_ID = os.getenv("APPLICATION_ID")
PRIVATE_KEY = os.getenv("PRIVATE_KEY")
VONAGE_VIRTUAL_NUMBER = '**********' # Replace with your Vonage virtual number
AGENT_NUMBER = '**********' # Replace with your "agent" number
AUDIO_URL = "https://download.samplelib.com/mp3/sample-12s.mp3"
app = FastAPI()
def transfer_call(call_id):
print("Transferring the call ... ")
ncco: list[NccoAction] = [
Talk(text="Hello, one moment please while your call is being forwarded to our agent."),
Connect(from_=VONAGE_VIRTUAL_NUMBER,
endpoint=[PhoneEndpoint(number=AGENT_NUMBER)]),]
client = Vonage(Auth(application_id=APPLICATION_ID, private_key=PRIVATE_KEY,))
client.voice.transfer_call_ncco(uuid=call_id, ncco=ncco)
@app.get('/webhooks/answer')
async def answer_call(call_id: str = Query(..., alias='uuid')):
print(f"The UUID for this call is:====> {call_id}")
Timer(30, transfer_call, [call_id]).start()
ncco: list[NccoAction] = [
Talk(text="Hello, our agents are assisting other customers. Please hold and we will connect you as soon as possible."),
Stream(streamUrl=[AUDIO_URL],loop=0),]
return [action.model_dump(by_alias=True, exclude_none=True) for action in ncco]Il se passe beaucoup de choses dans ce code, alors décomposons-le.
Vous devez d'abord mettre à jour les variables suivantes :
VONAGE_VIRTUAL_NUMBER : Remplacez le texte de l'espace réservé par votre numéro virtuel Vonage.
AGENT_NUMBER : Remplacer le texte de remplacement par le numéro de téléphone de l'"agent" vers lequel l'appelant sera transféré.
Dans ce code, nous définissons le /webhooks/answer . Lorsque ce point d'accès reçoit une demande de l'API Voice, il crée et parcourt un fichier NCCO avec une action Talk puis une action Stream pour jouer la musique d'attente.
La fonction transfer_call se charge de la création d'un client Vonage et le transfert de l'appel en utilisant son numéro d'identification unique.
Puisque nous simulons ce que serait la mise en attente, le code utilise un objet Timer pour appeler la fonction transfer_call après 30 secondes.
Maintenant que vous avez compris le code, faisons-le fonctionner. Assurez-vous qu'aucune autre application n'est en cours d'exécution, puis exécutez :
fastapi dev --port 3000 scenario-3.pyPour tester ce scénario particulier, vous aurez besoin de deux numéros de téléphone : Un pour appeler le numéro virtuel avec et un autre numéro de téléphone pour se connecter. Composez votre numéro virtuel Vonage et si tout a été mis en œuvre correctement, vous devriez être accueilli par le message de synthèse vocale suivi d'une musique d'attente. Après 30 secondes, l'appel sera transféré au numéro d'agent que vous avez fourni.
Dans ce tutoriel, vous avez appris à gérer les appels téléphoniques entrants à l'aide de l'API Voice de Vonage et d'une application FastAPI Python. Vous avez exploré comment les objets de contrôle d'appel (NCCO) de Vonage définissent les flux d'appels et comment les webhooks permettent à votre application de répondre aux appels entrants en temps réel. À l'aide de trois scénarios pratiques, vous avez mis en œuvre des flux de travail d'assistance à la clientèle courants : lecture d'un message de synthèse vocale, mise en relation d'un appelant avec un agent et mise en attente d'un appelant avec de la musique avant le transfert de l'appel.
En outre, vous avez configuré une application Voice API, exposé un serveur FastAPI local à l'aide de ngrok et utilisé Voice API pour mettre à jour un appel en cours. Ces éléments fondamentaux peuvent considérablement améliorer les interactions avec les clients, les temps de réponse et la rationalisation des opérations pour les entreprises. Par exemple, vous pouvez créer un système de conférence téléphonique, construire des flux d'appels personnalisésou suivre les performances des campagnes.
Si vous souhaitez approfondir vos connaissances, vous pouvez consulter les articles suivants Applications Voice en Python ou Intégration de l'API pour découvrir des techniques plus avancées. La mise en œuvre de ces concepts peut ouvrir des possibilités d'expériences client personnalisées et d'automatisation susceptibles de favoriser la croissance et l'efficacité de l'entreprise.
Consultez la Référence de l'API Voice pour obtenir une liste exhaustive des éléments que vous pouvez intégrer dans vos applications vocales.
Vous pouvez également en savoir plus sur les actions du NCCO dans le officiel
Connecter votre serveur de développement local à l'API Vonage à l'aide d'un tunnel Ngrok
Vous avez une question ou souhaitez partager ce que vous construisez ?
Rejoignez la conversation sur le Communauté Vonage Slack
S'abonner à la Bulletin d'information du développeur
Suivez-nous sur X (anciennement Twitter) pour les mises à jour
Regardez les tutoriels sur notre chaîne YouTube
Connectez-vous avec nous sur la page Vonage Developer sur LinkedIn
Restez connecté et tenez-vous au courant des dernières nouvelles, astuces et événements concernant les développeurs.
Partager:
Liz Acosta est conseillère en développement chez Vonage. Si son parcours professionnel, d'étudiante en cinéma à spécialiste du marketing, puis ingénieur et enfin défenseur des développeurs, peut sembler peu conventionnel, il est tout à fait typique des relations avec les développeurs ! Liz aime les pizzas, les plantes, les carlins et Python.