Envoyer et recevoir des messages WhatsApp avec Python, FastAPI et Vonage

Introduction

Vous souhaitez créer un robot WhatsApp à l'aide de Python ? Vous avez besoin d'envoyer et de recevoir des messages WhatsApp de manière programmatique ? Ce tutoriel vous montre comment créer un service de messagerie en temps réel à l'aide de Python, FastAPI, et l'API Vonage Messages API.

Avec un chatbot WhatsApp comme base, vous pourrez automatiser l'assistance, les rappels et les flux marketing, comme l'envoi de confirmations, le traitement des demandes des clients ou le déclenchement de suivis.

Nous utiliserons le SDK Python de Vonage pour connecter un numéro WhatsApp au sein d'un serveur FastAPI qui reçoit et répond aux messages en temps réel.

>> TL;DR Voir le projet projet complet sur GitHub

WhatsApp chat showing an automated reply from a Python FastAPI app using the Vonage Messages API

Conditions préalables

Pour suivre ce tutoriel, vous aurez besoin de :

• Python 3.9+

• A vérifié Compte professionnel WhatsApp (WABA)

  • Vous n'avez pas encore de compte WhatsApp Business ? Commencez avec notre Démarrage rapide de l'Environnement de test pour WhatsApp pour tester avec une configuration minimale.

• ngrok installé pour exposer votre serveur local

• Un Account API de Vonage

Vonage API Account

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.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Étape 1 : Créer votre application Vonage et vos crochets Web

Votre application FastAPI sera relativement simple, avec un seul fichier. Mais avant de la créer, nous commencerons par créer une application Vonage afin de disposer de toutes les configurations nécessaires.

Créer une application Messages API

Créez votre application Vonage dans le tableau de bord Vonage. Donnez un nom à l'application et activez la fonction Messages. Pour l'instant, nous utiliserons des points d'extrémité fictifs, que nous remplacerons dans la section suivante (Exposer votre serveur FastAPI local).

Setting up a Vonage Messages API application for WhatsApp using FastAPI and ngrok.Dans les paramètres de votre application Vonage :

1. Définir l'URL entrant à https://YOUR_NGROK_URL/inbound.

2. Définissez l'URL de l'état comme suit https://YOUR_NGROK_URL/status.

3. Générez une clé publique et une clé privée en cliquant sur le bouton. Veillez à déplacer votre clé.privée dans le répertoire racine du projet (whatsapp-fastapi) dans la section suivante.

4. Enregistrez les modifications.

Liez ensuite votre WABA en cliquant sur l'onglet "Lier des comptes externes" :

Viewing the WhatsApp-FastAPI application in the Vonage dashboard with an active WhatsApp number linked.

Exposer votre serveur FastAPI local

Pour recevoir des webhooks, votre application s'appuiera sur ngrok pour exposer votre serveur local.

Dans un deuxième onglet du terminal :

ngrok http 3000

Copiez l'URL NGROK qui ressemble à quelque chose comme :

https://abc123.ngrok.io

Retournez à votre application Vonage et mettez à jour les URLs du webhook pour remplacer YOUR_NGROK_URL par vos véritables URLs ngrok. Par exemple :

• URL entrant : https://abc123.ngrok.io/inbound

• URL du statut : https://abc123.ngrok.io/status

Cliquez sur Enregistrer pour finaliser la configuration.

>> En savoir plus sur les tests avec ngrok.

Étape 2 : Créer votre projet Python FastAPI

Configuration du projet

Créez votre dossier de projet :

mkdir whatsapp-fastapi
cd whatsapp-fastapi
touch main.py .env

Ensuite, créez et activez un environnement virtuel afin d'installer les paquets Python requis :

python3 -m venv venv
source venv/bin/activate
pip install fastapi uvicorn python-dotenv vonage

• fastapi: Un framework web moderne et performant pour construire rapidement des API avec un support asynchrone et une documentation automatique.

• vonage: Le SDK Python officiel de Vonage, utilisé pour envoyer et recevoir des messages WhatsApp via l'API Messages de Vonage.

• uvicorn: Un serveur ASGI ultra-rapide utilisé pour exécuter votre application FastAPI en développement ou en production.

• python-dotenv: Charge les variables d'environnement de manière sécurisée à partir d'un fichier .env afin de ne pas coder en dur les informations d'identification dans votre base de code.

Configurer votre environnement

Dans votre fichier .env ajoutez ce qui suit (remplacez par vos identifiants réels). Ce fichier permet de sécuriser vos informations d'identification et de les garder en dehors de votre code source.

VONAGE_APPLICATION_ID=your_application_id
VONAGE_PRIVATE_KEY=./private.key
VONAGE_WHATSAPP_NUMBER=your_vonage_virtual_number

• VONAGE_APPLICATION_ID: Votre ID d'application Vonage, qui se trouve dans le tableau de bord de l'API. tableau de bord de l'API.

• VONAGE_PRIVATE: Votre fichier de clé privée. Veillez à déplacer votre fichier private.key dans le répertoire racine du projet (whatsapp-fastapi).

• NUMÉRO DE TÉLÉPHONE DE VONAGE_WHATSAPP: Votre numéro de téléphone virtuel Vonage associé à votre WABA.

  • Les numéros de téléphone doivent être au format international, sans + ni 00. Par exemple, un numéro américain serait 15552345678

>> En savoir plus sur Variables d'environnement Python.

Initialiser FastAPI et Vonage SDK

Préparons maintenant le terrain pour l'envoi et la réception de messages WhatsApp en câblant votre application FastAPI et en initialisant le client Vonage.

Votre main.py servira de point d'entrée à votre application FastAPI.

# main.py
import os
import logging
import json
from dotenv import load_dotenv
from fastapi import FastAPI, Request, Response
from vonage import Auth, Vonage
from vonage_messages import WhatsappText

Nous commençons par importer les bibliothèques nécessaires :

• os et dotenv nous aident à charger des informations d'identification sensibles à partir de notre fichier .env .

• fastapi, Demandeet Response sont utilisées pour définir les routes de l'API et gérer les requêtes HTTP entrantes.

• vonage et vonage_messages nous permettent d'accéder à l'API Messages de Vonage, et plus particulièrement à WhatsApp.

load_dotenv()

Nous chargeons ici votre fichier .env afin que vous puissiez accéder en toute sécurité à l'identifiant de votre application, au chemin de la clé privée et au numéro WhatsApp sans les coder en dur.

logging.basicConfig(level=logging.INFO)

Cette fonction permet d'effectuer une journalisation de base pour vous aider à déboguer et à surveiller les messages et les événements entrants dans votre terminal au fur et à mesure qu'ils se produisent.

auth = Auth(
    application_id=os.getenv("VONAGE_APPLICATION_ID"),
    private_key=os.getenv("VONAGE_PRIVATE_KEY"),
)
vonage_client = Vonage(auth)

C'est ici que nous initialisons le client Vonage à l'aide du nouveau SDK. Vous passez votre application_id et le chemin d'accès à votre fichier de clé privée pour authentifier vos demandes d'API. La fonction Vonage() vous permettra d'envoyer des messages WhatsApp à l'aide de l'API Messages.

app = FastAPI()

Cela crée l'instance d'application FastAPI. Vous l'utiliserez pour définir les points de terminaison de vos webhooks et pour exécuter votre serveur de développement.

WHATSAPP_NUMBER = os.getenv("VONAGE_WHATSAPP_NUMBER")

Enfin, nous stockons votre numéro d'expéditeur WhatsApp dans une variable afin qu'il soit facile à réutiliser lors de l'envoi ultérieur de messages sortants.

Étape 3 : Traiter les messages WhatsApp entrants et envoyer des réponses

Pour créer un bot WhatsApp fonctionnel, vous avez besoin de deux points de terminaison webhook :

1. Un pour recevoir les messages entrants des utilisateurs de WhatsApp

2. Un pour suivre les mises à jour de l'état des messages (par exemple, délivré, lu, échoué)

Vous pouvez voir le fichier main.py sur GitHub.

Gestion des messages entrants via Webhook

Créer un fichier /inbound qui écoute les messages WhatsApp entrants. Lorsque quelqu'un envoie un message à votre numéro WhatsApp de Vonage, Vonage effectue une requête POST vers cette URL avec une charge utile JSON décrivant le message.

Voici comment procéder :

@app.post("/inbound")
async def receive_whatsapp_message(request: Request):
    try:
        data = await request.json()
    except Exception:
        raw = await request.body()
        try:
            data = json.loads(raw)
        except:
            data = {}

Ce bloc tente d'analyser la requête entrante en JSON. En cas d'échec (parfois, le corps n'est constitué que d'octets bruts), il revient au décodage et au chargement manuel.

 logging.info(f"🔍 Full inbound payload: {json.dumps(data, indent=2)}")

Pour des raisons de débogage et de transparence, nous enregistrons l'ensemble des données dans la console. Ceci est utile pendant le développement pour comprendre quels champs sont disponibles et comment les données sont structurées.

    sender = data.get("from")
    message = data.get("text")

Nous extrayons ici deux champs clés :

• de: le numéro de téléphone de l'utilisateur qui a envoyé le message WhatsApp.

• texte: le contenu du message

Envoyer une réponse WhatsApp

Maintenant que vous avez reçu le message, envoyons une réponse. Dans cet exemple, le bot se contente d'inverser le message de l'utilisateur et de le lui renvoyer ; une façon simple et amusante de montrer la messagerie bidirectionnelle.

  if sender and message:
        reversed_text = message[::-1]
        reply = WhatsappText(
            from_=WHATSAPP_NUMBER,
            to=sender,
            text=f"Here's your message in reverse: {reversed_text}",
        )
        response = vonage_client.messages.send(reply)
        logging.info(f"📤 Sent reply: {response}")

Voici ce qui se passe :

• Nous vérifions que le numéro de l'expéditeur et le message sont tous deux présents.

• Nous inversons la chaîne de messages en utilisant la syntaxe de tranche de Python [::-1].

• Nous construisons un WhatsappText à l'aide du SDK de Vonage. Cela crée la charge utile JSON appropriée sous le capot.

• Enfin, nous envoyons le message avec vonage_client.messages.send(reply)et enregistrons la réponse.

return Response(status_code=200)

Cela indique à Vonage que la demande de webhook a été reçue avec succès. Renvoyez toujours un 200 OK pour accuser réception du webhook.

Suivi de la livraison et lecture des accusés de réception (facultatif)

Vous pouvez également écouter les événements relatifs à l'état des messages en mettant en œuvre une fonction /status . Celui-ci reçoit les confirmations de livraison et les accusés de réception, ce qui peut vous aider à déboguer ou à analyser le flux de messages.

@app.post("/status")
async def message_status_update(request: Request):
    data = await request.json()
    logging.info(f"📬 Status update: {data}")
    return Response(status_code=204)

Lorsque vous envoyez un message WhatsApp, Vonage appellera ce point de terminaison plus tard avec des mises à jour d'état telles que :

• livrél'appareil de l'utilisateur a reçu le message

• lirel'utilisateur a ouvert le message

• échoué: la livraison a échoué (par exemple, numéro non valide)

Étape 4 : Exécuter et tester votre application FastAPI

Dans votre terminal, démarrez votre serveur :

uvicorn main:app --reload --port 3000

Aujourd'hui :

1. Envoyer un message WhatsApp à votre numéro Vonage WABA

2. Votre application FastAPI :

   • Enregistrer le message entrant

   • Envoyer une réponse inversée à l'aide de l'API Messages de Vonage

3. Vous verrez la réponse dans votre chat WhatsApp.

>> Vous pouvez voir le statut de votre message mis à jour dans le serveur FastAPI (votre terminal).

Bonus : Comment envoyer un message WhatsApp

Parfois, vous souhaitez envoyer un message de manière programmée, et pas seulement en réponse à un webhook. Voici un script simple que vous pouvez exécuter. Tout d'abord, créez un nouveau fichier send_message.py :

touch send_message.py

Ce script est en grande partie le même que le précédent. Mais au lieu d'envoyer un message codé en dur, nous demanderons à l'utilisateur, via la ligne de commande, d'entrer un numéro de téléphone et un message à envoyer.

# send_message.py
import os
from dotenv import load_dotenv
from vonage import Auth, Vonage
from vonage_messages import WhatsappText

load_dotenv()

auth = Auth(
    application_id=os.getenv("VONAGE_APPLICATION_ID"),
    private_key=os.getenv("VONAGE_PRIVATE_KEY"),
)

vonage_client = Vonage(auth)

# Ask the user for phone number and message text
recipient = input("Enter recipient phone number (e.g., 14155551234): ").strip()
message = input("Enter a message to send: ").strip()

msg = WhatsappText(
    from_=os.getenv("VONAGE_WHATSAPP_NUMBER"),
    to=recipient,
    text=message,
)

response = vonage_client.messages.send(msg)
print(response)

Pour le faire fonctionner :

source venv/bin/activate && python3 send_message.py

Et vous verrez :

Sending a WhatsApp message using the Python CLI with FastAPI and the Vonage SDK.

Conclusion

Vous avez maintenant construit un bot WhatsApp fonctionnel en Python en utilisant FastAPI et l'API Messages de Vonage. C'est un excellent point de départ pour l'assistance en temps réel, l'automatisation ou les chatbots !

Si vous souhaitez continuer à construire et à apprendre, consultez ces tutoriels :

1. Connecter WhatsApp à ChatGPT en PythonLes bots intelligents : utiliser OpenAI pour construire des bots intelligents et conversationnels

2. Essayer la messagerie RCS en Python: RCS est comme WhatsApp, mais en natif dans l'application de messagerie de votre téléphone.