Recevoir un appel téléphonique avec Voice API et Swift

Dans ce tutoriel, vous allez créer une application Swift qui peut recevoir des appels téléphoniques en utilisant la fonction Vapor et l'API Nexmo Voice API. Vous pouvez suivre ce tutoriel sur MacOS ou Ubuntu.

Pour la solution complète, veuillez consulter ce Github repo.

Conditions préalables

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.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Ready to start building?

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

• La CLI Nexmo - vous l'utiliserez pour créer une application, acheter un numéro et relier les deux.

• Swift 4.1 ou supérieur - sur MacOS, Xcode 9.3 ou supérieur fera l'affaire.

Le plan

Ce tutoriel vous guidera à travers les étapes suivantes :

• En savoir plus sur les concepts Nexmo

• Créer un nouveau projet Vapor

• Ajouter une route pour la réponse vocale

• Exposer l'application à l'aide de ngrok

• Acheter un numéro Nexmo

• Créer une application Nexmo à utiliser avec le numéro

• Testez votre application

Concepts Nexmo

Avant de vous lancer dans la construction, voici quelques concepts qu'il vous faudra comprendre.

A application Nexmo vous permet d'utiliser facilement les produits Nexmo, en l'occurrence l Voice API pour créer des applications vocales dans le Cloud.

Une application Nexmo requiert deux URL comme paramètres :

• answer_url - Nexmo enverra une requête à cette URL dès que l'appel sera pris.

• event_url - Nexmo envoie des informations sur les événements de manière asynchrone à cette URL lorsque l'état de l'appel change ; cela définit en fin de compte le flux de l'appel.

Les deux URL doivent renvoyer du JSON et suivre la norme Nexmo Call Control Object (NCCO) de Nexmo. Dans l'exemple ci-dessous, vous allez définir un NCCO qui lit un texte prédéfini pour un appel entrant, en utilisant la fonction Synthèse vocale à l'aide du moteur de synthèse vocale.

A numéro virtuel Nexmo sera associé à l'application et servira de "point d'entrée" à celle-ci - c'est le numéro que vous appellerez pour tester l'application.

Pour plus d'informations sur l'application Nexmo, veuillez consulter la page Nexmo Référence API.

Nouveau projet Vapor

Vous allez utiliser Vapor pour créer une simple application web Swift. Si vous n'avez pas encore installé Vapor, faites-le en lançant cette commande :

Des instructions d'installation détaillées sont disponibles pour MacOS et Ubuntu.

À partir de la ligne de commande, naviguez jusqu'à l'emplacement approprié où vous souhaitez que votre projet réside (par exemple, votre répertoire Documents) et créez une nouvelle application Vapor :

Si vous utilisez MacOS, vous pouvez demander à vapor de créer automatiquement un projet XCode pour vous (l'option -y ouvrira automatiquement le projet Xcode) :

Build & Run pour tester votre application en vous assurant que le schéma Run soit sélectionné. Une fois que tout est compilé, le serveur est démarré et vous verrez une notification dans la console :

Server starting on http://localhost:8080

Pointez votre navigateur sur cette URL et un message It works! devrait apparaître.

Ajouter l'itinéraire

Vous allez maintenant ajouter une route qui servira de answer_url pour l'application l'application Nexmo. http://localhost:8080/webhooks/answer répondra avec l'objet JSON suivant :

[
    {
        "action":"talk",
        "text":"<speak>To be <break strength='weak' \/> or not to be <break strength='weak' \/> that is the question.<\/speak>"
    }
]

Un projet Vapor stocke ses itinéraires dans le fichier routes.swift à l'intérieur du groupe Sources/App à l'intérieur du groupe. Ouvrez ce fichier, effacez tous les itinéraires existants et définissez le nouvel itinéraire :

import Vapor

public func routes(_ router: Router) throws {
    router.get("/webhooks/answer") { request -> String in
        let talk = Action(
            action: "talk",
            text: "<speak>To be <break strength='weak' /> or not to be <break strength='weak' /> that is the question.</speak>")
        let encoder = JSONEncoder()
        guard let data = try? encoder.encode([talk]) else { return "error encoding" }
        return String(data: data, encoding: .utf8) ?? "error"
    }
}

Action est une simple Structure Swift pour contenir les détails de l'action NCCO - définissez-la après la fermeture du routeur :

struct Action: Encodable {
    var action: String
    var text: String
}

En codant Action pour qu'il soit conforme à Encodablevous vous assurez que le JSONEncoder peut l'utiliser.

Créez et exécutez l'application et testez la nouvelle sortie d'itinéraire à l'adresse suivante : http://localhost:8080/webhooks/answer.

Vous disposez maintenant d'une URL qui sera utilisée en tant que answer_url.

Exposez votre application

Pour que Nexmo puisse atteindre votre application Vapor, il doit accéder à une URL publique - votre application s'exécute sur votre machine et n'est accessible qu'au sein de votre réseau local.

ngrok est un utilitaire simple qui expose votre serveur web local par le biais d'URL publiques.

Avec ngrok installéexécutez la commande suivante :

Prenez note de l'adresse de réexpédition car vous en aurez besoin lorsque vous configurerez votre Account - un exemple de sortie est montré ci-dessous - l'adresse de réexpédition est la suivante https://7ffc0230.ngrok.io.

Acheter un Numbers

Il s'agit du numéro que vous allez appeler pour vous connecter à votre application Nexmo. L'exemple ci-dessous utilise un numéro américain, mais des numéros pour d'autres pays sont disponibles.

Remarque : lors de l'ouverture d'un compte Nexmo, 2,00 € sont ajoutés à votre solde, ce qui est largement suffisant pour obtenir un numéro.

Pour acheter un nouveau numéro, utilisez l'interface CLI de Numbers :

Notez le nouveau numéro qui vous a été attribué lors de l'achat ; vous en aurez besoin ensuite.

Créer une application Nexmo

Vous allez maintenant relier le tout en créant une nouvelle application Nexmo en utilisant l'adresse de transfert ngrok :

Note : Le deuxième paramètre URL, http://your-ngrok-forwarding-address/webhooks/events, n'existe pas et vous ne l'utiliserez jamais, mais une URL d'événement doit être spécifiée lors de la création d'une application Nexmo.

La sortie donnée par la commande ci-dessus comprendra l'identifiant de la nouvelle application (par exemple : Application created : 39083ced-5275-423d-8a1f-9db528c106b1). Vous aurez besoin de cet identifiant pour relier votre numéro de téléphone à l'application - vous pouvez utiliser l'interface de commande Nexmo pour ce faire :

L'application va maintenant envoyer une demande à votre http://your-ngrok-forwarding-address/webhooks/answer lorsqu'elle reçoit un appel téléphonique.

Testez votre application

Depuis votre téléphone, appelez votre numéro Numbers pour entendre la question la plus importante de toutes.

Conclusion

En quelques lignes de code, vous avez créé une application capable de recevoir un appel téléphonique et d'adresser un message à l'appelant. Il existe d'autres façons d'interagir avec l'appelant et d'autres Speech Synthesis Markup Language (SSML) que vous pouvez utiliser.

Quelle est la prochaine étape ?

Vous voulez en savoir plus ? Consultez notre documentation sur Nexmo Developer où vous trouverez des informations sur le flux d'appels, Voice API et les objets de contrôle d'appel Nexmo.