Comment lire de l'audio dans un appel avec ASP.NET Core MVC

Lorsque vous créez des applications à commande vocale, c'est-à-dire capables de passer et de recevoir des appels téléphoniques, la chose la plus fondamentale que vous devez être en mesure de faire est de diffuser de l'audio dans l'appel de manière programmatique.

C'est la base des SVI, un système d'alerte indiquant que vous allez être connecté à un appel, une invitation à faire quelque chose, ou même simplement un message d'attente. Sans la possibilité de diffuser de l'audio dans un appel, il existe peu de cas d'utilisation pour les applications vocales au-delà de la procuration vocale.

Dans ce tutoriel, nous allons explorer comment commencer à jouer de l'audio dans les appels avec Voice API de Vonage de Vonage et ASP.NET Core MVC.

Aller directement au code

Si vous voulez sauter ce tutoriel et passer directement au code, il est disponible sur GitHub.

Conditions préalables

• Nous allons avoir besoin de la dernière version du SDK .NET Core, j'utilise la version 3.1.

• Nous allons utiliser Visual Studio Code pour ce tutoriel. Bien entendu, cela fonctionnera également avec Visual Studio et Visual Studio pour Mac. Les étapes de l'installation et de l'exécution peuvent être légèrement différentes.

• Nous testerons ceci avec ngrok - alors allez-y et suivez leurs instructions pour l'installer.

• Nous allons avoir besoin de npm pour récupérer le fichier vonage-cli

  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.

Aperçu du sujet

Il existe deux méthodes pour diffuser de l'audio dans un appel.

1. Lorsque notre application est appelée, elle renvoie un fichier NCCO (Nexmo Call Control Object) indiquant à Vonage ce qu'il faut jouer dans l'appel.

2. Nous utiliserons l'API Voice de Vonage (VAPI) pour passer un appel et diffuser de l'audio dans l'appel que nous créons.

Dans les deux cas, nous allons utiliser la fonctionnalité de streaming audio. Cela nous permet de diffuser un fichier audio lors d'un appel. Cependant, je m'en voudrais de ne pas souligner qu'en plus de la lecture de fichiers audio dans les appels, il existe de nombreuses possibilités de personnaliser ce qui est joué dans une requête, que ce soit en utilisant la fonction Text-To-Speech(TTS) ou en utilisant des websockets pour diffuser des flux audio dynamiques dans un appel.

Configuration de l'interface de programmation Nexmo

Avec npm installé, nous pouvons aller de l'avant et installer et configurer le CLI Nexmo en utilisant :

Le CLI Nexmo est ainsi configuré et prêt à fonctionner.

Run Ngrok

Je vais jeter tout ce que j'ai sur... localhost:5000. Exécutez ngrok pour accéder publiquement à localhost:5000.

Prenez note de l'URL sur laquelle ngrok tourne. Dans mon cas, il tourne sur http://7ca005ad1287.ngrok.io. Ce sera l'URL de base pour mes webhooks à l'avenir.

Créer notre application Vonage

Une Application Vonage est une construction qui nous permet de relier facilement l'itinéraire de nos Numbers et de nos webhooks. Vous pouvez créer une application dans le tableau de bord de Vonageou vous pouvez simplement la créer maintenant avec le CLI.

Ceci va créer une Application Vonage. Elle va ensuite lier tous les appels entrants vers cette application à l'URL de réponse : http://7ca005ad1287.ngrok.io/webhooks/answer. Tous les événements d'appel qui se produisent sur cette application vont être acheminés vers http://7ca005ad1287.ngrok.io/webhooks/events. Cette commande va imprimer deux choses.

1. Votre numéro d'application - vous pouvez voir ce numéro d'application dans le tableau de bord Vonage

2. La clé privée de votre application. Assurez-vous de prendre ceci et de l'enregistrer dans un fichier - j'appelle le mien private.key.

Associez votre numéro Vonage à votre Applications

Lorsque vous créez votre Account, un numéro Vonage vous est attribué. Vous pouvez le voir dans la section dans la section Numbers du tableau de bord. Vous pouvez également exécuter la commande nexmo number:list dans votre console pour obtenir la liste de vos Numbers. Prenez votre numéro Vonage et votre numéro d'identification d'application et exécutez la commande suivante :

Une fois cette étape franchie, vos appels seront bien dirigés vers votre URL.

Créer un projet

Dans votre console, naviguez vers votre répertoire de code source et exécutez la commande suivante :

Cela créera un répertoire et un projet appelés PlayAudioMvcExécutez la commande cd pour changer votre répertoire en PlayAudioMvcet exécutez la commande suivante pour installer la bibliothèque Vonage.

Exécuter code . pour ouvrir Visual Studio Code.

Modifier le contrôleur

Ajouter des déclarations d'utilisation

Nous allons nous appuyer sur le fichier HomeController.cs ouvrez Controllers\HomeController.cs et ajouter les instructions d'utilisation suivantes au début :

using Microsoft.Extensions.Configuration;
using Vonage.Voice.Nccos.Endpoints;
using Vonage.Voice.Nccos;
using Vonage.Voice;
using Vonage.Request;

Configuration de l'injection

Nous allons tirer parti de l'injection de dépendances pour obtenir certains des éléments configurables de notre application, à savoir l'appId et la clé privée. Pour cela, ajoutez un champ IConfiguration au champ HomeControllerpuis ajoutez un IConfigurationParameter au constructeur et assigner ce champ IConfiguration au paramètre. Votre constructeur devrait maintenant ressembler à ceci. Pendant que nous y sommes, ajoutons également une constante à cette classe pour pointer vers un fichier audio sur le web, il y en a un que Vonage fournit pour les cas de test et que nous allons lier :

const string STREAM_URL = "https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3";

private readonly IConfiguration _config;

public HomeController(ILogger<HomeController> logger, IConfiguration config)
{
    _config = config;
    _logger = logger;
}

Ajouter un point de terminaison de réponse

Nous allons traiter le cas 1 : lorsque nous recevons un appel d'un utilisateur et que nous voulons jouer un fichier audio dans cet appel. Nous allons devoir ajouter une action à notre contrôleur qui retournera une chaîne JSON. Ajoutez ce qui suit à notre HomeController classe :

[HttpGet("/webhooks/answer")]
public string Answer()
{
    var streamAction = new StreamAction{
        StreamUrl = new string[]
        {
            STREAM_URL
        }
    };
    var ncco = new Ncco(streamAction);
    return ncco.ToString();
}

Lorsque quelqu'un compose un numéro, Vonage va effectuer une demande d'accès à cette URL. Cette méthode s'appuie sur notre constructeur NCCO pour créer un NCCO ; nous convertissons ensuite le NCCO en chaîne et le renvoyons. Cela renverra une chaîne JSON qui ressemblera à ceci :

[{"streamUrl":["https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3"],"action":"stream"}]

Ajouter une sortie d'appel

L'action suivante que nous allons devoir ajouter est une action de numérotation. C'est un peu plus compliqué. Il va falloir récupérer notre appId et notre clé dans la configuration. Elle a également besoin d'un numéro à appeler et d'un numéro à partir duquel appeler, votre numéro Voice, puis elle construira un client vocal, créera une structure de demande et passera l'appel :

[HttpPost]
public IActionResult MakePhoneCall(string toNumber, string fromNumber)
{
    var appId = _config["APPLICATION_ID"];
    var privateKeyPath = _config["PRIVATE_KEY_PATH"];

    var streamAction = new StreamAction{ StreamUrl = new string[] { STREAM_URL }};
    var ncco = new Ncco(streamAction);

    var toEndpoint = new PhoneEndpoint{Number=toNumber};
    var fromEndpoint = new PhoneEndpoint{Number=fromNumber};

    var credentials = Credentials.FromAppIdAndPrivateKeyPath(appId, privateKeyPath);
    var client = new VoiceClient(credentials);
    var callRequest = new CallCommand { To = new []{toEndpoint}, From = fromEndpoint, Ncco= ncco};
    var call = client.CreateCall(callRequest);
    ViewBag.Uuid = call.Uuid;
    return View("Index");
}

Ajouter un Frontend

Dans le même ordre d'idées que pour le Home Controller, nous allons également nous appuyer sur notre Home View. Ouvrez Views\Home\Index.cshtmlet supprimez la div de base qui s'y trouve. Nous allons ajouter un formulaire de base qui sera envoyé à notre action MakePhoneCall et lorsque l'action se terminera, nous afficherons l'UUID de l'appel téléphonique. En gardant cela à l'esprit, ajoutons ce qui suit à notre fichier :

@using (Html.BeginForm("MakePhoneCall", "home", FormMethod.Post))
{
    <div class="form-vertical">
        <h4>Call<h4>
                @Html.ValidationSummary(true, "", new { @class = "text-danger" })
                <div class="form-group">
                    @Html.Label("To")
                    <div>
                        @Html.Editor("toNumber", new { htmlAttributes = new { @class = "form-control" } })
                    </div>
                </div>

                <div class="form-group">
                    @Html.Label("From")
                    <div>
                        @Html.Editor("fromNumber", new { htmlAttributes = new { @class = "form-control" } })
                    </div>
                </div>
                <div class="form-group">
                    <div class="col-md-offset-2 col-md-10">
                        <button type="submit">Send</button>
                    </div>
                </div>
    </div>
}
@if(@ViewBag.Uuid != null){
    <h2>Call UUID: @ViewBag.Uuid</h2>
}

Configurer votre application

Ajouter des variables de configuration

Rappelez-vous que nous utilisons l'élément IConfiguration pour obtenir notre appId et notre chemin d'accès à la clé privée. En gardant cela à l'esprit, ouvrons appsettings.json et ajoutons les clés suivantes :

"APPLICATION_ID":"APPLICATION_ID",
"PRIVATE_KEY_PATH":"C:\\path\\to\\your\\private.key"

Configurer Kestrel ou IIS Express

Comme j'utilise VS Code, mon application va naturellement utiliser kestrel. Que vous utilisiez kestrel ou IIS Express, allez dans properties\launchSettings.json et dans le menu PlayAudioMvc->applicationUrl déposer le https://localhost:5001 puisque nous n'utilisons pas SSL avec ngrok, et que nous pointons vers le port 5000. Si vous utilisez IIS Express, dans iisSettings->iisExpress, définissez le applicationUrl à http://localhost:5000 et le sslPort à 0.

Tester votre application

Une fois cela fait, tout ce que vous avez à faire est de lancer la commande dotnet run et votre application démarrera et sera hébergée sur le port 5000. Il ne vous reste plus qu'à appeler votre application - vous pouvez l'appeler sur votre numéro Vonage et passer un appel depuis votre application. Vous pouvez passer l'appel en naviguant vers localhost:5000 et en remplissant et soumettant le formulaire.

Ressources

• Vous pouvez en savoir plus sur la Voice API en consultant notre site web de documentation

• Vous pouvez en apprendre beaucoup sur le fonctionnement des API vocales, en particulier le NCCOS, en consultant notre référence NCCO

• Tout le code de ce tutoriel est disponible sur GitHub