Reproducir una transmisión de audio durante una llamada telefónica con Python y Vonage

Hay muchas razones por las que podrías querer reproducir una transmisión de audio durante una llamada. Un caso de uso habitual es cuando los desarrolladores quieren poner a la persona que llama en espera para que se relaje, y se puede reproducir música que le ayude a reducir sus niveles de estrés.

Algunos ejemplos son

• Reproducción de música de espera para las personas que llaman

• Conferencia telefónica: Pon música en la conferencia telefónica hasta que se alcance el quórum.

• Mensaje pregrabado: resulta útil cuando Vonage no admite tu idioma en su motor de conversión de texto a voz

• Buzón de voz: cuando llamas y dejas un mensaje, este se puede reproducir en una llamada posterior.

A continuación verás cómo implementar los escenarios 1 y 2. Los demás escenarios se tratan en otras entradas del blog.

También hay dos métodos para reproducir un flujo de audio en una llamada:

1. Utilización de un objeto de control de llamada (OCN)

2. Uso de la Voice API

Utilizará el método 1 para el escenario 1 y el método 2 para el escenario 2.

Cómo transmitir audio en una llamada con Vonage

Los Objetos de Control de Llamada (NCCOs) proporcionan una manera conveniente de controlar una llamada entrante. Los NCCOs consisten en alguna configuración JSON que describe cómo manejar la Llamada. Existe una detallada guía de referencia sobre NCCOs donde se describen las muchas acciones que se pueden llevar a cabo. Sólo hay una acción que nos interesa en nuestros escenarios, stream. En realidad hay dos formas de utilizar la stream acción: sincrónica y asincrónica. Asíncrono significa que la persona que llama puede interrumpir el audio stream utilizando el teclado del teléfono. Hay algunas opciones de acción de transmisión que son de interés:

Consulta la documentación para obtener más información sobre las opciones de Stream.

A continuación se muestra un fragmento de código de ejemplo para reproducir audio durante una llamada utilizando el SDK de Python de Vonage mediante la definición de un answer webhook:

@app.route("/webhooks/answer", methods=["POST"])
def answer_call():
    """
    Answer a call to your Vonage virtual number by playing music
    """
    ncco: list[NccoAction] = [
        Stream(streamUrl=[STREAM_URL]),
    ]

    return [action.model_dump(by_alias=True, exclude_none=True) for action in ncco]

Los formatos de archivo de audio compatibles son MP3 y WAV de 16 bits.

Ya hemos desarrollado una aplicación básica de Vonage para recibir una llamada y reproducir música durante la misma, utilizando dos escenarios. Con la aplicación básica, debes añadir tus credenciales al .env archivo e implementar la aplicación mediante GitHub Codespaces. Un Codespace es un entorno de desarrollo alojado en la nube de GitHub. GitHub Codespaces se pueden personalizar para cada proyecto, y los usuarios pueden configurar el sistema operativo basado en Linux que desean utilizar, reenviar los puertos más habituales, establecer variables de entorno, etc. También puedes editar la aplicación de partida y experimentar con ella.

Requisitos previos

• A Cuenta API de Vonage

• Python 3.x

• Frasco

• ngrok o GitHub Codespaces

• A Número virtual de Vonage

Regístrate para obtener un Account de la API de Vonage

Crear una nueva aplicación de Vonage

Configuración de tu entorno

Bifurcar este repositorio. Ábrelo en Codespaces haciendo clic en «Crear codespace en main». También puedes implementar la aplicación con Python y ngrok. Las instrucciones para ese método se encuentran en el archivo README.

Cómo obtener y configurar tus claves secretas

Necesitarás tu ID de aplicación de Vonage y tu private.key para que esta aplicación de ejemplo funcione.

1. En el panel de control para desarrolladores de Vonage de tu aplicación, haz clic en el botón «Generar clave pública y privada». Se descargará un archivo. ¡Guarda este archivo en un lugar seguro y mantén su confidencialidad!

2. En tu Codespace, crea un archivo llamado .env y copia y pega en él el contenido de .env.template en él. Sustituye el marcador de posición VONAGE_APPLICATION_ID por tu propio ID de aplicación.

3. En tu Codespace, crea un archivo llamado private.key. Copia y pega el contenido del archivo que has descargado private.key en este archivo y actualiza el valor del marcador de posición de VONAGE_PRIVATE_KEY en tu .env para que apunte a tu archivo de clave privada recién creado.

En la terminal de Codespace, ejecuta los siguientes comandos:

A continuación, ejecuta este comando:

Copia y pega los resultados de estos comandos en la URL de respuesta y URL del evento , de acuerdo con los campos de la configuración de las aplicaciones de Vonage.

Copy the generated URLs and paste them into the Answer URL and Event URL fields in your Vonage Application settings.Transmite audio a tu llamada mediante un NCCO

En este escenario, los usuarios llamarán a un número de Vonage y se reproducirá música en la llamada mediante un NCCO con una stream acción. Utilizaremos el siguiente scenario-1.py archivo:

from dotenv import load_dotenv
from flask import Flask, request, jsonify
from vonage_voice import NccoAction, Stream

from os import environ as env

# Load environment variables from a .env file:
load_dotenv(".env")

# Load in configuration from environment variables:
STREAM_URL = env["STREAM_URL"]


app = Flask(__name__)


@app.route("/webhooks/answer", methods=["POST"])
def answer_call():
    """
    Answer a call to your Vonage virtual number by playing music
    """
    ncco: list[NccoAction] = [
        Stream(streamUrl=[STREAM_URL]),
    ]

    return [action.model_dump(by_alias=True, exclude_none=True) for action in ncco]


@app.route("/webhooks/event", methods=["POST"])
def events():
    return "200"


if __name__ == "__main__":
    app.run(host="localhost", port=9000)

Pruébelo

Puedes ejecutar tu código en Codespaces siguiendo estos pasos.

Instale las dependencias:

Inicia tu aplicación con el siguiente comando:

En el terminal, abra la pestaña Port pestaña Haga clic en Private en la columna Visibility y cámbialo por Public.

Change the port visibility to Public so Vonage can reach your local webhook.La secuencia de acontecimientos en este escenario es la siguiente:

1. Marca tu número de Vonage

2. Vonage recibe la llamada

3. Se genera una llamada de retorno en la answer URL del webhook que hayas especificado

4. Tu aplicación recibe la llamada de retorno y responde con un NCCO

5. Se reproduce música durante la llamada

Transmite audio a tu llamada mediante la Voice API

En este caso, llamas a tu número de Vonage y te incorporan a una conferencia (en nuestro caso, la «Soothing Conference»). A continuación, puedes acceder a la /stream URL para iniciar la transmisión en la conferencia. A continuación, la música se reproduce en la conferencia mediante la Voice API.

Pruébelo

Puedes ejecutar tu código en Codespaces siguiendo estos pasos.

Instale las dependencias:

Inicia tu aplicación con el siguiente comando:

En el terminal, abra la pestaña Port pestaña Haga clic en Private en la columna Visibility y cámbialo por Public.

Change the port visibility to Public so Vonage can reach your local webhook.¡Ya estás listo para reproducir audio en streaming!

Haz estas cosas extra:

1. Marca tu número de Vonage

2. Ejecuta el siguiente comando en la nueva ventana de terminal echo "https://${CODESPACE_NAME}-9000.preview.app.github.dev/stream" y, a continuación, accede al enlace (si lo ejecutas en un equipo local, localhost:9000/stream), y la música se reproducirá en tu conferencia

Se producirán las siguientes acciones:

1. Vonage recibe la llamada

2. La llamada de retorno se genera en la answer URL del webhook que hayas especificado

3. Tu aplicación recibe la llamada de retorno y responde con un NCCO

4. Los participantes se unieron a una conferencia

5. Música para su conferencia

Recapitulación

¡Enhorabuena! Puedes utilizar el flujo de trabajo y los ejemplos de código preparados para transmitir audio relacionado durante una llamada y reproducir música relacionada cuando los usuarios estén en espera.

Otras lecturas y recursos

• Gestionar una llamada entrante con Python y Vonage

• Transmisión de llamadas a un navegador mediante Voice WebSockets

• Cómo enviar mensajes SMS con Python, Flask y Vonage