WhatsApp API avec Python : bibliothèques, exemples et cas d'usage

Python est le langage de prédilection de millions de développeurs dans le monde, et cette popularité s'étend également aux équipes techniques des entreprises africaines. Que vous construisiez un chatbot pour une banque mobile au Cameroun, un système de confirmation de commande pour un e-commerce ivoirien ou une plateforme de notifications pour une assurance marocaine, Python offre un écosystème riche pour interagir avec l'API WhatsApp Business Cloud. Ce guide recense les meilleures bibliothèques disponibles, propose des exemples concrets et couvre les cas d'usage les plus fréquents.

Les bibliothèques Python pour WhatsApp API

Plusieurs options s'offrent aux développeurs Python souhaitant interagir avec l'API WhatsApp Business Cloud de Meta. Voici les principales :

Approche directe avec requests : la bibliothèque standard requests reste la plus simple et la plus directe. Elle ne nécessite aucune abstraction supplémentaire et vous donne un contrôle total sur les requêtes HTTP vers l'API Graph de Meta.

pip install requests python-dotenv

heyoo : une bibliothèque open-source légère spécialement conçue pour l'API WhatsApp Cloud. Elle simplifie les appels courants comme l'envoi de messages, de templates et la gestion des webhooks.

pip install heyoo

pywa : une bibliothèque plus complète avec support des webhooks, des messages interactifs et une gestion avancée des états de conversation. Idéale pour des projets plus ambitieux.

pip install pywa

Pour la majorité des projets, l'approche avec requests reste recommandée en production car elle minimise les dépendances et facilite la maintenance à long terme. Voyons comment l'utiliser.

Envoyer des messages avec Python et l'API Cloud

Commençons par la configuration de base et l'envoi d'un message texte simple :

import requests
import os
from dotenv import load_dotenv

load_dotenv()

WHATSAPP_TOKEN = os.getenv('WHATSAPP_TOKEN')
PHONE_NUMBER_ID = os.getenv('PHONE_NUMBER_ID')
BASE_URL = f"https://graph.facebook.com/v18.0/{PHONE_NUMBER_ID}/messages"
HEADERS = {
    "Authorization": f"Bearer {WHATSAPP_TOKEN}",
    "Content-Type": "application/json"
}

def send_text_message(to: str, text: str) -> dict:
    """Envoie un message texte simple via l'API WhatsApp Cloud."""
    payload = {
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": to,
        "type": "text",
        "text": {"body": text}
    }
    
    response = requests.post(BASE_URL, json=payload, headers=HEADERS)
    response.raise_for_status()
    return response.json()

# Envoyer une notification à un client marocain
result = send_text_message("212661234567", "Bonjour Hamid, votre colis est en route !")
print(f"Message ID : {result['messages'][0]['id']}")

Pour les messages avec template (indispensables pour initier une conversation après 24h sans interaction) :

def send_template_message(to: str, template_name: str, lang: str = "fr", 
                           body_params: list = None) -> dict:
    """Envoie un message template HSM avec paramètres optionnels."""
    components = []
    
    if body_params:
        components.append({
            "type": "body",
            "parameters": [{"type": "text", "text": p} for p in body_params]
        })
    
    payload = {
        "messaging_product": "whatsapp",
        "to": to,
        "type": "template",
        "template": {
            "name": template_name,
            "language": {"code": lang},
            "components": components
        }
    }
    
    response = requests.post(BASE_URL, json=payload, headers=HEADERS)
    response.raise_for_status()
    return response.json()

# Envoyer une confirmation de rendez-vous
send_template_message(
    to="225071234567",
    template_name="rappel_rdv",
    lang="fr",
    body_params=["Aminata Koné", "demain à 10h00", "Clinique du Plateau"]
)

Recevoir les messages avec Flask (webhooks)

Un chatbot ou un système de réponse automatique nécessite la réception des messages entrants via webhooks. Voici une implémentation complète avec Flask :

from flask import Flask, request, jsonify
import hashlib, hmac, json

app = Flask(__name__)
VERIFY_TOKEN = os.getenv('VERIFY_TOKEN')
APP_SECRET = os.getenv('APP_SECRET')

@app.route('/webhook', methods=['GET'])
def verify_webhook():
    """Vérification initiale du webhook par Meta."""
    mode = request.args.get('hub.mode')
    token = request.args.get('hub.verify_token')
    challenge = request.args.get('hub.challenge')
    
    if mode == 'subscribe' and token == VERIFY_TOKEN:
        return challenge, 200
    return 'Forbidden', 403

@app.route('/webhook', methods=['POST'])
def receive_message():
    """Traitement des messages entrants."""
    # Vérification de la signature
    signature = request.headers.get('X-Hub-Signature-256', '')
    expected = 'sha256=' + hmac.new(
        APP_SECRET.encode(),
        request.get_data(),
        hashlib.sha256
    ).hexdigest()
    
    if not hmac.compare_digest(signature, expected):
        return 'Unauthorized', 401
    
    data = request.json
    
    if data.get('object') == 'whatsapp_business_account':
        for entry in data.get('entry', []):
            for change in entry.get('changes', []):
                messages = change.get('value', {}).get('messages', [])
                for msg in messages:
                    process_message(msg)
    
    return jsonify({'status': 'ok'}), 200

def process_message(msg: dict):
    """Logique métier de traitement des messages."""
    sender = msg['from']
    msg_type = msg['type']
    
    if msg_type == 'text':
        text = msg['text']['body'].lower().strip()
        
        if 'commande' in text:
            send_text_message(sender, 
                "Pour passer commande, répondez avec : NOM PRODUIT QUANTITÉ\n"
                "Exemple : Riz basmati 5kg")
        elif 'solde' in text or 'balance' in text:
            # Appel à votre base de données ici
            send_text_message(sender, "Consultation de votre solde en cours...")
        else:
            send_text_message(sender, 
                "Bonjour ! Tapez :\n• *commande* pour passer une commande\n"
                "• *solde* pour voir votre solde\n• *aide* pour l'assistance")

if __name__ == '__main__':
    app.run(debug=True, port=5000)

Cas d'usage avancés : envoi de médias et messages interactifs

Au-delà des simples textes, l'API supporte images, documents, boutons et listes. Ces formats enrichissent considérablement l'expérience client, particulièrement pour les commerces en ligne africains qui souhaitent présenter leurs produits directement dans WhatsApp.

def send_image_url(to: str, image_url: str, caption: str = "") -> dict:
    """Envoie une image depuis une URL publique."""
    payload = {
        "messaging_product": "whatsapp",
        "to": to,
        "type": "image",
        "image": {
            "link": image_url,
            "caption": caption
        }
    }
    response = requests.post(BASE_URL, json=payload, headers=HEADERS)
    response.raise_for_status()
    return response.json()

def send_interactive_buttons(to: str, body_text: str, buttons: list) -> dict:
    """Envoie un message avec boutons de réponse rapide (max 3 boutons)."""
    payload = {
        "messaging_product": "whatsapp",
        "to": to,
        "type": "interactive",
        "interactive": {
            "type": "button",
            "body": {"text": body_text},
            "action": {
                "buttons": [
                    {"type": "reply", "reply": {"id": b["id"], "title": b["title"]}}
                    for b in buttons
                ]
            }
        }
    }
    response = requests.post(BASE_URL, json=payload, headers=HEADERS)
    response.raise_for_status()
    return response.json()

# Exemple : demander confirmation d'une commande
send_interactive_buttons(
    to="237671234567",
    body_text="Votre commande de 2x Tisane Moringa à 5000 FCFA. Confirmer ?",
    buttons=[
        {"id": "confirm_yes", "title": "Oui, confirmer"},
        {"id": "confirm_no", "title": "Annuler"},
        {"id": "modify", "title": "Modifier"}
    ]
)

Pour orchestrer ces fonctionnalités dans un système complet de marketing WhatsApp, explorez les possibilités offertes par l'automatisation des flux WhatsApp. Whakup fournit une couche no-code au-dessus de l'API pour les équipes marketing, tout en laissant les développeurs accéder à l'API brute pour les intégrations personnalisées.

Consultez également le guide complet WhatsApp Business API pour comprendre les limites de débit, la gestion des templates et les bonnes pratiques de conformité.

FAQ

Q: Quelle bibliothèque Python recommandez-vous pour débuter avec WhatsApp API ?

R: Pour débuter, requests avec une structure simple est la meilleure option. Elle est universellement connue, bien documentée et vous force à comprendre les appels API réels. Une fois à l'aise, pywa offre une abstraction plus complète pour les projets plus complexes avec gestion d'état de conversation.

Q: Comment gérer les erreurs de rate limiting en Python ?

R: Implémentez un mécanisme de retry avec backoff exponentiel. Utilisez la bibliothèque tenacity qui simplifie ce pattern : @retry(wait=wait_exponential(multiplier=1, min=4, max=60), stop=stop_after_attempt(5)). Les erreurs 429 (Too Many Requests) déclenchent automatiquement l'attente et la relance.

Q: Peut-on utiliser Python asynchrone (asyncio) avec l'API WhatsApp ?

R: Oui, avec httpx ou aiohttp à la place de requests. C'est recommandé pour les applications qui envoient beaucoup de messages en parallèle, notamment lors de campagnes. Utilisez asyncio.gather() pour envoyer plusieurs messages simultanément dans les limites du rate limit.

Q: Comment tester unitairement du code qui appelle l'API WhatsApp ?

R: Utilisez unittest.mock ou pytest-mock pour simuler les réponses de l'API sans faire de vraies requêtes. Créez des fixtures de réponse JSON réalistes (en copiant des vraies réponses de l'API de test Meta) et mockez requests.post dans vos tests.

Q: L'API WhatsApp Cloud est-elle compatible avec les frameworks Django et FastAPI ?

R: Totalement. Django et FastAPI sont d'excellents choix pour héberger vos webhooks WhatsApp. FastAPI est particulièrement adapté pour les webhooks grâce à son support natif de l'asynchrone et à sa validation automatique via Pydantic. Django convient mieux aux projets avec une base de données et un admin panel.

---

Déployez votre intégration Python WhatsApp avec une plateforme marketing complète. Inscrivez-vous sur Whakup et connectez votre code à un tableau de bord analytics, une gestion des templates et une segmentation avancée.