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 fracasan 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 de situación
Quizá la mejor forma de entender este caso de uso sea consultar el archivo de configuración de ejemplo, sample.json:
{
"APP": {
"APP_ID": "abcd1234-8238-42d0-a03a-abcd1234...",
"PRIVATE_KEY": "private.key"
},
"FROM": {
"MESSENGER": "COMPANY MESSENGER ID",
"VIBER": "COMPANY VIBER ID",
"WHATSAPP": "COMPANY WHATSAPP NUMBER",
"SMS": "COMPANY SMS NAME/NUMBER"
},
"USERS": [
{
"name": "Tony",
"channels": [
{
"type": "messenger",
"id_num": "USER MESSENGER ID"
},
{
"type": "sms",
"id_num": "USER PHONE NUMBER"
}
]
},
{
"name": "Michael",
"channels": [
{
"type": "viber_service_msg",
"id_num": "USER PHONE NUMBER"
},
{
"type": "whatsapp",
"id_num": "USER PHONE NUMBER"
},
{
"type": "sms",
"id_num": "USER PHONE NUMBER"
}
]
}
]
}
La parte más importante de estos archivos de configuración es el 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 ver el código sobre cómo hacerlo).
Tenga en cuenta que se aplican las siguientes condiciones:
- El usuario debe tener al menos dos canales.
- El usuario puede combinar cualquier número de canales y tipos, siempre que haya al menos dos canales. Por ejemplo, un usuario podría tener tres números de SMS y un ID de Messenger.
- El último canal especificado para un usuario se considerará el canal de reserva definitivo. Su tratamiento es ligeramente diferente, ya que no tiene asociada ninguna condición de conmutación por error en el modelo de flujo de trabajo. Si este falla, se procesará al siguiente usuario de la lista.
- El canal alternativo final no tiene por qué ser SMS, aunque normalmente lo será.
- Los flujos de trabajo se crean por usuario, pero puedes especificar un flujo de trabajo específico 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 de 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 un Account de Vonage
- Instalar Node JS - Es necesario para utilizar 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
- Flask instalado
- Dispón de cuentas en las redes sociales que quieras utilizar, como Facebook, Viber y WhatsApp.
También puede resultarle útil repasar los siguientes temas generales:
Si tienes pensado probar este caso de uso con Facebook Messenger, te recomendamos que sigas los pasos de este tutorial primero.
Los pasos
Una vez cumplidos los requisitos previos, los pasos son los siguientes:
- Crear una aplicación de Vonage
- Poner en marcha Ngrok
- Ejecute su servidor webhook
- Revisar el código de la aplicación
- Probar la aplicación
Hay varias formas de conseguir el mismo resultado con Vonage. Este tutorial solo muestra una forma concreta de hacerlo; por ejemplo, verás cómo utilizar la línea de comandos para crear la aplicación, en lugar del panel de control. Otros tutoriales muestran otras formas de hacerlo.
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:
Anota el ID de aplicación generado. También puedes consultarlo en el cuadro de mando.
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 configura los dos webhooks a través de los cuales se produce toda la interacción entre tu aplicación y Vonage. Debes tener un servidor en funcionamiento y accesible para Vonage en estas URL
Poner en marcha Ngrok
Asegúrate de que Ngrok esté en ejecución para realizar pruebas de forma local. Para iniciar Ngrok, escribe:
Para generar una URL temporal de Ngrok. Si eres suscriptor de pago puedes escribir:
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
Debes poner en marcha tu servidor de webhooks para que se confirmen los webhooks y se puedan registrar los detalles de los mensajes enviados. Tu servidor de webhooks sería similar al siguiente:
from flask import Flask, request, jsonify
from pprint import pprint
app = Flask(__name__)
@app.route('/webhooks/inbound', methods=['POST'])
def inbound_message():
print ("** inbound_message **")
data = request.get_json()
pprint(data)
return ("inbound_message", 200)
@app.route('/webhooks/status', methods=['POST'])
def message_status():
print ("** message_status **")
data = request.get_json()
pprint(data)
return ("message_status", 200)
if __name__ == '__main__':
app.run(host="localhost", port=9000)
Añade este código a un archivo llamado server.py y guárdalo.
Ejecútalo localmente con:
Revisar el código de la aplicación
Por comodidad, el código se encuentra 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 cambiar al siguiente canal si el mensaje no se lee en un plazo de 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 crea un flujo de trabajo como el siguiente:
{
"template": "failover",
"workflow": [
{
"from": {
"type": "messenger",
"id": "from_messenger"
},
"to": {
"type": "messenger",
"id": "user_id_num"
},
"message": {
"content": {
"type": "text",
"text": "This is a Facebook Messenger message sent using the Dispatch API"
}
},
"failover": {
"expiry_time": "600",
"condition_status": "read"
}
},
{
"from": {
"type": "viber_service_msg",
"id": "from_viber"
},
"to": {
"type": "viber_service_msg",
"number": "user_id_num"
},
"message": {
"content": {
"type": "text",
"text": "This is a Viber Service Message sent using the Dispatch API"
}
},
"failover": {
"expiry_time": "600",
"condition_status": "read"
}
},
{
"from": {
"type": "sms",
"number": "from_sms"
},
"to": {
"type": "sms",
"number": "user_id_num"
},
"message": {
"content": {
"type": "text",
"text": "This is an SMS sent using the Dispatch API"
}
}
}
]
}
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 el Dispatch API para enviar el mensaje:
r = requests.post('https://api.nexmo.com/v0.1/dispatch', headers=headers, data=workflow)
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 valores que introdujiste al crear tu aplicación de Vonage. Debes añadirlos 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úrate de haber configurado tu lista de usuarios según cómo quieras realizar las pruebas.
CONSEJO: Vale la pena validar su archivo de configuración modificado en este punto utilizando un Validador de JSON.
A continuación, puede ejecutar la aplicación con:
La aplicación procesará el archivo de configuración y se pondrá en contacto con cada usuario por turnos hasta que se haya leído el mensaje.
SMS
Puedes utilizar cualquier teléfono móvil capaz de recibir 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.
Necesitas un Account de WhatsApp Business para probar este tutorial con WhatsApp. Además, hay que enviar un MTM al usuario destinatario antes de que pueda recibir mensajes de tu 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.