Desviar una llamada telefónica a través de un proxy de voz con Python y Starlette

Hay algunas situaciones en las que podemos necesitar que un desconocido nos llame, o que nosotros le llamemos a él. Un repartidor puede tener que llamarte para preguntarte por tu paquete, o tú puedes necesitar llamar al taxista porque te has olvidado el paraguas. En estas situaciones, es conveniente poder llamar y hablar con la persona real y no con un centro de llamadas. Sin embargo, ninguna persona quiere que un desconocido tenga su número privado.

El desvío de llamadas permite que las personas se llamen entre sí sin que ninguna de ellas conozca el número de teléfono de la otra. Este tipo de desvío de llamadas se conoce como "proxy de voz".

Antes de empezar

Hay algunas cosas que necesitas antes de empezar:

1. Python 3.6+. Este ejemplo utiliza el programa asíncrono Starlette por lo que una versión reciente de Python es imprescindible.

2. Si está ejecutando el ejemplo en su entorno de desarrollo local, necesita una forma de exponerlo a Internet, como por ejemplo utilizando ngrok.

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.

Descargar el código

Todo el código de este ejemplo está disponible en la organización de la Comunidad Nexmo en Github. Clona el repositorio ahora:

git clone git@github.com:nexmo-community/nexmo-python-voiceproxy.git
cd nexmo-python-voiceproxy

Una vez que hayas clonado el repositorio, debes instalar sus dependencias. Te recomiendo que lo hagas siempre en un nuevo entorno virtual.

python -m venv nexmo-voiceproxy
source nexmo-voiceproxy/bin/activate
pip install -r requirements.txt

Creación de un servidor Starlette

Proporcionamos instrucciones a la Voice API de Nexmo utilizando un Objeto de Control de Llamada Nexmo (NCCO). El NCCO es un archivo JSON que contiene una lista de acciones que Nexmo debe realizar cada vez que un usuario llama a un Número Virtual Nexmo. En este ejemplo, el NCCO tiene una sola acción, connect. La acción connect nos permite conectar la llamada a diferentes puntos finales. Un endpoint puede ser otro número, un WebSocket o un endpoint SIP. En este ejemplo, se utiliza el tipo number tipo. Desviar una llamada a un número diferente de esta manera no es visible para el usuario.

async def get(self, request):
    return JSONResponse(
        [
            {
                "action": "connect",
                "from": os.getenv("NEXMO_NUMBER_FROM"),
                "endpoint": [
                    {"type": "phone", "number": os.getenv("NEXMO_NUMBER_TO")}
                ],
            }
        ]
    )

El código anterior tiene dos variables de entorno que debe suministrar. NEXMO_NUMBER_FROM, este es el número de teléfono al que el usuario llama para iniciar el proxy, también es el número que el otro usuario ve como el llamante. Este número debe ser un Número Virtual Nexmo; explicaré cómo puedes alquilar un Número Virtual y enlazarlo a tu aplicación más adelante en el artículo.

NEXMO_NUMBER_TO es el número de teléfono del usuario que recibe la llamada proxy. Este número puede ser cualquier número de teléfono con formato E.164.

Eventos de Voice API

Puede realizar un seguimiento del estado de su llamada proxy utilizando el webhook de eventos. Cada vez que se produce un cambio en el estado de la llamada, Nexmo se lo notifica a través de un webhook. La información suministrada al webhook difiere dependiendo del estado actual, puedes encontrar una lista completa en la Documentación de Voice API.

En este ejemplo, la información se registra en el terminal para que pueda ver cómo se producen los eventos en tiempo real. Vale la pena señalar que siempre debe devolver un 200 OK respuesta HTTP a todos los webhooks de Nexmo. Si no devuelve una respuesta 200 OK la API de Nexmo asume que se ha producido un error y, tras un breve retardo, reintenta el endpoint. Para evitar múltiples solicitudes y datos duplicados, asegúrate de devolver siempre una respuesta . 200 OK.

async def post(self, request):
    event = await request.json()
    log.msg("Voice Proxy", **event)
    return PlainTextResponse()

Por defecto, la API Nexmo solicita el archivo NCCO a través de GET y notifica el evento al webhook mediante una petición POST con un cuerpo JSON. Usted puede cambiar esto en la configuración de su aplicación, pero el código de este tutorial asume que GET solicitudes son para el NCCO, y POST son notificaciones de eventos.

Vinculación de un número virtual a una aplicación de voz

La API Nexmo necesita poder acceder a tu servidor Starlette. Si estás ejecutando este ejemplo localmente, necesitas exponer tu servidor a la Internet pública. Para obtener más información sobre cómo crear un túnel a localhost leer nuestro entrada de blog sobre ngrok.

Asegúrese de que su servidor está funcionando python server.py y luego abra un nuevo terminal para ngrok:

ngrok http 8000

Ahora que su servidor proxy está funcionando y es accesible por la API de Nexmo, puede alquilar un Nexmo Virtual Number y crear una nueva Voice Application utilizando el Panel de Nexmoo a través de la CLI de Vonage. Puedes encontrar más información sobre cómo instalar la CLI de Vonage aquí.

Para hacer esto a través de la CLI es necesario ejecutar varios comandos:

vonage numbers:search [COUNTRYCODE]
vonage numbers:buy [NUMBER] [COUNTRYCODE]
vonage apps:create
vonage apps:link [APPLICATION_ID] --number=number

Los comandos anteriores realizan lo siguiente:

• Buscar un número disponible con COUNTRYCODE. Pass in GB para los números virtuales británicos y US para los de Estados Unidos.

• Una vez que haya encontrado un número adecuado, cómprelo utilizando vonage numbers:buy [NUMBER] [COUNTRYCODE]

• Al crear una nueva Voice Application ejecute vonage apps:create y siga las instrucciones. Debe proporcionar un nombre para la aplicación, la URL de su archivo NCCO, la URL de su webhook de eventos y una ubicación para guardar su clave privada. La clave privada se utiliza para autenticarse con la Voice API de Nexmo al realizar llamadas salientes. Como este ejemplo sólo maneja llamadas entrantes, no necesitas esta clave privada esta vez.

• Por último, vincule el número virtual a su nueva aplicación. Se pueden asociar varios números a una misma aplicación, por ejemplo, si desea tener diferentes números locales para usuarios de distintos países.

Puesta en común

Una vez que tengas un Número Virtual asociado a tu Aplicación de Voz y tengas tu servidor proxy funcionando y expuesto a la Internet pública, estarás listo para hacer tu primera llamada por proxy.

Si utiliza un segundo dispositivo para llamar al Número Virtual Nexmo asociado a su solicitud, podrá ver la solicitud de la OCN en el terminal Starlette.

Cuando la llamada se desvíe y su otro teléfono empiece a sonar, compruebe el número que aparece para la persona que llama. El número mostrado no es el número de teléfono del teléfono que inició la llamada, es el número virtual Nexmo que especificó como su NEXMO_NUMBER_FROM número. Con una docena de líneas de código, ¡has creado un proxy de voz anónimo!

Lecturas complementarias

El desvío de llamadas es sólo una de las muchas cosas que puedes hacer con la Voice API de Nexmo. Usted debe tratar de conectar la llamada a un WebSocket, o modificar el webhook de eventos para realizar un seguimiento de las estadísticas sobre sus llamadas. Incluso podría hacer análisis del sentimiento de la llamada en tiempo real.

Ponte en contacto

Si tienes alguna pregunta o comentario sobre este post, o si quieres ser el primero en enterarte cuando escribamos algo nuevo o encontremos alguna tecnología interesante, síguenos en Twitter: @NexmoDev