Basculement multi-utilisateurs et multi-canaux à l'aide de Dispatch API
Ce tutoriel vous montre comment envoyer un message à une liste d'utilisateurs avec basculement automatique.
L'idée est que vous avez une liste d'utilisateurs et que chaque utilisateur a deux canaux désignés ou plus, dont le dernier est le canal de repli final. On tente d'envoyer le message au premier utilisateur de la liste de priorité des utilisateurs sur leurs canaux désignés. Chaque canal est traité à tour de rôle, avec une condition de basculement appropriée.
Si toutes les tentatives de lecture du message par un utilisateur échouent, le traitement passe à l'utilisateur suivant dans la liste des priorités.
Imaginons par exemple que votre serveur principal présente un dysfonctionnement et que vous souhaitiez en informer une liste d'administrateurs système qui sont de garde. Chaque administrateur peut disposer de plusieurs canaux sur lesquels il peut être contacté. La liste des utilisateurs serait traitée jusqu'à ce qu'au moins un des administrateurs ait lu le message important.
Exemple de scénario
La meilleure façon de comprendre ce cas d'utilisation est peut-être d'examiner l'exemple de fichier de configuration, 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 partie la plus importante de ce fichier de configuration est la section USERS section. Vous disposez ici d'une liste d'utilisateurs prioritaires. Dans ce cas, l'application tentera d'envoyer le message à Tony, et si Tony ne lit pas le message sur l'un des canaux désignés dans le délai imparti, le processus est répété pour Michael.
NOTE : La condition de basculement pour chaque canal de read avec un délai d'expiration de 600 est actuellement codé en dur dans l'application, mais pourrait être ajouté au fichier de configuration (voir cas-3 pour savoir comment procéder).
Les conditions suivantes s'appliquent :
- L'utilisateur doit disposer d'au moins deux canaux.
- L'utilisateur peut combiner autant de canaux et de types qu'il le souhaite, à condition qu'il y ait au moins deux canaux. Par exemple, un utilisateur peut avoir 3 numéros de SMS plus un identifiant Messenger.
- Le dernier canal spécifié pour un utilisateur sera considéré comme le canal de repli final. Il est traité légèrement différemment car il n'est pas associé à une condition de basculement dans le modèle de flux de travail. En cas d'échec, l'utilisateur suivant dans la liste sera traité.
- Le canal de repli final n'est pas obligatoirement un SMS, mais c'est généralement le cas.
- Un flux de travail est créé par utilisateur, mais vous pouvez spécifier un flux de travail unique pour chaque utilisateur.
- On tente d'appliquer un flux de travail à chaque utilisateur dans l'ordre dans lequel les utilisateurs sont répertoriés dans le fichier de configuration.
- Le basculement d'un canal à l'autre est automatique et géré de manière transparente par l'API Dispatch.
Code source
Le code source Python de ce projet est disponible dans la communauté Dépôt GitHub. Trois cas d'utilisation sont en fait inclus dans la base de code, mais ce tutoriel ne décrit que les cas d'utilisation suivants case-2. Le code pour case-2 peut notamment être trouvée ici. Il y a deux fichiers - le fichier de configuration de l'échantillon, sample.json et l'application, app.py.
Conditions préalables
- Créer un Account Vonage
- Installer Node JS - nécessaire pour utiliser l'interface de ligne de commande (CLI) de Vonage.
- Installer le CLI de Vonage
- Savoir comment tester votre serveur webhook localement
- Python 3 installé
- Flacon installé
- Disposer de comptes pour les canaux que vous souhaitez prendre en charge, tels que Facebook, Viber et WhatsApp.
Il peut également s'avérer utile de passer en revue les rubriques suivantes :
Si vous envisagez de tester ce cas d'utilisation avec Facebook Messenger, il est recommandé de suivre la procédure suivante ce tutoriel d'abord.
Les étapes
Une fois les conditions préalables remplies, les étapes sont les suivantes :
- Créer une application Vonage
- Faire fonctionner Ngrok
- Lancez votre serveur webhook
- Examiner le code de l'application
- Tester l'application
Il existe plusieurs façons d'obtenir le même résultat avec Vonage. Ce tutoriel ne montre qu'une façon spécifique de faire les choses, par exemple vous verrez comment utiliser la ligne de commande pour créer l'application, plutôt que le tableau de bord. D'autres tutoriels démontrent d'autres façons de faire.
Créez votre Applications Vonage
Si vous ne l'avez pas encore fait, créez un nouveau répertoire pour votre projet, par exemple multi-user-dispatch. Entrez dans ce répertoire.
Utilisez le CLI pour créer votre application Vonage :
Notez l'identifiant d'application généré. Vous pouvez également le vérifier dans la fenêtre tableau de bord.
Cette commande crée également une clé privée, multi_user_dispatch_app.key dans votre répertoire actuel, ainsi que la mise à jour/création de vonage_app.json.
Cette commande définit également les deux webhooks où toutes les interactions ont lieu entre votre application et Vonage. Vous devez avoir un serveur en cours d'exécution et accessible à Vonage à ces URLs
Faire fonctionner Ngrok
Assurez-vous que vous avez lancé Ngrok pour le tester localement. Pour démarrer Ngrok, tapez
Pour générer une URL Ngrok temporaire. Si vous êtes un abonné payant, vous pouvez taper :
NOTE : dans ce cas, Ngrok détournera les webhooks de Vonage que vous avez spécifiés lors de la création de votre application Vonage vers localhost:9000.
Lancez votre serveur webhook
Vous devez mettre en place votre serveur webhook afin que les webhooks soient reconnus et que les détails des messages envoyés puissent être enregistrés. Votre serveur webhook doit ressembler à ce qui suit :
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)
Ajoutez ce code à un fichier appelé server.py et l'enregistrer.
Exécutez-le localement avec :
Examiner le code de l'application
Pour des raisons de commodité, le code est contenu dans un seul fichier app.py. Il n'y a que cela et votre fichier de configuration JSON, config.jsonqui peut être créé initialement en copiant sample.json.
Plus important encore, le fichier de configuration contient la liste des utilisateurs à contacter par ordre de priorité, ainsi que les canaux qui leur sont attribués. Dans cette implémentation, chaque utilisateur doit avoir au moins deux canaux, mais il peut y avoir n'importe quelle combinaison de canaux par utilisateur. Par exemple, un utilisateur peut avoir trois numéros de SMS, un autre peut avoir un identifiant Messenger, Viber et deux numéros de SMS supplémentaires.
Le dernier canal répertorié pour chaque utilisateur est considéré comme le dernier recours avant de passer à un autre utilisateur. Pour chaque utilisateur, un message sera envoyé à chaque canal à l'aide de la Dispatch API, avec la mention automatique le basculement vers le canal suivant si le message n'est pas lu dans les 600 secondes.
La première partie du code de l'application, app.pylit le fichier de configuration et charge les variables et les structures de données importantes. Il est supposé que votre entreprise prendra en charge les quatre canaux supportés par l'API Dispatch, messenger, viber_service_msg, whatsapp et smsBien que les utilisateurs cibles puissent se voir attribuer uniquement les canaux qu'ils préfèrent, il est possible de les contacter uniquement par SMS. Certains utilisateurs, par exemple, ne peuvent être contactés que par SMS.
Il existe une fonction d'assistance, set_field_typesLe système de gestion de l'information permet de gérer le fait que certains canaux utilisent le système de gestion de l'information de l'Union européenne. numbers et certains utilisent idset Viber qui utilise à la fois ids et numbers.
La principale fonctionnalité de ce cas d'utilisation se trouve dans la rubrique build_user_workflow fonction. Ce code construit un flux de travail tel que le suivant :
{
"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 fonction build_user_workflow permet également de s'assurer que les valeurs lues dans le fichier de configuration sont intégrées dans le flux de travail.
Vous avez probablement remarqué que le expiry_time et condition_status sont codées en dur dans le flux de travail, en tant qu'éléments intégrés dans le système build_user_workflow. Cela a été fait pour que le code soit aussi simple que possible, mais vous pouvez ajouter ces paramètres au fichier de configuration pour chaque canal. Dans ce cas, certains utilisateurs pourraient avoir une expiration de 300 secondes sur certains canaux, et vous pourriez également spécifier la condition de basculement de read ou delivered par canal. Cela a été mis en œuvre pour vous dans cas-3 mais il n'est pas décrit plus avant dans ce tutoriel car tout le code est fourni, ainsi que l'exemple de fichier de configuration modifié.
Une fois le flux de travail construit, vous utilisez la fonction Dispatch API pour envoyer le message :
r = requests.post('https://api.nexmo.com/v0.1/dispatch', headers=headers, data=workflow)
Un JWT est généré afin d'authentifier l'appel API. C'est la raison pour laquelle vous devez noter l'élément app_id et private_key lorsque vous avez créé votre application Vonage. Ces valeurs doivent être ajoutées à votre fichier de configuration.
Tester l'application
Copie sample.json à config.json.
Assurez-vous d'avoir défini les valeurs appropriées dans config.json pour des paramètres tels que app_id, private_key et les détails des différents canaux pris en charge. Assurez-vous d'avoir configuré votre liste d'utilisateurs en fonction de la manière dont vous souhaitez tester les choses.
TIP : Il est utile de valider votre fichier de configuration modifié à ce stade à l'aide d'une commande Filtre JSON.
Vous pouvez ensuite exécuter l'application avec :
L'application traitera le fichier de configuration et contactera chaque utilisateur à tour de rôle jusqu'à ce que le message ait été lu.
SMS
Vous pouvez utiliser n'importe quel téléphone portable capable de recevoir un SMS pour tester ce tutoriel.
Facebook Messenger
Pour tester Facebook Messenger, quelques étapes supplémentaires sont nécessaires. Celles-ci ont été discutées en détail dans ce tutorielCette information n'a donc pas été reproduite ici.
Viber
Vous avez besoin d'un identifiant de message de service Viber pour tester ce tutoriel avec Viber.
Pour tester ce tutoriel avec WhatsApp, vous devez disposer d'un compte professionnel WhatsApp. En outre, l'utilisateur cible doit recevoir un MTM avant de pouvoir recevoir des messages de votre entreprise.
Résumé
Dans ce tutoriel, vous avez vu un cas d'utilisation dans lequel vous pouvez essayer d'envoyer un message à une liste d'utilisateurs, où chaque utilisateur a plusieurs canaux. L'application se termine lorsque le message a été lu.