Conmutación por error multiusuario y multicanal mediante Dispatch API

Este tutorial muestra cómo enviar un mensaje a una lista de usuarios con conmutación automática por error.

La idea es que usted tiene una lista de usuarios y cada usuario tiene dos o más canales designados, el último de los cuales es el canal de reserva final. Se intenta enviar el mensaje al primer usuario de la lista de usuarios prioritarios en sus canales designados. Cada canal se procesa por turnos, con una condición de reserva adecuada.

Si fallan todos los intentos de que un usuario lea el mensaje, el procesamiento pasa al siguiente usuario de la lista de prioridades.

A modo de ejemplo, imagine que su servidor principal ha funcionado mal y desea notificarlo a una lista de administradores del sistema que están de guardia. Cada administrador puede tener varios canales por los que puede ser contactado. La lista de usuarios se procesaría hasta que al menos uno de los administradores hubiera leído el mensaje importante.

Ejemplo

Quizá la mejor forma de entender este caso de uso sea consultar el archivo de configuración de ejemplo, sample.json:

La parte más importante de estos archivos de configuración es el archivo USERS sección. Aquí tienes una lista de usuarios prioritarios. En este caso, la aplicación intentará enviar el mensaje a Tony, y si Tony no consigue leer el mensaje en ninguno de los canales designados dentro del tiempo de expiración, el proceso se repite para Michael.

NOTA: La condición de conmutación por error para cada canal de read con un plazo de expiración de 600 está actualmente codificado en la aplicación, pero podría añadirse al archivo de configuración (véase caso-3 para saber cómo hacerlo).

Tenga en cuenta que se aplican las siguientes condiciones:

El usuario debe tener al menos dos canales.
El usuario puede mezclar cualquier número de canales y tipos siempre que haya al menos dos canales. Por ejemplo, un usuario podría tener 3 números SMS más un ID de Messenger.
El último canal especificado para un usuario se considerará el último canal de reserva. Se gestiona de forma ligeramente diferente ya que no tiene una condición de fallo asociada en el modelo de flujo de trabajo. Si falla, se procesará el siguiente usuario de la lista.
El canal alternativo final no tiene por qué ser SMS, aunque normalmente lo será.
Un flujo de trabajo se crea por usuario, pero puede especificar un flujo de trabajo único para cada usuario.
Se intenta aplicar un flujo de trabajo a cada usuario en el orden en que aparecen los usuarios en el archivo de configuración.
La conmutación por error de un canal al siguiente es automática y la gestiona de forma transparente la Dispatch API.

Código fuente

El código fuente Python de este proyecto está disponible en la comunidad Repositorio GitHub. En realidad, el código base incluye tres casos de uso, pero este tutorial sólo describe case-2. El código para case-2 específicamente se puede encontrar aquí. Hay dos archivos - el archivo de configuración de ejemplo, sample.json y la aplicación, app.py.

Requisitos previos

Crear una cuenta de Vonage
Instalar Node JS - necesario para usar la interfaz de línea de comandos (CLI) de Vonage.
Instalar la CLI de Vonage
Sepa cómo probar su servidor webhook localmente
Python 3 instalado
Frasco instalado
Account de los canales a los que desea dar soporte, como Facebook, Viber y WhatsApp.

También puede resultarle útil repasar los siguientes temas generales:

Si planeas probar este caso de uso con Facebook Messenger se recomienda que trabajes a través de este tutorial primero.

Los pasos

Una vez cumplidos los requisitos previos, los pasos son los siguientes:

Hay varias maneras de lograr el mismo resultado con Vonage. Este tutorial muestra sólo una manera específica de hacer las cosas, por ejemplo, verás cómo usar la línea de comandos para crear la aplicación, en lugar del Panel de control. Otros tutoriales muestran otras maneras de hacer las cosas.

Crea tu aplicación de Vonage

Si aún no lo ha hecho, cree un nuevo directorio para su proyecto, por ejemplo multi-user-dispatch. Cambia a este directorio.

Usa la CLI para crear tu aplicación de Vonage:

vonage apps:create "Multi-user Dispatch App" --messages_inbound_url=https://abcd1234.ngrok.io/inbound --messages_status_url=https://abcd1234.ngrok.io/status

Anote el ID de solicitud generado. También puede comprobarlo en el salpicadero.

Este comando también creará una clave privada, multi_user_dispatch_app.key en su directorio actual, así como actualizar/crear vonage_app.json.

Este comando también establece los dos webhooks donde tiene lugar toda la interacción entre tu aplicación y Vonage. Debes tener un servidor en ejecución y accesible para Vonage en estas URL

Poner en marcha Ngrok

Asegúrese de tener Ngrok ejecutándose para realizar pruebas localmente. Para iniciar Ngrok escriba:

ngrok http 9000

Para generar una URL temporal de Ngrok. Si eres suscriptor de pago puedes escribir:

ngrok http 9000 -subdomain=your_domain

NOTA: en este caso Ngrok desviará los webhooks de Vonage que especificaste al crear tu aplicación de Vonage a localhost:9000.

Ejecute su servidor webhook

Usted necesita tener su servidor webhook en funcionamiento para que los webhooks sean reconocidos, y los detalles de los mensajes enviados puedan ser registrados. Su servidor webhook sería similar al siguiente:

Añade este código a un archivo llamado server.py y guárdalo.

Ejecútalo localmente con:

python3 server.py

Revisar el código de la aplicación

Para mayor comodidad, el código está contenido en un único archivo app.py. Sólo existe esto y su archivo de configuración JSON, config.jsonque puede crearse inicialmente copiando sample.json.

Lo más importante es que el archivo de configuración almacena la lista de usuarios a contactar en orden de prioridad, además de sus canales designados. Cada usuario debe tener al menos dos canales en esta implementación, pero puede haber cualquier mezcla conveniente de canales por usuario. Por ejemplo, un usuario podría tener tres números SMS, otro usuario podría tener un ID de Messenger, Viber y dos números SMS adicionales.

El último canal listado para cada usuario es tratado como el último fallback antes de cambiar a otro usuario. Para cada usuario, se enviará a cada canal un mensaje utilizando la Dispatch API, con automático conmutación por error al siguiente canal si el mensaje no se lee en 600 segundos.

La primera parte del código de la aplicación, app.pylee el fichero de configuración y carga las variables y estructuras de datos importantes. Se asume que su empresa soportará los cuatro canales soportados por el Dispatch API, messenger, viber_service_msg, whatsapp y smsaunque a los usuarios objetivo sólo se les pueden asignar sus canales preferidos. Algunos usuarios, por ejemplo, solo pueden ser contactados por SMS.

Existe una función de ayuda, set_field_typespara gestionar el hecho de que algunos canales utilicen numbers y algunos utilizan idsy Viber, que utiliza ids y numbers.

La funcionalidad principal para este caso de uso se encuentra en la función build_user_workflow función. Este código construye un flujo de trabajo como el siguiente:

La función build_user_workflow también se asegura de que los valores leídos del archivo de configuración se incrusten en el flujo de trabajo.

Probablemente se habrá dado cuenta de que el expiry_time y condition_status están codificadas en el flujo de trabajo como incorporadas en build_user_workflow. Esto se hizo para mantener el código lo más sencillo posible, pero usted podría agregar estos parámetros al archivo de configuración por canal. En este caso, algunos usuarios podrían tener una caducidad de 300 segundos en algunos canales, y también podría especificar la condición de conmutación por error de read o delivered por canal. Esto se ha implementado para usted en caso-3 pero no se describe con más detalle en este tutorial, ya que se proporciona todo el código, junto con el archivo de configuración de ejemplo modificado.

Una vez creado el flujo de trabajo, se utiliza la función Dispatch API para enviar el mensaje:

Se genera un JWT para autenticar la llamada a la API. Esta es la razón por la que es necesario tener en cuenta el app_id y private_key cuando creaste tu aplicación de Vonage. Debes agregarlos a tu archivo de configuración.

Probar la aplicación

Copia sample.json a config.json.

Asegúrese de haber establecido los valores adecuados en config.json para parámetros como app_id, private_key y los detalles de los distintos canales compatibles. Asegúrese de que ha configurado su lista de usuarios de acuerdo con la forma en que desea probar las cosas.

TIP: Vale la pena validar su archivo de configuración modificado en este punto utilizando un Linter JSON.

A continuación, puede ejecutar la aplicación con:

python3 app.py

La aplicación procesará el archivo de configuración y se pondrá en contacto con cada usuario sucesivamente hasta que se haya leído el mensaje.

SMS

Puedes utilizar cualquier teléfono móvil que pueda recibir un SMS para probar este tutorial.

Facebook Messenger

Para realizar pruebas con Facebook Messenger se requieren algunos pasos adicionales. Estos se han discutido en detalle en este tutorialpor lo que esa información no se ha reproducido aquí.

Viber

Necesita un ID de mensaje de servicio de Viber para probar este tutorial con Viber.

Para probar este tutorial con WhatsApp necesita una Account de WhatsApp business. Además, el usuario de destino debe recibir un MTM antes de poder recibir mensajes de su empresa.

Resumen

En este tutorial has visto un caso de uso en el que puedes intentar enviar un mensaje a una lista de usuarios, donde cada usuario tiene múltiples canales. La aplicación termina cuando el mensaje ha sido leído.