Senden und Empfangen von WhatsApp-Nachrichten mit Python, FastAPI und Vonage

Einführung

Möchten Sie einen WhatsApp-Bot mit Python erstellen? Möchten Sie WhatsApp-Nachrichten programmgesteuert senden und empfangen? Dieses Tutorial zeigt Ihnen, wie Sie einen Echtzeit-Nachrichtendienst mit Python erstellen können, FastAPI, und der Vonage Messages API.

Mit einem WhatsApp-Chatbot als Grundlage können Sie Support-, Erinnerungs- und Marketingabläufe automatisieren, wie z. B. das Versenden von Bestätigungen, die Bearbeitung von Kundenanfragen oder das Auslösen von Nachfassaktionen.

Wir verwenden das Vonage Python SDK um eine WhatsApp-Nummer mit einem FastAPI-Server zu verbinden, der Nachrichten in Echtzeit empfängt und beantwortet.

>> TL;DR Siehe das vollständige Projekt auf GitHub

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

Voraussetzungen

Für diese Anleitung benötigen Sie:

• Python 3.9+

• Ein verifizierter WhatsApp Business Account (WABA)

  • Sie haben noch keinen WhatsApp Business Account? Beginnen Sie mit unserem Sandbox-Schnellstart für WhatsApp um mit minimaler Einrichtung zu testen.

• ngrok installiert für die Offenlegung Ihres lokalen Servers

• Ein Vonage API-Konto

Vonage API-Konto

Um dieses Tutorial durchzuführen, benötigen Sie ein Vonage API-Konto. Wenn Sie noch keines haben, können Sie sich noch heute anmelden und mit einem kostenlosen Guthaben beginnen. Sobald Sie ein Konto haben, finden Sie Ihren API-Schlüssel und Ihr API-Geheimnis oben auf dem Vonage-API-Dashboard.

Sind Sie bereit, mit dem Bau zu beginnen?

Erleben Sie nahtlose Konnektivität, Echtzeit-Messaging und kristallklare Sprach- und Videoanrufe - alles auf Knopfdruck.

Schritt 1: Erstellen Sie Ihre Vonage App und Webhooks

Ihre FastAPI-Anwendung wird relativ einfach sein und aus einer einzigen Datei bestehen. Doch bevor wir sie erstellen, erstellen wir zunächst eine Vonage-Anwendung, um alle erforderlichen Konfigurationen bereitzustellen.

Erstellen einer Messages API-Applikation

Erstellen Sie Ihre Vonage-Anwendung im Vonage Dashboard. Geben Sie der Anwendung einen Namen und aktivieren Sie die Nachrichtenfunktion. Für den Moment verwenden wir Platzhalter-Endpunkte, die wir im nächsten Abschnitt (Expose Your Local FastAPI Server) ersetzen werden.

Setting up a Vonage Messages API application for WhatsApp using FastAPI and ngrok.In den Einstellungen Ihrer Vonage-Anwendung:

1. Setzen Sie die eingehende URL auf https://YOUR_NGROK_URL/inbound.

2. Setzen Sie die Status-URL auf https://YOUR_NGROK_URL/status.

3. Erzeugen Sie einen öffentlichen und einen privaten Schlüssel, indem Sie auf die Schaltfläche klicken. Stellen Sie sicher, dass Sie Ihren private.key Datei in das Hauptverzeichnis des Projekts (whatsapp-fastapi) im nächsten Abschnitt.

4. Speichern Sie die Änderungen.

Verknüpfen Sie dann Ihre WABA, indem Sie auf den Reiter "Externe Konten verknüpfen" klicken:

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

Lokalen FastAPI-Server freigeben

Um Webhooks zu empfangen, wird Ihre Anwendung auf ngrok angewiesen sein, um Ihren lokalen Server freizugeben.

In einer zweiten Registerkarte des Terminals:

ngrok http 3000

Kopieren Sie die NGROK_URL, die etwa so aussieht:

https://abc123.ngrok.io

Gehen Sie zurück zu Ihrer Vonage-Anwendung und aktualisieren Sie die Webhook-URLs, um IHRE_NGROK_URL durch Ihre tatsächlichen ngrok-URLs. Zum Beispiel:

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

• Status-URL: https://abc123.ngrok.io/status

Klicken Sie auf Speichern, um die Einrichtung abzuschließen.

>> Erfahren Sie mehr über Testen mit ngrok.

Schritt 2: Erstellen Sie Ihr Python-FastAPI-Projekt

Projekt einrichten

Erstellen Sie Ihren Projektordner:

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

Erstellen und aktivieren Sie dann eine virtuelle Umgebung, damit Sie die erforderlichen Python-Pakete installieren können:

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

• fastapi: Ein modernes, leistungsstarkes Web-Framework für die schnelle Erstellung von APIs mit asynchroner Unterstützung und automatischer Dokumentation.

• vonage: Das offizielle Python-SDK von Vonage, mit dem man WhatsApp-Nachrichten über die Vonage Messages API senden und empfangen kann.

• uvicorn: Ein blitzschneller ASGI-Server, mit dem Sie Ihre FastAPI-Anwendung in der Entwicklung oder Produktion ausführen können.

• python-dotenv: Lädt Umgebungsvariablen sicher aus einer .env Datei, so dass Sie keine Anmeldeinformationen in Ihrer Codebasis fest einprogrammieren müssen.

Konfigurieren Sie Ihre Umgebung

In Ihrer .env Datei fügen Sie Folgendes hinzu (ersetzen Sie es durch Ihre tatsächlichen Anmeldedaten). Diese Datei schützt Ihre Anmeldedaten und hält sie von Ihrem Quellcode fern.

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

• VONAGE_APPLICATION_ID: Ihre Vonage-Anwendungs-ID, zu finden im API-Dashboard.

• VONAGE_PRIVATE: Ihre private Schlüsseldatei. Stellen Sie sicher, dass Sie Ihre heruntergeladene private.key Datei in das Stammverzeichnis des Projekts (whatsapp-fastapi).

• VONAGE_WHATSAPP_NUMMER: Ihre virtuelle Vonage-Telefonnummer, die mit Ihrem WABA verbunden ist.

  • Telefonnummern sollten im internationalen Format ohne + oder 00 angegeben werden. Eine US-Nummer wäre zum Beispiel 15552345678

>> Erfahren Sie mehr über Python Umgebungsvariablen.

Initialisierung von FastAPI und Vonage SDK

Lassen Sie uns nun die Voraussetzungen für das Senden und Empfangen von WhatsApp-Nachrichten schaffen, indem wir Ihre FastAPI-Anwendung verkabeln und den Vonage-Client initialisieren.

Ihre main.py wird als Einstiegspunkt für Ihre FastAPI-Anwendung dienen.

# 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

Wir beginnen mit dem Import der erforderlichen Bibliotheken:

• os und dotenv helfen uns beim Laden sensibler Anmeldedaten aus unserer .env Datei zu laden.

• fastapi, Anfrageund Antwort werden verwendet, um API-Routen zu definieren und eingehende HTTP-Anfragen zu bearbeiten.

• vonage und vonage_messages ermöglichen uns den Zugriff auf die Vonage Messages API, insbesondere WhatsApp.

load_dotenv()

Hier laden wir Ihre .env Datei, so dass Sie sicher auf Ihre Anwendungs-ID, den Pfad zum privaten Schlüssel und die WhatsApp-Nummer zugreifen können, ohne sie fest zu kodieren.

logging.basicConfig(level=logging.INFO)

Dies ermöglicht eine grundlegende Protokollierung, die Ihnen bei der Fehlersuche und der Überwachung eingehender Nachrichten und Ereignisse in Ihrem Terminal hilft, sobald diese auftreten.

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

An dieser Stelle wird der Vonage Client mit dem neuen SDK initialisiert. Sie übergeben Ihre anwendungs_id und den Pfad zu Ihrer privaten Schlüsseldatei zur Authentifizierung Ihrer API-Anfragen. Die Vonage() Instanz ermöglicht es Ihnen, WhatsApp-Nachrichten über die Messages API zu versenden.

app = FastAPI()

Dadurch wird die FastAPI-Anwendungsinstanz erstellt. Sie verwenden diese, um Ihre Webhook-Endpunkte zu definieren und Ihren Entwicklungsserver auszuführen.

WHATSAPP_NUMBER = os.getenv("VONAGE_WHATSAPP_NUMBER")

Schließlich speichern wir die Nummer Ihres WhatsApp-Absenders in einer Variablen, damit Sie sie später beim Senden ausgehender Nachrichten einfach wiederverwenden können.

Schritt 3: Eingehende WhatsApp-Nachrichten bearbeiten und Antworten senden

Um einen funktionierenden WhatsApp-Bot zu erstellen, benötigen Sie zwei Webhook-Endpunkte:

1. Eine, um eingehende Nachrichten von WhatsApp-Benutzern zu empfangen

2. Eine zur Verfolgung von Nachrichtenstatusaktualisierungen (z. B. zugestellt, gelesen, fehlgeschlagen)

Sie können sich die funktionierende main.py Datei auf GitHub.

Eingehende Nachrichten über Webhook verarbeiten

Erstellen Sie eine /eingehend Endpunkt, der auf eingehende WhatsApp-Nachrichten wartet. Wenn jemand eine Nachricht an Ihre Vonage-WhatsApp-Nummer sendet, stellt Vonage eine POST-Anfrage an diese URL mit einer JSON-Nutzlast, die die Nachricht beschreibt.

So gehen Sie damit um:

@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 = {}

Dieser Block versucht, die eingehende Anfrage als JSON zu parsen. Wenn dies fehlschlägt (manchmal besteht der Textkörper nur aus rohen Bytes), wird er wieder dekodiert und manuell geladen.

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

Zur Fehlersuche und Transparenz wird die gesamte Nutzlast auf der Konsole protokolliert. Dies ist während der Entwicklung hilfreich, um zu verstehen, welche Felder verfügbar sind und wie die Daten strukturiert sind.

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

Hier extrahieren wir zwei Schlüsselfelder:

• von: die Telefonnummer des Nutzers, der die WhatsApp-Nachricht gesendet hat

• Textder eigentliche Inhalt der Nachricht

Eine WhatsApp-Antwort senden

Nun, da Sie die Nachricht erhalten haben, können Sie eine Antwort senden. In diesem Beispiel kehrt der Bot die Nachricht des Nutzers einfach um und sendet sie zurück; eine lustige und einfache Art, Zwei-Wege-Nachrichten zu demonstrieren.

  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}")

Es geht um Folgendes:

• Wir prüfen, ob sowohl die Absendernummer als auch die Nachricht vorhanden sind.

• Wir kehren die Zeichenkette mit der Python-Slice-Syntax um [::-1].

• Wir konstruieren einen WhatsappText Nachricht mithilfe des Vonage SDK. Dadurch wird die richtige JSON-Nutzlast unter der Haube erstellt.

• Schließlich senden wir die Nachricht mit vonage_client.messages.send(reply)und protokollieren die Antwort.

return Response(status_code=200)

Dies teilt Vonage mit, dass die Webhook-Anfrage erfolgreich empfangen wurde. Geben Sie immer ein 200 OK Antwort zurück, um die Webhook-Zustellung zu bestätigen.

Lieferung verfolgen und Quittungen lesen (optional)

Sie können auch auf Nachrichtenstatusereignisse hören, indem Sie eine /status Endpunkt implementieren. Dieser empfängt Zustellungsbestätigungen und Lesebestätigungen, was Ihnen bei der Fehlersuche oder Analyse des Nachrichtenflusses helfen kann.

@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)

Wenn Sie eine WhatsApp-Nachricht senden, ruft Vonage diesen Endpunkt später mit Statusaktualisierungen wie z. B. an:

• zugestellt: das Gerät des Benutzers hat die Nachricht erhalten

• lesen: der Benutzer hat die Nachricht geöffnet

• fehlgeschlagen: Zustellung fehlgeschlagen (z.B. ungültige Nummer)

Schritt 4: Ausführen und Testen der FastAPI-Anwendung

Starten Sie in Ihrem Terminal Ihren Server:

uvicorn main:app --reload --port 3000

Jetzt:

1. Senden Sie eine WhatsApp-Nachricht an Ihre Vonage WABA-Nummer

2. Ihre FastAPI-Anwendung wird:

   • Protokollieren Sie die eingehende Nachricht

   • Senden Sie eine stornierte Antwort mit der Vonage Messages API

3. Sie werden die Antwort in Ihrem WhatsApp-Chat sehen

>> Sie können den Status Ihrer Nachricht auf dem FastAPI-Server (Ihrem Terminal) sehen.

Bonus: Wie man eine WhatsApp-Nachricht versendet

Manchmal möchten Sie eine Nachricht programmgesteuert senden, nicht nur als Reaktion auf einen Webhook. Hier ist ein einfaches Skript, das Sie ausführen können. Erstellen Sie zunächst eine neue send_message.py Datei:

touch send_message.py

Dieses Skript sieht weitgehend genauso aus wie zuvor. Aber anstatt eine fest kodierte Nachricht zu senden, wird der Benutzer über die Befehlszeile aufgefordert, eine Telefonnummer und eine Nachricht einzugeben, die gesendet werden soll.

# 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)

Um es auszuführen:

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

Und dann wirst du sehen:

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

Schlussfolgerung

Sie haben jetzt einen funktionierenden WhatsApp-Bot in Python mit FastAPI und der Vonage Messages API erstellt. Dies ist ein großartiger Startpunkt für Echtzeit-Support, Automatisierung oder Chatbots!

Wenn Sie gerne weiter bauen und lernen möchten, sehen Sie sich diese verwandten Tutorials an:

1. WhatsApp mit ChatGPT in Python verbinden: OpenAI verwenden, um intelligente, dialogfähige Bots zu erstellen

2. RCS-Nachrichten in Python ausprobieren: RCS ist wie WhatsApp, aber nativ in der Messaging-App Ihres Telefons