Compartir:
){kind=small}
Liz Acosta es promotora de desarrolladores en Vonage. Aunque su trayectoria profesional, de estudiante de cine a comercializadora, de ingeniera a defensora de los desarrolladores, puede parecer poco convencional, ¡es bastante típica de las relaciones con los desarrolladores! A Liz le encanta la pizza, las plantas, los carlinos y Python.
Gestionar una llamada entrante con Python
Tiempo de lectura: 14 minutos
En este tutorial, aprenderá a utilizar Python FastAPI para desarrollar una aplicación de voz que reciba llamadas telefónicas entrantes utilizando la Voice API de Vonage. El software que recibe y enruta llamadas telefónicas ayuda a las empresas a mejorar la experiencia del cliente. Permite un soporte más personalizado y eficiente. Este tutorial te guiará a través de tres escenarios comunes de flujo de llamadas de soporte al cliente:
Al final de este tutorial, comprenderás cómo manejar eficazmente las llamadas entrantes con Vonage utilizando una aplicación FastAPI de Python y ngrok. Esta guía te permitirá ampliar las capacidades de tu aplicación para conectarte con los usuarios en tiempo real, haciendo que tu aplicación sea más interactiva y atractiva. Ya sea que estés construyendo una solución de servicio al cliente o una herramienta de comunicación, dominar estas habilidades mejorará la funcionalidad de tu proyecto y la experiencia del usuario.
Las aplicaciones de voz de Vonage emplean objetos de control de llamadas de Vonage (NCCO) para construir flujos de llamadas con acciones NCCO. En otras palabras, un NCCO es una matriz JSON de acciones que pueden controlar las llamadas entrantes. Un NCCO típico tiene este aspecto:
[
{"action": "talk",
"text": "Hello, one moment please, your call is being forwarded to our agent."},
{"action": "connect",
"from": VONAGE_NUMBER,
"endpoint": [{"type": 'phone',
"number": YOUR_SECOND_NUMBER}]}
]
En este ejemplo concreto, hay dos acciones: talk y connect. Una acción suele ir acompañada de un conjunto de opciones clave-valor configurables:
Para la
talkla opcióntextproporciona el script de texto a voz. Más información en la documentación de la acción NCCO Talk.La acción
connectse configura con dos opciones:fromyendpoint. Consulte la Referencia de la acción NCCO Connect para más detalles sobre la configuración.
En talk y connect se ejecutan de forma sincrónica en el orden en que aparecen en la lista. Algunas acciones pueden configurarse para que sean asíncronas. Esto puede resultar útil cuando se construye un flujo de llamadas en el que la persona que llama puede elegir entre un menú de opciones, como seleccionar un idioma. En un escenario así, no querrás que la persona que llama tenga que esperar a través de todo el menú de idiomas para proceder con la llamada. Esto es algo que querrías hacer de forma asíncrona. Para saber cómo funciona, consulte la guía guía de acciones NCCO asíncronas.
En resumen, las OCN ofrecen los elementos básicos para crear flujos de llamadas sofisticados y adaptados a sus necesidades específicas.
Para completar este tutorial, nos basaremos en conceptos técnicos y herramientas ajenos a Vonage que pueden ser útiles en otras áreas del desarrollo de software.
Un webhook es la forma en que una aplicación basada en web envía datos o notificaciones de eventos a otra aplicación de este tipo, permitiendo la comunicación automática en lugar de que una aplicación tenga que sondear constantemente a la otra en busca de actualizaciones. En general, esto significa interactuar a través de la web mediante una API utilizando una petición HTTP. En este tutorial en particular, utilizaremos un webhook para notificar a su aplicación web que alguien ha llamado a su número virtual y para devolver una NCCO de las acciones del flujo de llamadas.
FastAPI es un framework web de alto rendimiento para crear API de servicios basados en HTTP en Python. Lo que diferencia a FastAPI de otros frameworks web de Python es su estrecha alineación con Pydanticuna biblioteca de validación de datos para Python. Este acoplamiento permite a FastAPI validar, serializar y deserializar datos. Esto proporciona un método más declarativo de especificar la estructura y los tipos de datos para las solicitudes entrantes, como los cuerpos HTTP y las respuestas salientes. FastAPI también genera automáticamente OpenAPI automáticamente. Todas estas características combinadas la hacen especialmente adecuada para las modernas API REST, el desarrollo de microservicios y las aplicaciones que requieren funcionalidad en tiempo real.
En este tutorial, crearemos una aplicación web y la ejecutaremos localmente en tu máquina. Debido a que se ejecutará localmente, no se podrá acceder a ella desde la Internet pública, y si no se puede acceder a tu aplicación web, Vonage no podrá realizar una solicitud al webhook. Aquí es donde entra en juego la tunelización. Tunneling expone los servidores locales a la Internet pública a través de URL públicas temporales o estáticas. ngrok es una plataforma de software que brinda este servicio.
En resumen, crearemos una aplicación web Python FastAPI con un webhook y utilizaremos ngrok para que tu aplicación local sea accesible a través de un túnel a una URL pública para que Vonage pueda realmente publicar en el webhook y manejar una llamada entrante como se define en el código.
En este tutorial, usaremos FastAPI para definir un webhook al que el Voice API pueda hacer una petición cuando alguien llame a tu número virtual. Usaremos ngrok para exponer el webhook al internet público. Y usaremos Vonage para comprar un número virtual así como el Voice API para completar el manejo de llamadas entrantes.
Si lo prefiere, puede extraer el código para manejar una llamada entrante de Vonage Community GitHub.
Para completar este tutorial, necesitarás lo siguiente:
Python 3.8+
Una cuenta cuenta ngrok e instalación
Un número de teléfono adicional para actuar como "agente" con el que conectar
Antes de empezar a construir, pongamos todo en orden.
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.
La Voice API debe poder acceder a tu webhook para poder hacerle peticiones, por lo tanto, la URL del endpoint debe ser accesible a través de la internet pública.
Para ello, en este tutorial utilizaremos ngrok. Echa un vistazo a nuestro tutorial de ngrok para aprender a instalarlo y usarlo.
En una ventana de terminal, cree un directorio para este proyecto y navegue hasta él:
mkdir vonage-inbound-call && cd vonage-inbound-call
Ahora que lo tienes todo preparado, es hora de empezar a construir.
Este tutorial le guiará a través de tres flujos de llamada diferentes:
Antes de pasar a cada escenario, primero crearemos una aplicación de Vonage y prepararemos nuestro entorno para el desarrollo completando lo siguiente:
La Voice API debe poder acceder a tu webhook para poder hacerle peticiones. Para ello, la URL del endpoint debe estar expuesta a la Internet pública. Para eso está ngrok.
En una ventana de terminal separada, ejecute:
ngrok http 3000Este comando generará las URL públicas a las que su servidor local hará túnel en el puerto 3000. Tome nota de la URL pública - debe ser algo como esto:
Forwarding https://0a6ec0a950eb.ngrok-free.app -> http://localhost:3000
Primero tienes que crear una aplicación Voice API. La "aplicación" a la que nos referimos aquí es un contenedor de la información de configuración y seguridad necesaria para la Voice API.. No es lo mismo que la aplicación web FastAPI que también vamos a crear.
Cree su aplicación Voice API en el panel del desarrollador accediendo a la sección Applications en el menú de la izquierda y haciendo clic en el botón "Crear nueva aplicación". Se abrirá el menú de creación de aplicaciones. Asigne a su aplicación el nombre inbound-call.
En el marco de las Capacidades active la opción de Voicey aparecerá una lista de campos de texto. En el campo de texto URL de respuestaproporcione la URL pública ngrok modificada con el webhook que definió en su aplicación FastAPI. Esto se parecerá a: https://96b34a48a639.ngrok-free.app/webhooks/answer.
Haga clic en el botón "Generar nueva solicitud".
A screenshot of the Create an application menu in the Vonage developer dashboard.Ahora que ha creado su solicitud, puede vincular su número a ella pulsando en el botón Vincular en la tabla de números disponibles. Su aplicación está ahora lista para responder a las llamadas entrantes. Los escenarios que codificaremos le dirán a la aplicación qué hacer cuando el /answer webhook es llamado.
Los entornos virtuales de Python te permiten instalar paquetes en una ubicación aislada del resto de tu sistema. Esto ayuda a evitar el desorden en todo el sistema y los conflictos con diferentes versiones y paquetes de Python. Consulta nuestra entrada de blog sobre entornos virtuales para obtener más información.
En el directorio de su proyecto, ejecute los siguientes comandos para crear un entorno virtual y activar un entorno virtual:
python3 -m venv venv && source venv/bin/activateAhora debería ver en su terminal el prefijo (venv). Para desactivar su entorno virtual, ejecute el comando deactivate comando .
Para instalar las dependencias que necesitamos para este tutorial, ejecute lo siguiente:
pip install vonage python-dotenv 'fastapi[standard]'Ahora tenemos todo lo que necesitamos para empezar a codificar.
En este caso concreto, responderemos a una llamada entrante a un número virtual reproduciendo un mensaje de texto a voz.
Cree un archivo llamado scenario-1.py que incluya el siguiente código:
from fastapi import FastAPI, Query
from vonage_voice import Talk
app = FastAPI()
@app.get('/webhooks/answer')
async def answer_call(from_: str = Query(..., alias='from')):
from_ = '-'.join(from_)
return [Talk(text=f'Thank you for calling from {from_}').model_dump(by_alias=True, exclude_none=True)]
Este código crea el /webhooks/answer endpoint. Cuando este punto final recibe una solicitud de la Voice API, crea e itera a través de un archivo NCCO con una Talk acción. Ésta es la responsable de la conversión de texto a voz que escucha la persona que llama cuando marca el número. Para obtener más información sobre cómo responder a las llamadas con texto a voz, echa un vistazo a nuestros ejemplos de código.
Ahora es el momento de probar tu aplicación.
En tu ventana de terminal, ejecuta
fastapi dev --port 3000 scenario-1.pyEsto creará un servidor local con su punto final webhook en el puerto 3000. Su aplicación está lista para recibir llamadas.
Llama al número virtual que vinculaste a la aplicación en el panel de control. Si todo funciona correctamente, deberías ser recibido con el mensaje de texto a voz que definiste en tu código Python.
Después de la prueba, termina el servidor para que puedas codificar el siguiente escenario.
En este escenario, incluiremos la acción NCCO Connect que conectará a la persona que llama con un agente después de completar la Talk acción.
Cree un nuevo archivo llamado scenario-2.py y añade el siguiente código:
from fastapi import FastAPI, Query
from vonage_voice import Talk, Connect, NccoAction, PhoneEndpoint
VONAGE_VIRTUAL_NUMBER = 'Replace-this-text-with-your-Vonage-virtual-number'
AGENT_NUMBER = 'Replace-this-text-with-your-agent-number'
app = FastAPI()
@app.get('/webhooks/answer')
async def answer_call():
ncco: list[NccoAction] = [
Talk(text="Hello, one moment please while your call is being forwarded to our agent."),
Connect(from_=VONAGE_VIRTUAL_NUMBER,
endpoint=[PhoneEndpoint(number=AGENT_NUMBER)]),]
return [action.model_dump(by_alias=True, exclude_none=True) for action in ncco]Este código crea el /webhooks/answer endpoint. Cuando este punto final recibe una solicitud de la Voice API, crea e itera a través de un archivo NCCO con una Talk y luego una acción Connect acción. La acción Connect acción requiere que proporciones tu número virtual de Vonage y un número de agente adicional para las variables VONAGE_VIRTUAL_NUMBER y AGENT_NUMBERrespectivamente. Puedes obtener más información sobre la conexión de llamadas con Voice API aquí.
Detenga las aplicaciones que pueda tener en ejecución de cualquier otro escenario de este tutorial y ejecútelas:
fastapi dev --port 3000 scenario-2.pyPara probar este escenario concreto, necesitarás dos números de teléfono: Uno con el que llamar al número virtual y otro número de teléfono al que conectarte. Marca tu número virtual de Vonage y, si todo se ha implementado correctamente, deberías ser recibido con el mensaje de texto a voz y luego debería sonar tu segundo número (el número del agente).
En este escenario, gestionamos una llamada entrante poniendo a la persona que llama en espera y reproduciendo música hasta que haya un agente disponible. A continuación, la llamada se transfiere al agente.
Este es el flujo de llamadas que implementaremos:
Cuando se responda a la llamada, el interlocutor escuchará un mensaje de texto a voz
La persona que llama se pondrá en espera y se le transmitirá música
Tras un retardo simulado de 30 segundos, la llamada se transferirá a un segundo OCN.
La segunda OCN reproduce un mensaje de texto a voz y conecta a la persona que llama con un agente.
Dado que este escenario concreto utiliza la Voice API para actualizar una llamada en cursonecesitamos el ID de la aplicación de Vonage y una clave privada para crear un cliente. Esto garantiza que el usuario que realiza la actualización esté autorizado y sea el propietario de la llamada: ¡sería bastante inquietante si de repente escucharas música de espera en una llamada con un amigo! El ID de la aplicación y la clave privada pueden obtenerse a través del panel de desarrollador de Vonage.
En el menú Aplicaciones del panel de desarrollador, haz clic en la aplicación que has creado para este tutorial y, a continuación, haz clic en "Editar." Una vez que se abra la ventana de edición, haz clic en el botón que dice "Generar clave pública y privada". Esto activará una descarga de su clave privada como un archivo con la extensión .key. Mantén este archivo en privado y no lo compartas en ningún sitio donde pueda estar en peligro. Haga clic en el botón "Guardar cambios" y anote también su ID de aplicación.
A screenshot of the application Edit menu in the Vonage developer dashboard showing where to generate a public and private key.
A screenshot of the inbound-call application in the Vonage developer dashboard showing where you can find the application ID.Mueve tu archivo de clave privada al mismo directorio donde se encuentra tu código Python. En el mismo directorio, crea un archivo llamado .env y añade lo siguiente:
APPLICATION_ID=Replace-this-with-your-application-ID
PRIVATE_KEY=Replace-this-with-the-name-of-your-private-key-file
Cree un nuevo archivo llamado scenario-3.py y añade el siguiente código:
import os
from dotenv import load_dotenv
from threading import Timer
from fastapi import FastAPI, Query
from vonage import Auth, Vonage
from vonage_voice import Talk, Connect, NccoAction, PhoneEndpoint, Stream
load_dotenv()
APPLICATION_ID = os.getenv("APPLICATION_ID")
PRIVATE_KEY = os.getenv("PRIVATE_KEY")
VONAGE_VIRTUAL_NUMBER = '**********' # Replace with your Vonage virtual number
AGENT_NUMBER = '**********' # Replace with your "agent" number
AUDIO_URL = "https://download.samplelib.com/mp3/sample-12s.mp3"
app = FastAPI()
def transfer_call(call_id):
print("Transferring the call ... ")
ncco: list[NccoAction] = [
Talk(text="Hello, one moment please while your call is being forwarded to our agent."),
Connect(from_=VONAGE_VIRTUAL_NUMBER,
endpoint=[PhoneEndpoint(number=AGENT_NUMBER)]),]
client = Vonage(Auth(application_id=APPLICATION_ID, private_key=PRIVATE_KEY,))
client.voice.transfer_call_ncco(uuid=call_id, ncco=ncco)
@app.get('/webhooks/answer')
async def answer_call(call_id: str = Query(..., alias='uuid')):
print(f"The UUID for this call is:====> {call_id}")
Timer(30, transfer_call, [call_id]).start()
ncco: list[NccoAction] = [
Talk(text="Hello, our agents are assisting other customers. Please hold and we will connect you as soon as possible."),
Stream(streamUrl=[AUDIO_URL],loop=0),]
return [action.model_dump(by_alias=True, exclude_none=True) for action in ncco]Este código contiene muchas cosas, así que vamos a desglosarlo.
Primero tendrás que actualizar las siguientes variables:
NÚMERO_VIRTUAL_DE_VAGE: Sustituye el texto del marcador de posición por tu número virtual de Vonage.
NÚMERO_AGENTE: Sustituya el texto del marcador de posición por el número de teléfono del "agente" al que se transferirá la llamada.
En este código, definimos el /webhooks/answer endpoint. Cuando este endpoint recibe una solicitud de la Voice API, crea e itera a través de un archivo NCCO con una acción Talk y luego una acción Stream para reproducir la música de espera.
La función transfer_call se encarga de crear un cliente de Vonage y luego transferir la llamada utilizando su número identificador único.
Como estamos simulando lo que sería ser puesto en espera, el código utiliza un objeto Timer para llamar a la función transfer_call después de 30 segundos.
Ahora que entiendes el código, vamos a ponerlo en marcha. Asegúrate de que no tienes ninguna otra aplicación en ejecución y ejecútala:
fastapi dev --port 3000 scenario-3.pyPara probar este escenario concreto, necesitarás dos números de teléfono: Uno para llamar al número virtual y otro número de teléfono para conectarte. Marca tu número virtual de Vonage y, si todo se ha implementado correctamente, deberías ser recibido con el mensaje de texto a voz seguido de música de espera. Después de 30 segundos, la llamada se transferirá al número de agente que proporcionaste.
En este tutorial, aprendiste a manejar llamadas telefónicas entrantes usando la Voice API de Vonage y una aplicación FastAPI de Python. Exploraste cómo los objetos de control de llamadas de Vonage (NCCO) definen los flujos de llamadas y cómo los webhooks permiten que tu aplicación responda a las llamadas entrantes en tiempo real. A través de tres escenarios prácticos, implementaste flujos de trabajo comunes de soporte al cliente: reproducir un mensaje de texto a voz, conectar a una persona que llama con un agente y poner a una persona en espera con música antes de transferir la llamada.
Además, configuró una aplicación Voice API, expuso un servidor FastAPI local mediante ngrok y utilizó Voice API para actualizar una llamada en curso. Estos elementos fundamentales pueden mejorar significativamente las interacciones con los clientes, mejorar los tiempos de respuesta y agilizar las operaciones de las empresas. Por ejemplo, se puede crear un sistema de multiconferencia, construir flujos de llamadas personalizadoso seguir el rendimiento de las campañas.
Los interesados en ampliar sus conocimientos pueden consultar artículos relacionados sobre Aplicaciones de voz en Python o Integración API para descubrir técnicas más avanzadas. La implementación de estos Concepts puede abrir oportunidades para experiencias de cliente personalizadas y automatización que pueden impulsar el crecimiento y la eficiencia del negocio.
Consulte la referencia Voice API para obtener una lista exhaustiva de los elementos que puede incorporar a sus aplicaciones de voz.
También puede obtener más información sobre las acciones de la OCNC en la guía oficial oficial
Conecta tu servidor de desarrollo local a la API de Vonage mediante un túnel Ngrok
¿Tienes alguna pregunta o algo que compartir? Únete a la conversación en Slack de la comunidad de Vonagey mantente actualizado con el Boletín para desarrolladoressíguenos en X (antes Twitter)suscríbete a nuestro canal de YouTube para ver tutoriales en video, y sigue la página de página para desarrolladores de Vonage en LinkedInun espacio para que los desarrolladores aprendan y se conecten con la comunidad. Mantente conectado, comparte tu progreso y entérate de las últimas noticias, consejos y eventos para desarrolladores.
Compartir:
Liz Acosta es promotora de desarrolladores en Vonage. Aunque su trayectoria profesional, de estudiante de cine a comercializadora, de ingeniera a defensora de los desarrolladores, puede parecer poco convencional, ¡es bastante típica de las relaciones con los desarrolladores! A Liz le encanta la pizza, las plantas, los carlinos y Python.