Alimentation en données en temps réel de plusieurs canaux à l'aide de Messages API

Ce didacticiel vous montre comment envoyer des données à plusieurs canaux en temps réel à l'aide de l'API Messages. Ce tutoriel montre comment envoyer des données dans tous les canaux pris en charge. Des informations sur le test de tous les canaux sont fournies. Si vous souhaitez tester Facebook Messenger, il est recommandé de suivre la procédure suivante ce tutoriel car ce tutoriel contient de nombreuses informations spécifiques à Facebook. Pour tester WhatsApp et Viber, vous aurez besoin de comptes professionnels auprès de ces fournisseurs.

Exemple de scénario

Dans ce tutoriel, vous verrez comment envoyer des cours de bourse en temps réel à un utilisateur sur le canal de son choix. Un utilisateur peut s'inscrire pour recevoir des données sur le canal de son choix. Par exemple, il peut recevoir les cours de la bourse via son téléphone portable à l'aide de SMS ou via Facebook Messenger. WhatsApp et Viber sont également pris en charge. Pour Facebook Messenger, WhatsApp et SMS, les utilisateurs peuvent enregistrer leur intérêt pour une action particulière. Cependant, Viber ne prend pas en charge les messages entrants vers une entreprise, de sorte que les utilisateurs doivent s'inscrire pour recevoir les messages par l'intermédiaire d'un site web afin de recevoir des données. De plus, avec WhatsApp, il y a une complication supplémentaire : WhatsApp demande à une entreprise d'envoyer à l'utilisateur des données sur les actions. un MTM avant que l'utilisateur puisse accepter de recevoir des messages.

Veuillez noter que seuls des prix d'actions simulés sont utilisés dans ce tutoriel.

Code source

Le code source Python de ce projet est disponible dans la communauté Vonage. Dépôt GitHub. Un client générique particulièrement intéressant offre un moyen pratique d'envoyer un message à n'importe quel canal pris en charge avec un seul appel de méthode. Vous verrez également du code Python pour gérer les messages entrants sur WhatsApp, SMS et Messenger.

Conditions préalables

  1. Créer un Account Vonage
  2. Installer Node JS - nécessaire pour utiliser l'interface de ligne de commande (CLI) de Vonage.
  3. Installer le CLI de Vonage
  4. Savoir comment tester votre serveur webhook localement
  5. Python 3 installé
  6. Flacon installé
  7. 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 :

  1. Créer une application Vonage
  2. Faire fonctionner Ngrok
  3. Configurez vos webhooks SMS dans le tableau de bord
  4. Rédigez votre application de base
  5. Envoyer un SMS
  6. Examiner le code client générique
  7. Le cas d'utilisation revisité
  8. 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 real-time-app. Entrez dans ce répertoire.

Utilisez le CLI pour créer votre application Vonage :

vonage apps:create "Real-time App" --messages_inbound_url=https://abcd1234.ngrok.io/inbound --messages_status_url=https://abcd1234.ngrok.io/status

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, real_time_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

ngrok http 9000

Pour générer une URL Ngrok temporaire. Si vous êtes un abonné payant, vous pouvez taper :

ngrok http 9000 -subdomain=your_domain

Notez que 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.

Configurez vos webhooks SMS dans le tableau de bord

Dans le tableau de bord, cliquez sur Paramètres du compte. Dans cette section, vous pouvez définir les webhooks SMS au niveau de votre Account :

Notez que vous devrez remplacer "abcd1234" dans les URLs du webhook par vos propres informations. Si vous avez un Account Ngrok payant, il peut s'agir de votre domaine personnalisé.

NOTE : Cette étape est nécessaire car les applications Messages et Dispatch ne prennent actuellement en charge que les SMS sortants, et non les SMS entrants. C'est pourquoi vous utiliserez les webhooks SMS au niveau du compte pour prendre en charge les SMS entrants, mais vous utiliserez l'API Messages pour l'envoi de SMS sortants.

Rédigez votre application de base

Dans le cas le plus simple, votre application consignerait les informations relatives aux messages entrants, ainsi que les données relatives à la réception et à l'état des messages. Cela ressemblerait à 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)

@app.route('/webhooks/inbound-sms', methods=['POST'])
def inbound_sms():
    print ("** inbound_sms **")
    values = request.values
    pprint(values)
    return ("inbound_sms", 200)

@app.route('/webhooks/delivery-receipt', methods=['POST'])
def delivery_receipt():
    print ("** delivery_receipt **")
    data = request.get_json()
    pprint(data)
    return ("delivery_receipt", 200)

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

Ajoutez ce code à un fichier appelé app1.py et l'enregistrer.

Exécutez-le localement avec :

python3 app1.py

Envoyer un SMS

Votre application de base est maintenant opérationnelle et prête à enregistrer des événements. Vous pouvez tester cette application de base en envoyant un SMS à n'importe quel numéro Vonage lié à n'importe quelle application vocale, lorsque le numéro Vonage dispose de capacités vocales et de SMS. Si vous n'avez pas d'application vocale et que vous ne savez pas comment en créer une, vous pouvez consulter le document suivant cette information. La raison pour laquelle vous devez passer par cette étape supplémentaire est que l'API Messages and Dispatch ne prend pas actuellement en charge les SMS entrants, mais seulement les SMS sortants, de sorte que vous devez utiliser le webhook au niveau du compte pour recevoir des notifications de SMS entrants.

Lorsque vous examinez les informations de traçage produites lors de l'envoi d'un SMS, vous voyez quelque chose de similaire à ce qui suit :

** inbound_sms ** {'keyword': 'MESSAGE', 'message-timestamp': '2019-04-16 13:55:21', 'messageId': '1700000240EAA6B6', 'msisdn': '447700000001', 'text': 'Message from Tony', 'to': '447520635498', 'type': 'text'}

Client générique

Actuellement, Vonage ne prend pas officiellement en charge les Messages API et Dispatch API dans le SDK du serveur Python, mais notre API REST est prise en charge (Beta) et la fonction Le code Python est fourni dans le projet dans une classe réutilisable. Cette classe permet d'envoyer un message à l'aide de l'API Messages à l'un des canaux pris en charge. Le code vaut la peine d'être examiné rapidement :

    def send_message (self, channel_type, sender, recipient, msg):
        if channel_type == 'messenger':
            from_field = "id"
            to_field = "id"
        elif channel_type == 'whatsapp' or channel_type == "sms": 
            from_field = "number"
            to_field = "number"
        elif channel_type == 'viber_service_msg':
            from_field = "id"
            to_field = "number"
               
        data_body = json.dumps({
            "from": {
	        "type": channel_type,
	        from_field: sender
            },
            "to": {
	        "type": channel_type,
	        to_field: recipient
            },
            "message": {
	        "content": {
	            "type": "text",
	            "text": msg
	        }
            }
        })
...

Le corps est construit pour vous en fonction du type de canal. En effet, les détails sont légèrement différents d'un canal à l'autre - par exemple, Facebook utilise des identifiants, alors que WhatsApp et les SMS n'utilisent que des numéros. Viber utilise un identifiant et un numéro. Le code utilise ensuite l'API Messages pour envoyer le message à votre place. C'est la base du cas d'utilisation, avec quelques bits supplémentaires pour permettre l'inscription de l'utilisateur.

Le cas d'utilisation revisité

Il est temps d'examiner ce cas d'utilisation plus en détail afin que vous puissiez construire votre application de manière plus efficace.

Pour les canaux qui prennent en charge les messages entrants (Messenger, WhatsApp et SMS), vous pouvez permettre à l'utilisateur d'envoyer un message pour s'inscrire. Pour Viber, cela devra être fait via une autre partie de l'application web. Typiquement, vous devriez fournir un formulaire où l'utilisateur peut s'inscrire au flux en temps réel.

Si un utilisateur envoie un message entrant tel que "Salut", l'application répondra par un message d'aide. Dans notre cas, il s'agit de "Envoyez-nous un message contenant MSFT ou GOOGL pour obtenir des données en temps réel". L'inscription est ensuite confirmée par un autre message indiquant le flux auquel l'utilisateur s'est abonné.

Vous recevrez ensuite un prix en temps réel sur le symbole boursier que vous avez choisi. Si vous souhaitez vous inscrire sur un autre canal, vous êtes libre de le faire. De même, si vous souhaitez changer de symbole boursier, envoyez un message avec le nouveau symbole : vous recevrez un accusé de réception et le flux de données sera modifié en conséquence.

Le code de base pour mettre cela en œuvre se trouve dans la fonction proc_inbound_msg en app_funcs.py.

Dans le cas de WhatsApp, une étape supplémentaire est nécessaire pour envoyer un Message MTM à l'utilisateur avant qu'il ne puisse s'inscrire pour recevoir des données. Pour des raisons de simplicité, cette information est fournie sous la forme d'un morceau de code séparé.

Tester l'application

Vous pouvez utiliser l'application avec :

python3 app.py APP_ID

Où APP_ID est l'ID de l'application Vonage de votre application Messages.

SMS

Pour tester par SMS, envoyez un SMS comme vous l'avez fait précédemment. Vous recevrez un message d'aide. Renvoyez un message avec le symbole boursier de l'une ou l'autre des options suivantes MSFT ou GOOGL. Vous recevrez alors périodiquement une mise à jour (simulée) des prix. Vous devez actuellement quitter l'application pour ne plus recevoir ces messages, mais vous pourriez ajouter la possibilité de les désactiver, comme le montre l'exemple suivant 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 devez disposer d'un compte professionnel Viber valide pour tester cette solution. Une partie de votre application web demanderait à l'utilisateur fournit son numéro de téléphone et le symbole qui l'intéressent. L'utilisateur pourrait alors recevoir un premier message qu'il aurait la possibilité de recevoir ou de refuser. A petit programme d'essai est fourni pour démontrer que le client générique est testé avec Viber.

WhatsApp

WhatsApp nécessite une étape supplémentaire pour un test complet. Vous devez envoyer à l'utilisateur un MTM (modèle) WhatsApp avant qu'il ne puisse recevoir des messages. Le code pour ce faire n'a pas été décrit dans ce tutoriel mais un exemple de code est disponible. ici. Vous pouvez ensuite utiliser le client générique fourni dans ce tutoriel pour envoyer les messages WhatsApp suivants.

Résumé

Dans ce tutoriel, vous avez vu un cas d'utilisation où l'utilisateur peut recevoir des données en temps réel sur n'importe quel canal pris en charge par l'API Messages.

Autres ressources