Booster les appels vocaux avec la détection homme/machine de l'API de Vonage et Flask

Introduction

Dans certains scénarios d'entreprise, il est nécessaire d'établir une communication vocale avec les clients, où les contraintes de temps deviennent un facteur critique pour délivrer des messages vocaux de manière efficace, en particulier lorsque la main-d'œuvre disponible est limitée. Lorsqu'un agent lance un appel en composant un numéro de téléphone, il doit faire preuve de patience jusqu'à ce que l'appel soit pris par le destinataire, qui peut être un humain ou un système de messagerie vocale. Ces interactions consomment un temps et des ressources précieux.

Grâce à l'API Voice de Vonage et à ses capacités accrues de détection des personnes, des messages vocaux et des bips, il est possible d'automatiser l'ensemble du processus de communication avec une mise en œuvre minimale du code. En outre, la fonction sophistiquée de détection des machines garantit la transmission complète du message prévu. Le tutoriel suivant vous guide dans l'automatisation des appels vocaux, avec l'identification des entités humaines ou de la messagerie vocale. Le code source de cette application est disponible sur Github.

1. Les conditions préalables

Il y a des conditions préalables spécifiques à remplir avant d'utiliser l'API Voice de Vonage. Il s'agit notamment de créer un Account Vonage Developer, d'obtenir un numéro virtuel, de configurer un environnement Python ainsi que l'application Flask et l'application ngrok Ingress. Les sections suivantes décrivent ces conditions préalables en détail.

Créer un Account de développeur Vonage

Vonage est un fournisseur de communications de premier plan qui donne aux développeurs l'accès aux API pour envoyer de la voix, de la vidéo et des messages. En en vous inscrivant pour un Account gratuitvous aurez accès à un crédit gratuit et à une documentation pour utiliser les API de Vonage. Une fois que vous avez obtenu la clé et le secret de l'API, suivez la documentation pour créer une application vocale à l'aide de Dashboard. documentation pour créer une application vocale à l'aide de Dashboard et générer un JWT qui sera nécessaire dans les étapes suivantes. Vous pouvez en savoir plus sur la génération de JWT ici.

Vonage API Account

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.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Obtenir un numéro de téléphone virtuel

Une fois l'inscription terminée, obtenez un numéro de téléphone virtuel à partir du site web de Vonage. Dans certains pays, les numéros de téléphone sont nécessaires pour passer un appel, et l'identification de l'appelant "inconnu" n'est pas autorisée pour passer un appel. Il est donc fortement recommandé d'obtenir un numéro de téléphone virtuel à un prix modique.

Configuration du serveur Flask et de l'application ngrok Ingress

Un serveur web capable de communiquer avec un point de terminaison publié est nécessaire pour recevoir les événements de la progression de l'appel et émettre ensuite des éléments d'action. Flask est un cadre d'application web à faible encombrement qui utilise Python pour créer des applications web. Configurez le serveur Flask dans votre environnement à l'aide de la documentation officielle.

Pour accéder à une application Flask exécutée localement, vous avez besoin d'une URL publique accessible par Internet. Voici un ensemble d'instructions minimales pour vérifier si Python est installé et configurer Flask sur votre machine :

Vous pouvez utiliser ngrok pour héberger le serveur web sur votre machine locale et envoyer/recevoir des requêtes depuis le web. Il est recommandé d'installer la dernière version de ngrok. Voici un ensemble d'instructions minimales pour installer ngrok sur votre Mac et vérifier sa version :

Pour commencer, voici le code Python minimum pour démarrer le serveur flask et envoyer un message d'accueil "Hello World" :

from flask import Flask, request

app = Flask(__name__)

@app.route("/", methods=["GET", "POST"])
def callback_listener():
    print(f"event received --> {request.data}")
    return ("Hello world!", 200)

Enregistrez le code ci-dessus dans callback.py et exécutez-le à l'aide de la commande suivante :

Vous pouvez maintenant pointer votre navigateur vers l'adresse IP publique ou l'URL ngrok ingress pour voir si l'application est accessible via Internet et prête pour l'étape suivante.

2. Passer un appel Voice et suivre les événements

Maintenant que vous avez rempli les conditions préalables, il est temps de passer le premier appel vocal et de suivre la progression de cet appel vocal. Il existe plusieurs façons de passer un appel, notamment en utilisant le SDK dans Node.js, Python ou .NET. La méthode la plus simple consiste à utiliser la commande curl, que nous allons présenter ici.

L'exemple est tiré ici et modifié pour "action : talk". Pour passer un appel, utilisez la commande curl ou Postman en utilisant l'option import :

Remplacer le texte suivant par :

• YOUR_JWT = JWT généré à l'étape précédente

• YOUR_MOBILE_NUMBER = Numéro de portable pour recevoir l'appel vocal

• YOUR_VIRTUAL_NUMBER = Numéro virtuel obtenu à l'étape précédente

• YOUR_CALLBACK_URL = URL d'entrée de ngrok ou adresse IP publique de l'application serveur Flask

Si vous consultez les journaux de l'application Flask, vous verrez les détails de la progression de l'appel, du démarrage à la sonnerie.

event received --> b'{"headers":{},"from":"YOUR_VIRTUAL_NUMBER","to":"YOUR_MOBILE_NUMBER","uuid":"2dd98ea6-2518-4e54-8f3a-a8c532f131d6","conversation_uuid":"CON-51982b08-5337-480f-be09-81c3cda3f885","status":"started","direction":"outbound","timestamp":"2023-10-20T13:57:42.895Z"}'
event received --> b'{"headers":{},"from":"YOUR_VIRTUAL_NUMBER","to":"YOUR_MOBILE_NUMBER","uuid":"2dd98ea6-2518-4e54-8f3a-a8c532f131d6","conversation_uuid":"CON-51982b08-5337-480f-be09-81c3cda3f885","status":"ringing","direction":"outbound","timestamp":"2023-10-20T13:57:42.895Z"}'
event received --> b'{"start_time":null,"headers":{},"rate":null,"from":"YOUR_VIRTUAL_NUMBER","to":"YOUR_MOBILE_NUMBER","uuid":"2dd98ea6-2518-4e54-8f3a-a8c532f131d6","conversation_uuid":"CON-51982b08-5337-480f-be09-81c3cda3f885","status":"answered","direction":"outbound","network":null,"timestamp":"2023-10-20T13:57:47.191Z"}'
event received --> b'{"headers":{},"end_time":"2023-10-20T13:57:50.000Z","uuid":"2dd98ea6-2518-4e54-8f3a-a8c532f131d6","network":"23410","duration":"3","start_time":"2023-10-20T13:57:47.000Z","rate":"0.10000000","price":"0.00500000","from":"YOUR_VIRTUAL_NUMBER","to":"YOUR_MOBILE_NUMBER","conversation_uuid":"CON-51982b08-5337-480f-be09-81c3cda3f885","status":"completed","direction":"outbound","timestamp":"2023-10-20T13:57:49.611Z"}'

Félicitations pour avoir passé votre premier appel vocal automatisé. Si vous ne pouvez pas passer d'appel, il peut y avoir de nombreuses raisons pour lesquelles vous ne recevez pas d'appel sur votre téléphone portable. Il se peut que l'utilisateur n'ait pas été authentifié, que le JWT n'ait pas été correctement miné ou que le champ "from" n'ait pas été défini correctement. Vous pouvez toujours résoudre les problèmes d'appel en utilisant les données de la réponse de la commande et de l'outil Voice Inspector de Voice Inspector.

3. Ajout de la détection humaine/messagerie vocale à l'appel

Maintenant que vous pouvez passer un appel, il est temps d'ajouter des fonctions avancées pour détecter qui est à l'autre bout du fil. Il existe plusieurs scénarios possibles pour décrocher l'appel :

1. Un humain

2. Un message d'accueil pour la messagerie vocale

3. Un message d'accueil de la messagerie vocale suivi d'un bip sonore

Grâce à la fonction de détection humaine/messagerie vocale, chaque cas peut être traité de manière spécifique afin de délivrer correctement le message lors des appels vocaux.

Pour ajouter la reconnaissance humaine/voix, mettez à jour la commande curl avec l'option 'advanced_machine_detection' (des détails sur ce paramètre peuvent être trouvés ici) :

Si vous décrochez et dites " bonjour ", la Voice sera interprétée comme une voix humaine, et un événement " status : human " sera généré et envoyé dans le callback de la progression de l'appel, que vous pouvez voir dans les logs de l'application du serveur Flask :

event received --> b'{"call_uuid":"47f22bfd-ddb3-4a02-88be-9cb9673e0ae9","from":"<YOUR_VIRTUAL_NUMBER>","to":"<YOUR_MOBILE_NUMBER>","status":"human","conversation_uuid":"CON-d8ae51d1-6b93-426d-bbd0-2b1c059036ca","timestamp":"2023-10-20T14:34:43.014Z"}'

Les messages d'accueil de la messagerie vocale sont interprétés comme "status : machine", et si un bip est détecté après la messagerie vocale, un paramètre supplémentaire "sub_state : beep_start" sera envoyé dans le rappel. Tous ces événements peuvent être résumés comme suit :

1. Si l'appel est décroché par une personne -> "status" : "human"

2. Si l'appel est dirigé vers une boîte vocale qui n'a pas de bip après -> "status" : "machine" et ensuite "sub_state" : "beep_timeout" lorsque le timeout du beep se produit

3. Si l'appel va vers la messagerie vocale avec un bip -> d'abord "status" : "machine" et ensuite "sub_state" : "beep_start" lorsque le bip est détecté

La détection du bip est une fonction utile car elle vous indique précisément quand l'enregistrement de la messagerie vocale commence. Avec la détection du bip, le message laissé dans l'enregistrement sera tronqué et ne sera peut-être pas clair lorsqu'il sera écouté par la personne qui l'écoute, car il manquera la partie du message qui précède le bip.

4. Modification de la progression des appels sur la base de la détection humaine/courrier vocal

Utilisons les capacités de reconnaissance de la messagerie vocale pour modifier la progression des appels. Pour un scénario simple, supposons que vous souhaitiez diffuser des messages spécifiques en fonction de la détection humaine/de la messagerie vocale. Par exemple :

1. Diffusion d'un message "Je parle à un humain" lorsqu'une personne est détectée.

2. Diffusion d'un message "Je suis en train de parler à la boîte vocale avant le bip" lorsque la boîte vocale est détectée.

3. Diffusion d'un message "Je suis en train de parler à la messagerie vocale après le bip" lorsque le bip est détecté.

Notez que vous recevez déjà les résultats de la détection du voicemail dans la progression des appels via des callbacks ; il s'agit juste de traiter l'information et d'ajouter la logique de prise de décision dans votre code Flask. Voici le code Flask mis à jour qui sera capable de traiter la détection de la messagerie vocale et de générer la réponse attendue :

from flask import Flask, request

app = Flask(__name__)

play_to_human = "I am talking to human."
play_to_voicemail = "I am talking to voicemail before the beep."
play_after_beep = "I am talking to voicemail after the beep."

@app.route("/", methods=["GET", "POST"])
def callback_listener():
    ncco, message_to_play = "", ""
    if request.is_json and "status" in request.get_json():
        req_json = request.get_json()
        print(f'status received --> {req_json["status"]}')
        if req_json["status"] == "machine" and "sub_state" not in req_json:
            message_to_play = play_to_voicemail
        elif req_json["status"] == "machine" and "sub_state" in req_json:
            message_to_play = play_after_beep
        elif req_json["status"] == "human":
            message_to_play = play_to_human
        ncco = [{ "action": "talk", "text": message_to_play, "loop": 3 }] if message_to_play != "" else ""
        print(f'response to send --> {ncco}')
    else:
        print(f'event received --> {request.data}')
    return (ncco if ncco != "" else "", 200)

Renouvelez l'appel en utilisant la commande curl avec l'option advanced_machine_detection :

curl --location 'https://api-us.vonage.com/v1/calls' \
--header 'Authorization: Bearer <YOUR_JWT>' \
--header 'Content-Type: application/json' \
--data '{
    "to": [ { "type": "phone", "number": "<YOUR_MOBILE_NUMBER>" } ],
    "from": { "type": "phone", "number": "<YOUR_VIRTUAL_NUMBER>" },
    "advanced_machine_detection": { "behavior": "continue", "beep_timeout": "45" },
    "event_url": ["YOUR_CALLBACK_UR"], 
    "ncco": [
        { "action": "talk",
        "text": "This is a test call." }
    ]
}'

Dans l'exemple ci-dessus, l'appel sera lancé par une simple action de conversation :

{ "action": "talk", "text": "This is a test call." }

Au fur et à mesure que l'appel progresse, l'action de conversation sera remplacée par une autre action de conversation, en fonction de la détection humaine/de la messagerie vocale, par exemple :

In case if call is picked up by human (i.e. status: human):
{ "action": "talk", 
"text": "I am talking to human.", 
"loop": 3 }

In case if call goes to voicemail before the beep is detected (i.e status: machine):
{ "action": "talk", 
"text": "I am talking to voicemail before the beep.", 
"loop": 3 }

In case if call goes to voicemail and beep is detected (i.e. status:machine and sub_state: beep_start):
{ "action": "talk", 
"text": "I am talking to voicemail after the beep.", 
"loop": 3 }

5. Conclusion avec un exemple concret

Enfin, tirons parti de cette capacité d'appel vocal améliorée en reprenant un scénario réel. Imaginez que vous menez une campagne d'appels vocaux et que vous ne souhaitez prendre des appels qu'avec une personne réelle. Ainsi, si une personne prend l'appel, elle est connectée à votre numéro de téléphone. Dans le cas contraire, laissez un message après le bip si l'appel aboutit sur la messagerie vocale. Pour résumer le cas d'utilisation :

1. Connecter le téléphone du militant pour parler à la personne qui répond au téléphone

2. Sinon, laissez un message à la boîte vocale après le bip : "Nous avons essayé de vous joindre ; veuillez nous contacter immédiatement".

Voici le code Flask mis à jour qui sera capable de traiter la détection des messages vocaux et de générer la réponse attendue :

from flask import Flask, request

app = Flask(__name__)

action_when_human = { "action": "connect", "from": "<YOUR_VIRTUAL_NUMBER>", "endpoint": [{ "type": "phone", "number": "<CALL_CAMPAIGNER_PHONE_NUMBER>" }] }
action_when_beep = { "action": "talk", "text": "We tried to reach you, please contact us immediately."}

@app.route("/", methods=["GET", "POST"])
def callback_listener():
    ncco = ""
    if request.is_json and "status" in request.get_json():
        req_json = request.get_json()
        if req_json["status"] == "machine" and "sub_state" in req_json and req_json["sub_state"] == "beep_start":
            ncco = [action_when_beep]
            print(f'status received --> {req_json["status"]}:{req_json["sub_state"]}')
            print(f'response to send --> {ncco}')
        elif req_json["status"] == "human":
            ncco = [action_when_human]
            print(f'status received --> {req_json["status"]}')
            print(f'response to send --> {ncco}')
    else:
        print(f'event received --> {request.data}')
    return (ncco if ncco != "" else "", 200)

Dans le code, remplacez YOUR_VIRTUAL_NUMBER par un numéro virtuel obtenu précédemment et CALL_CAMPAIGNER_PHONE_NUMBER par un numéro auquel vous souhaitez être connecté lorsqu'une personne décroche.

Testons le code en passant un appel à l'aide de la commande curl :

curl --location 'https://api-us.vonage.com/v1/calls' \
--header 'Authorization: Bearer <YOUR_JWT>' \
--header 'Content-Type: application/json' \
--data '{
    "to": [ { "type": "phone", "number": "<YOUR_MOBILE_NUMBER>" } ],
    "from": { "type": "phone", "number": "<YOUR_VIRTUAL_NUMBER>" },
    "advanced_machine_detection": { "behavior": "continue", "beep_timeout": "45" },
    "event_url": ["YOUR_CALLBACK_UR"], 
    "ncco": [
        { "action": "talk",
        "text": "Please wait while we connect you to an agent." }
    ]
}'

6. Conclusion

En suivant les étapes de ce tutoriel, vous avez réussi à créer une capacité d'appel vocal améliorée permettant de détecter si un humain, une boîte vocale ou un répondeur décroche l'appel à l'aide d'un signal sonore. En même temps, vous avez utilisé l'application Flask pour décider du déroulement des actions dans l'appel de manière dynamique. En utilisant ces simples extraits de code, vous pouvez rapidement mener des campagnes d'appels, effectuer des appels en masse et envoyer des messages vocaux correctement sans interaction humaine. Encore une fois, le code source de cette application se trouve sur Github.

D'autres concepts et documents relatifs à l'API de détection des machines sont disponibles à l'adresse suivante Détection avancée des machines.

Vous avez des questions ou des commentaires sur ce tutoriel ? Faites-nous part de vos réflexions sur sur Twitter ou sur notre canal Slack de la communauté Vonage en citant cet article pour une réponse rapide. Vous pouvez également vous connecter avec moi sur Twitter. Bonne chance et bon codage !