Recibir una llamada telefónica con Voice API y Swift

En este tutorial crearás una aplicación Swift que puede recibir llamadas telefónicas utilizando la tecnología Vapor y la Nexmo Voice API. Puedes seguir este tutorial tanto en MacOS como en Ubuntu.

Para obtener la solución completa, consulte este repositorio de Github.

Requisitos previos

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.

• El sitio Nexmo CLI - que va a utilizar para crear una aplicación, comprar un número y vincular los dos juntos

• Swift 4.1 o superior - en MacOS, Xcode 9.3 o superior será suficiente

El Plan

Este tutorial le guiará a través de los siguientes pasos:

• Conozca los conceptos de Nexmo

• Crear un nuevo proyecto Vapor

• Añadir una ruta para la respuesta de voz

• Exponer la aplicación mediante ngrok

• Comprar un número Nexmo

• Crear una aplicación Nexmo para utilizar con el número

• Pruebe su aplicación

Conceptos Nexmo

Antes de entrar en la construcción, hay un par de conceptos que debes entender.

A aplicación Nexmo le permite utilizar fácilmente los productos Nexmo, en este caso la Voice API para crear aplicaciones de voz en la nube.

Una aplicación Nexmo requiere dos URL como parámetros:

• answer_url - Nexmo realizará una solicitud a esta URL en cuanto se responda a la llamada

• event_url - Nexmo envía información de eventos de forma asíncrona a esta URL cuando cambia el estado de la llamada; esto define en última instancia el flujo de la llamada

Ambas URLs necesitan devolver JSON y seguir el Objeto de Control de Llamada Nexmo (NCCO) de Nexmo. En el siguiente ejemplo, definirás un NCCO que lea un texto predefinido para una llamada entrante, utilizando la función de Texto a voz texto a voz.

A número virtual Nexmo se asociará a la aplicación y servirá como "punto de entrada" a la misma: es el número al que llamarás para probar la aplicación.

Para obtener más información sobre la aplicación Nexmo, visite el sitio web de Nexmo Referencia API.

Nuevo proyecto Vapor

Utilizarás Vapor para crear una sencilla aplicación web Swift. Si aún no tienes Vapor instalado, ejecuta este comando:

Existen instrucciones detalladas de instalación para MacOS y Ubuntu.

Desde la línea de comandos, navega a una ubicación apropiada donde quieras que resida tu proyecto (por ejemplo, tu directorio de Documentos) y crea una nueva aplicación Vapor:

Si utiliza MacOS puede hacer que vapor cree automáticamente un proyecto XCode (la opción -y abrirá automáticamente el proyecto Xcode):

Build & Run para probar su aplicación asegurándose de que el Run esté seleccionado. Una vez compilado todo, se inicia el servidor y verás un aviso en la consola:

Server starting on http://localhost:8080

Dirija su navegador a esa URL y debería aparecer un It works! debería aparecer.

Añadir la ruta

Ahora añadirás una ruta que servirá de answer_url para la aplicación aplicación Nexmo. http://localhost:8080/webhooks/answer responderá con el siguiente objeto JSON:

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

Un proyecto Vapor almacena sus rutas en el archivo routes.swift dentro del Sources/App grupo. Abra este archivo, borre todas las rutas existentes y defina la nueva ruta:

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 es una simple Estructura Swift para contener los detalles de la acción NCCO - defínela después del cierre del enrutador:

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

Mediante la codificación Action para que se ajuste a Encodablese garantiza que el JSONEncoder pueda utilizarlo.

Cree y ejecute la aplicación y pruebe la salida de la nueva ruta en: http://localhost:8080/webhooks/answer.

Ahora tiene una URL que se utilizará como el archivo answer_url.

Exponga su aplicación

Para que Nexmo llegue a su aplicación Vapor, necesita acceder a una URL disponible públicamente; su aplicación se ejecuta en su máquina y sólo es accesible dentro de su red local.

ngrok es una sencilla utilidad que expone su servidor web local a través de URL públicas.

Con ngrok instaladoejecute el siguiente comando:

Tome nota de la dirección de reenvío, ya que la necesitará cuando configure su Account - a continuación se muestra un ejemplo - la dirección de reenvío es https://7ffc0230.ngrok.io.

Comprar un Numbers

Este será el número al que llamará para conectarse a su aplicación Nexmo. El siguiente ejemplo utiliza un número de EE.UU., pero los números de otros países están disponibles.

Nota: Cuando te registres en una Account Nexmo, se añadirán 2,00 euros a tu saldo y esto será más que suficiente para obtener un número.

Para adquirir un nuevo número, utilice la CLI de Nexmo:

Anote el nuevo número que se le asignó en la compra; lo necesitará a continuación.

Crear una aplicación Nexmo

Ahora lo unirá todo creando una nueva aplicación Nexmo utilizando la dirección de reenvío ngrok:

Nota: El segundo parámetro de URL, http://your-ngrok-forwarding-address/webhooks/events, no existe y nunca lo utilizarás, pero es necesario especificar una URL de evento al crear una aplicación Nexmo.

La salida dada por el comando anterior incluirá el id de la nueva aplicación (ej: Application created: 39083ced-5275-423d-8a1f-9db528c106b1). Necesitará este identificador de aplicación para vincular su número de teléfono a la aplicación; puede utilizar la CLI de Nexmo para hacerlo:

La aplicación enviará ahora una solicitud a su http://your-ngrok-forwarding-address/webhooks/answer cuando reciba una llamada telefónica.

Pruebe su aplicación

Desde tu teléfono, haz una llamada a tu número Nexmo para escuchar la pregunta más importante de todas.

Conclusión

En unas pocas líneas de código has creado una aplicación que puede recibir una llamada telefónica y decir un mensaje a la persona que llama. Existen otras formas de interactuar con la persona que llama y otras lenguaje de marcado de síntesis de voz (SSML) que puede utilizar.

¿Y ahora qué?

¿Quiere saber más? Consulte nuestra documentación en Desarrollador Nexmo donde puedes aprender sobre el flujo de llamadas, Voice API y Objetos de control de llamadas Nexmo.