Jetzt bauen

WhatsApp-API mit Python: Nachrichten senden, empfangen und automatisieren

WhatsApp-API in PythonPython + WhatsApp API

WhatsApp-API mit PythonNachrichten senden, empfangen und automatisieren

Alles, was Sie brauchen, um das WhatsApp-API in PythonWelche Bibliothek man wählen soll, wie man ein verknüpftes Konto mit einem QR-Code verbindet und wie man Nachrichten sendet und empfängt Anfragen und httpx, und wie man einen FastAPI-Webhook für einen Bot oder einen KI-Agenten verkabelt.
Mit Python entwickeln API-Referenz anzeigen
REST-API heute, keine Meta-Unternehmensverifizierung erforderlich
send_whatsapp.py
import requests BASE_URL = "https://{YOUR_DSN}/api/v1" HEADERS = {"X-API-KEY": "YOUR_ACCESS_TOKEN"} def send_whatsapp(chat_id: str, text: str) -> dict: response = requests.post( f"{BASE_URL}/chats/{chat_id}/messages", headers=HEADERS, data={"text": text}, ) response.raise_for_status() return response.json() send_whatsapp("9f9uio56sopa456s", "Hallo von Python!")
200 OK, Nachricht gesendet
Definition

Was ist die WhatsApp-API in Python?

Die WhatsApp-API in Python bedeutet, WhatsApp Business-Nachrichten aus Python-Code aufzurufen, anstatt sich durch WhatsApp Web zu klicken. Ein Python-Skript oder Backend-Dienst sendet eine HTTP-Anfrage, normalerweise mit Anfragen oder httpx, zu einer REST-API, die Chats, Nachrichten und Webhooks bereitstellt, entweder direkt über Metas Cloud-API oder über einen einheitlichen Anbieter wie Unipile, der WhatsApp neben LinkedIn, Instagram und Telegram über eine einzige Schnittstelle anbindet. Meta veröffentlicht kein offizielles All-in-One-WhatsApp-Python-SDK, weshalb fast jede Python-Integration in diesem Leitfaden und das Meiste, was Sie im restlichen Web finden, direkt mit den REST-Endpunkten kommuniziert.
Eine REST-API für WhatsApp, LinkedIn, Instagram und Telegram
Verknüpft mit einem QR-Code oder einem Kopplungscode, keine Meta-Business-Verifizierung
Anfragen für einfache Skripte, httpx für Asynchronität im großen Stil
Für die Orientierungsebene, Zugang, Kosten und Limits beginnen Sie mit dem WhatsApp-API-Zugriff, Kosten- und Limit-Leitfaden. Statt Python in PHP entwickeln?
Lies dieselbe Integration in PHP
Bevor Sie bauen

Was brauchen Sie, bevor Sie beginnen?

Sie benötigen kein Meta Business-Konto oder eine WhatsApp Business Platform-Genehmigung, um mit dem Senden und Empfangen von Nachrichten über Python zu beginnen. Sie benötigen eine funktionierende Python-Umgebung, einen HTTP-Client, einen Ort zum Empfangen von Webhooks und ein Unipile-Konto.
Python 3.9+
Entspricht der Mindestversion, die vom Unipile Python SDK selbst benötigt wird pydantic Abhängigkeit, und durch moderne httpx und FastAPI-Releases.
Requests oder HTTPX
Pip-Installationsanfragen für synchrone Aufrufe oder pip install httpx Wenn Sie planen, Nachrichten gleichzeitig zu senden. Siehe die Anfragen und httpx Dokumentation.
Ein lokaler Tunnel
Ein Werkzeug wie ngrok oder cloudflared um deine FastAPI-Webhook-Route während der Entwicklung über eine öffentliche HTTPS-URL verfügbar zu machen.
Zugangstoken und DSN
Beide stammen aus dem Unipile-Dashboard. Die DSN ist der Host, den Sie aufrufen, und das Access Token gehört in das X-API-KEY Header jeder Anfrage.
Erstellen Sie Ihre erste WhatsApp-Integration
Bibliotheksvergleich

Welche Python-Bibliothek sollte man für WhatsApp verwenden?

Es gibt keine einfache, offensichtliche Antwort, und die meisten Blogbeiträge zu diesem Thema bevorzugen das Paket, das ihr jeweiliger Autor betreut. Hier ist ein sachlicher Vergleich der fünf Wege, wie Python-Entwickler WhatsApp heute tatsächlich nutzen – von Browser-Automatisierung bis hin zu einem einheitlichen Anbieter –, damit Sie basierend darauf wählen können, was die jeweilige Option tatsächlich leistet, und nicht aufgrund von Marketing.
Bibliothek / Ansatz
Wie es tatsächlich heißt
Meta Unternehmensverifizierung
Gepflegt
Am besten für
pywhatkit
Betreibt WhatsApp Web in einem Browser-Tab (Tastaturautomatisierung), keine serverseitige API
Nicht zutreffend, keine API
Gemeinschaft, sporadisch
Einmalige Skripte und Demos auf einem Computer mit Bildschirm, kein produktiver Versand
WhatsApp Cloud API
Dünner Python-Wrapper um Metas eigene WhatsApp Cloud API-Endpunkte
Erforderlich
Community-Wrapper
Teams, die bereits für die Cloud-API freigeschaltet sind und einen Python-Client wünschen
whatsapp-api-client-python
Ruft das green-api SaaS auf, das wiederum die WhatsApp-Sitzung hält
Nicht erforderlich
Vom Anbieter gepflegt
Teams, die sich darauf verlassen können, von einem zweiten, auf einen einzigen Zweck ausgerichteten SaaS-Anbieter abhängig zu sein
Anfragen, direkt an Meta
Meta Cloud-API-Endpunkte, ganz ohne Wrapper
Erforderlich
Mach es selbst
Teams, die bereits für die Meta Business-Verifizierung freigegeben sind und die vollständige Kontrolle behalten möchten
Unipile, requests oder httpx
Die einheitliche Messaging-API von Unipile, WhatsApp neben LinkedIn, Instagram und Telegram
Nicht erforderlich
Aktiv gewartet, Python-SDK in der Beta-Phase
SaaS-Produkte, die im Namen jedes Benutzers viele Endbenutzer-WhatsApp-Konten verbinden
pywhatkit
AnrufeFührt WhatsApp Web in einem Browser-Tab aus, nicht als serverseitige API
Meta-VerifizierungNicht zutreffend, keine API
GepflegtGemeinschaft, sporadisch
Am besten fürSkripte für den einmaligen Gebrauch und Demos, kein produktiver Versand
WhatsApp Cloud API
AnrufeDünner Wrapper um Metas eigene Cloud-API-Endpunkte
Meta-VerifizierungErforderlich
GepflegtCommunity-Wrapper
Am besten fürBereits auf der Cloud-API genehmigte Teams
whatsapp-api-client-python
AnrufeDas Green-API-SaaS, das die WhatsApp-Sitzung hält
Meta-VerifizierungNicht erforderlich
GepflegtVom Anbieter gepflegt
Am besten fürTeams, die mit einem zweiten SaaS-Anbieter vertraut sind
Anfragen, direkt an Meta
AnrufeMeta Cloud API Endpoints, kein Wrapper
Meta-VerifizierungErforderlich
GepflegtMach es selbst
Am besten fürTeams bereits für die Meta Business-Verifizierung freigegeben
Unipile, requests oder httpx
AnrufeUnified-Messaging-API, WhatsApp mit LinkedIn, Instagram, Telegram
Meta-VerifizierungNicht erforderlich
GepflegtAktiv gewartet, Python-SDK in der Beta-Phase
Am besten fürSaaS-Produkte, die viele Endbenutzerkonten verbinden
Jede Option, die behält Meta-Unternehmensverifizierung erforderlich schließlich mit der WhatsApp Cloud API von Meta spricht (siehe Dokumentation der WhatsApp Business Platform von Meta), was die richtige Entscheidung ist, wenn Sie bereits eine verifizierte Unternehmensnummer verwenden. Wenn Sie stattdessen WhatsApp-Konten im Auftrag vieler verschiedener Endbenutzer verbinden, entfällt dieser Verifizierungsschritt durch die Verwendung eines QR-Codes oder Kopplungscodes vollständig. Dies ist das Modell, das im weiteren Verlauf dieses Leitfadens verwendet wird.
Kontoverbindung

Wie verbindet man ein WhatsApp-Konto in Python?

Jeder Aufruf in dieser Anleitung wird ausgeführt im Namen eines authentifizierten Benutzers die ihr eigenes WhatsApp-Konto verknüpft haben. Es gibt keinen Meta-Business-Verifizierungsschritt: Von Python aus senden Sie eine einzelne POST /api/v1/accounts Anfrage mit provider festlegen auf WHATSAPP, und der Nutzer den Link entweder durch Scannen eines QR-Codes oder durch Eingabe eines Kopplungscodes auf seinem Telefon bestätigt.
Option A: QR-Code (Standard)
Verlassen Mobiltelefonnummer koppeln aus dem Anforderungskörper und Unipile gibt einen Checkpoint zurück, der die QR-Code-Nutzlast enthält. Rendern Sie ihn mit einer Bibliothek wie QR-Code und zeige es dem Benutzer an, damit er es von WhatsApp > Verknüpfte Geräte scannen kann.
connect_qr.py
import requests BASE_URL = "https://{YOUR_DSN}/api/v1" HEADERS = {"X-API-KEY": "YOUR_ACCESS_TOKEN", "accept": "application/json"} def connect_whatsapp_qr() -> dict: response = requests.post( f"{BASE_URL}/accounts", headers=HEADERS, json={"provider": "WHATSAPP"}, ) response.raise_for_status() return response.json() account = connect_whatsapp_qr() print(account) # account enthält eine neue account_id sowie ein Checkpoint-Objekt. # Geben Sie den Checkpoint als QR-Code aus und lassen Sie den Nutzer diesen scannen # unter "WhatsApp > Verknüpfte Geräte".
Option B: Kopplungscode
Pass Mobiltelefonnummer koppeln im E.164-Format nur Ziffern, Ländercode zuerst, kein Pluszeichen, keine Leerzeichen. Unipile gibt einen Prüfpunkt mit einem kurzen Code zurück, den der Benutzer in WhatsApp eingibt, anstatt etwas zu scannen, was besser zu einem Headless-Server ohne Bildschirm passt, auf dem ein QR-Code angezeigt werden könnte.
connect_pairing_code.py
def connect_whatsapp_pairing_code(phone_e164_digits: str) -> dict: response = requests.post( f"{BASE_URL}/accounts", headers=HEADERS, json={ "provider": "WHATSAPP", "pairing_phone_number": phone_e164_digits, }, ) response.raise_for_status() return response.json() # Ländervorwahl + Nummer, nur Ziffern, z. B. Frankreich account = connect_whatsapp_pairing_code("33612345678") # Der Checkpoint des Kontos enthält den Kopplungscode, der in Ihrer Benutzeroberfläche angezeigt werden soll. # Der Nutzer gibt ihn in WhatsApp unter "Verbundene Geräte" > "Mit Telefonnummer verknüpfen" ein.
Bestätigen Sie, dass das Konto verbunden ist.
Sobald der Nutzer den QR-Code scannt oder den Kopplungscode eingibt, müssen Sie wissen, wann das Konto tatsächlich bereit zum Senden und Empfangen ist. Unipile bietet Ihnen zwei Möglichkeiten.
Kontostatus abfragen
Rufen GET /api/v1/accounts/{account_id} alle paar Sekunden, bis das Konto seine Überprüfung nicht mehr benötigt. Einfach, aber es verschwendet Anfragen, während man wartet.
Kontostatus-Webhook
Registrieren Sie einen Webhook mit Quelle festlegen auf Kontostatus (gleich POST /api/v1/webhooks Endpunkt für Nachrichten) und Unipile-Push-Benachrichtigungen {"AccountStatus": {"account_id": "...", "message": "OK"}} Sobald das Konto bereit ist. Dies wird von den meisten Produktionsintegrationen verwendet.
poll_status.py
import time def wait_for_connection(account_id: str, timeout_seconds: int = 120) -> dict: deadline = time.time() + timeout_seconds while time.time() < deadline: response = requests.get(f"{BASE_URL}/accounts/{account_id}", headers=HEADERS) response.raise_for_status() account = response.json() print(account) # Überprüfen Sie die Live-Nutzdaten für Ihre eigene Statusprüfung time.sleep(2) raise TimeoutError("WhatsApp-Konto hat die Verbindung nicht rechtzeitig bestätigt")
Erstelle den Verbindungsablauf
Senden Sie

Wie sendet man eine WhatsApp-Nachricht mit Python?

Das Senden einer WhatsApp-Nachricht von Python aus ist ein einzelner HTTP-Aufruf: POST /api/v1/chats/{chat_id}/messages, mit dem chat_id Sie bereits aus dem Auflisten von Chats oder von einem eingehenden Webhook haben, und ein text Feld. Der Endpunkt akzeptiert sowohl formulatorisch als auch JSON-codierte Inhaltskörper gleichermaßen, sodass ein einfacher requests.post mit Daten= funktioniert ohne zusätzliche Einrichtung.
Wenn kein vorhandener chat_id, zum Beispiel die erste Nachricht an einen neuen Kontakt, Anruf POST /api/v1/chats sondern mit einem account_id und des Empfängers attendees_ids; Unipile erstellt den 1:1-Chat und sendet die Nachricht in derselben Anfrage.
send.py
import requests BASE_URL = "https://{YOUR_DSN}/api/v1" HEADERS = {"X-API-KEY": "YOUR_ACCESS_TOKEN"} def send_message(chat_id: str, text: str) -> dict: response = requests.post( f"{BASE_URL}/chats/{chat_id}/messages", headers=HEADERS, data={"text": text}, ) response.raise_for_status() return response.json() def start_chat(account_id: str, attendee_provider_id: str, text: str) -> dict: response = requests.post( f"{BASE_URL}/chats", headers=HEADERS, data={ "account_id": account_id, "attendees_ids": attendee_provider_id, "text": text, }, ) response.raise_for_status() return response.json()
Nachrichtentypen (Text, Medien, Sprachnachrichten, Vorlagen) und das 24-Stunden-Kundendienstfenster sind ein eigenes Thema, das ausführlich behandelt wird im Leitfaden zu Nachrichtentypen, die die WhatsApp API unterstützt. Dieser Abschnitt behandelt nur die Python-Infrastruktur.
Meta berechnet WhatsApp API-Nachrichten seit Juli 2025 pro gesendeter Nachricht und nicht pro Unterhaltung. Siehe Wie die WhatsApp API-Preise pro Nachricht funktionieren für die aktuellen Tarife pro Land.
Gleichzeitigkeit

Wie sendet man asynchrone WhatsApp-Nachrichten in Python?

Wenn Sie zu viele Empfänger auf einmal senden, eine Broadcast-Nachricht, eine Warteschlangenentleerung, einen Massen-Follow-up-Job, eine Schleife, die auf einen wartet requests.post zu einer Zeit ist der Engpass, nicht die API. httpx.AsyncClient kombiniert mit asyncio.gather feuert viele Anfragen gleichzeitig von einer einzigen Event-Loop ab, keine Threads erforderlich. Ein Semaphor ist das, was Sie zu einem guten Bürger macht: WhatsApp-Konten unterliegen nach wie vor den plattformeigenen Ratenbegrenzungen, sodass unbegrenzte Nebenläufigkeit eine langsame Schleife lediglich gegen eine Wand aus 429-Antworten eintauscht.
send_bulk_async.py
import asyncio import httpx BASE_URL = "https://{YOUR_DSN}/api/v1" HEADERS = {"X-API-KEY": "YOUR_ACCESS_TOKEN"} CONCURRENCY_LIMIT = 5 async def send_message_async( client: httpx.AsyncClient, semaphore: asyncio.Semaphore, chat_id: str, text: str, ) -> dict: async with semaphore: response = await client.post( f"{BASE_URL}/chats/{chat_id}/messages", headers=HEADERS, data={"text": text}, ) response.raise_for_status() return response.json() async def send_bulk(messages: list[tuple[str, str]]) -> list: semaphore = asyncio.Semaphore(CONCURRENCY_LIMIT) async with httpx.AsyncClient(timeout=30) as client: tasks = [ send_message_async(client, semaphore, chat_id, text) for chat_id, text in messages ] return await asyncio.gather(*tasks, return_exceptions=True) messages = [ ("9f9uio56sopa456s", "Your order shipped!"), ("a1b2c3d4e5f6g7h8", "Your order shipped!"), ] results = asyncio.run(send_bulk(messages)) for chat_id_text, result in zip(messages, results): if isinstance(result, Exception): print("failed:", chat_id_text[0], result)
Behalten GLEICHZEITIGKEITS_LIMIT konservativ und erhöhen Sie ihn erst, nachdem Sie reale Fehlerraten beobachtet haben. return_exceptions=True Das bedeutet, dass ein fehlgeschlagener Sendevorgang den Rest des Batches nicht abbricht, was wichtig ist, sobald Sie Hunderte von Nachrichten in einem Durchgang versenden. Der Abschnitt zu Ratenbegrenzung und Wiederholungsversuchen unten baut auf demselben Muster auf.
Bauen Sie Ihre Versand-Pipeline auf
Webhaken

Wie empfängt man WhatsApp-Nachrichten mit einem FastAPI-Webhook?

Ein Webhook sorgt dafür, dass Ihr Python-Dienst im Moment des Eintreffens von einer neuen WhatsApp-Nachricht erfährt, anstatt danach zu pollen. Sie registrieren einen Endpunkt bei Unipile, und jedes passende Ereignis wird als JSON an Ihren Server gesendet. FastAPI passt naturgemäß zur Empfängerseite: eine pydantic Modell validiert die Nutzlast für Sie, und Hintergrundprozesse Sorgen Sie dafür, dass Ihre Route sofort eine Antwort zurückgibt, während die eigentliche Arbeit – das Aufrufen eines Modells und das Schreiben in eine Datenbank – danach erfolgt.
1. Registrieren Sie den Webhook
Punkt anfrage_url an deiner FastAPI-Route. Während der lokalen Entwicklung bedeutet das die HTTPS-URL, die dein Tunnel (aus dem Abschnitt zu den Voraussetzungen oben) bereitstellt, nicht localhost.
register_webhook.py
import requests BASE_URL = "https://{YOUR_DSN}/api/v1" HEADERS = {"X-API-KEY": "YOUR_ACCESS_TOKEN"} response = requests.post( f"{BASE_URL}/webhooks", headers=HEADERS, json={ "source": "messaging", "request_url": "https://your-tunnel.example.com/webhooks/whatsapp", "name": "whatsapp-fastapi", "format": "json", "events": ["message_received"], }, ) response.raise_for_status() print(response.json())
2. In FastAPI empfangen
Die Nutzlast, die Unipile sendet, enthält den Chat, den Absender und den Nachrichtentext als flache Felder sowie eine Liste von Anhängen, sofern welche vorhanden sind. Modellieren Sie nur, was Sie benötigen; Pydantic ignoriert zusätzliche Felder standardmäßig.
main.py
from typing import List, Optional from fastapi import BackgroundTasks, FastAPI from pydantic import BaseModel app = FastAPI() class Sender(BaseModel): attendee_id: str attendee_name: Optional[str] = None Teilnehmer-Anbieter-ID: str class Attachment(BaseModel): id: str type: str mimetype: Optional[str] = None unavailable: bool = False class WhatsAppMessageEvent(BaseModel): account_id: str account_type: str event: str chat_id: str message_id: str message: Optional[str] = None timestamp: str webhook_name: Optional[str] = None sender: Sender attachments: Liste[Attachment] = [] def handle_message(event: WhatsAppMessageEvent) -> None: if event.account_type != "WHATSAPP" or event.event != "message_received": return # Unipile umfasst Nachrichten, die das verknüpfte Konto selbst gesendet hat – sei es # von einem anderen Gerät oder über Ihre eigenen API-Aufrufe. Vergleichen Sie den Absender # mit dem Kontoinhaber, den Sie bei der Verbindung gespeichert haben, wenn Sie # nur auf Nachrichten reagieren möchten, die von der anderen Seite kommen. print(f"Neue WhatsApp-Nachricht im Chat {event.chat_id}: {event.message}") # Leiten Sie die Nachricht von hier aus an Ihre Warteschlange, Ihre Datenbank oder einen KI-Agenten weiter @app.post("/webhooks/whatsapp") async def whatsapp_webhook( event: WhatsAppMessageEvent, background_tasks: BackgroundTasks, ): background_tasks.add_task(handle_message, event) return {"status": "received"}
Führe es aus mit uvicorn main:app --reload, leiten Sie Ihren Tunnel auf Port 8000 um und registrieren Sie diese öffentliche URL als anfrage_url in Schritt 1. Zurückgeben {"status": "erhalten"} Bevor die Nachricht vollständig verarbeitet ist, ist wichtig: Unipile erwartet eine schnelle Antwort, und Hintergrundprozesse ist was hält Nachricht_verarbeiten vom Blockieren.
Noch etwas, das sich von Anfang an lohnt einzubauen: Speichern Sie jedes verarbeitete Nachrichten-ID Bevor Sie darauf reagieren, und überspringen Sie alles, was Sie bereits gesehen verknüpftes WhatsApp-Konto selbst die Verbindung trennt und wiederherstellt, stellt Unipile die Nachrichten zugestellt, während diese Lücke bestand, sobald es aufholt, und eine erneute Bereitstellung oder ein abgestürzter Hintergrundtask können separat dazu führen, dass Ihr eigener Handler dasselbe Ereignis zweimal sieht, sodass die Behandlung Nachrichten-ID wie ein Idempotenzkey einen WhatsApp-Bot daran hindert, doppelt zu antworten.
Erstelle deinen FastAPI-Webhook
Lesen Sie

Wie ruft man Chats und den Nachrichtenverlauf in Python ab?

Jeder Listenendpunkt in der Unipile-API – Chats, Nachrichten, Teilnehmer – ist auf dieselbe Weise paginiert: Die Antwort enthält einen Artikel Array und ein Cursor. Gib das rüber. Cursor Beim nächsten Anruf wieder da, und stoppt, sobald er zurückkommt null. Von Python während True Loop bildet dieses Muster direkt ab.
Alle WhatsApp-Chats für ein Konto auflisten
list_chats.py
import requests BASE_URL = "https://{YOUR_DSN}/api/v1" HEADERS = {"X-API-KEY": "YOUR_ACCESS_TOKEN"} def list_all_whatsapp_chats(account_id: str) -> list: chats = [] cursor = None while True: params = {"account_id": account_id, "limit": 100} if cursor: params["cursor"] = cursor response = requests.get(f"{BASE_URL}/chats", headers=HEADERS, params=params) response.raise_for_status() page = response.json() chats.extend(page["items"]) cursor = page["cursor"] if not cursor: break return chats for chat in list_all_whatsapp_chats("Yk08cDzzdsqs9_8ds"): print(chat["id"], chat["name"], chat["unread_count"])
Lies den Nachrichtenverlauf und die Teilnehmer eines Chats
Die neuesten Nachrichten werden zuerst zurückgegeben. Verwenden Sie dieselbe Grenze und Cursor Muster zum Rückwärtsblättern in älteren Verlaufsdaten und Aufrufen des Teilnehmer-Endpunkts, wann immer Sie ermitteln müssen, wer sich tatsächlich in einem Chat befindet, sei es einzeln oder in einer Gruppe.
chat_history.py
def get_chat_history(chat_id: str, limit: int = 100) -> list: response = requests.get( f"{BASE_URL}/chats/{chat_id}/messages", headers=HEADERS, params={"limit": limit}, ) response.raise_for_status() return response.json()["items"] def get_chat_attendees(chat_id: str) -> list: response = requests.get( f"{BASE_URL}/chats/{chat_id}/attendees", headers=HEADERS, ) response.raise_for_status() return response.json()["items"] messages = get_chat_history("9f9uio56sopa456s") attendees = get_chat_attendees("9f9uio56sopa456s")
Dies ist auch der Codepfad, den eine CRM-Synchronisierung oder ein Support-Postfach in Python tatsächlich ausführt: Bei einer neuen Verbindung jeden Chat einmal durchgehen mit alle_whatsapp_chats_auflisten um Ihre Datenbank zu füllen und sich dann auf den Webhook aus dem vorherigen Abschnitt zu verlassen, um sie aktuell zu halten, anstatt sie erneut abzufragen. Die GET /chats Endpunkt akzeptiert auch einen ungelesen filtern, damit ein leichterer Job, der nach einem Zeitplan nur ungelesene Chats überprüft, nicht jedes Mal den gesamten Kontoverlauf durchblättern muss.
WhatsApp-Gruppen sind auch Chats, also das Gleiche GET /chats und GET /chats/{chat_id}/attendees ruft sie und ihre Mitglieder aus Python ohne zusätzlichen Code auf. Um einen Teilnehmer hinzuzufügen oder zu entfernen oder den Einladungslink abzurufen, verwenden Sie PATCH /chats/{chat_id} mit einem Teilnehmer hinzufügen, Teilnehmer entfernen, oder Einladungslink abrufen Aktion. Die vollständige Komplettlösung sowie Metas eigene Teilnehmerlimits für die native Groups-API finden Sie im Leitfaden zu WhatsApp-Gruppenteilnehmer hinzufügen oder entfernen.
Automatisierung

Wie baut man einen WhatsApp-Bot oder KI-Agenten in Python?

Jeder WhatsApp-Bot oder KI-Agent folgt denselben drei Schritten: Empfang einer Nachricht über den Webhook, Entscheidung, was damit zu geschehen hat, und Senden einer Antwort über denselben Weg chat_id. An den Schritten eins und drei ändert sich nichts, wenn man ein LLM in die Mitte stellt, weshalb der FastAPI-Handler und der Nachricht senden Funktionen aus den früheren Abschnitten sind bereits der größte Teil des Codes, den Sie benötigen.
agent.py
from openai import OpenAI # oder ein beliebiger LLM-Client, den Sie verwenden llm = OpenAI() _recent_bot_replies: dict = {} def generate_reply(incoming_text: str) -> str: completion = llm.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": "Du bist ein hilfsbereiter WhatsApp-Supportmitarbeiter."}, {"role": "user", "content": incoming_text}, ], ) return completion.choices[0].message.content def handle_message(event: WhatsAppMessageEvent) -> None: if event.account_type != "WHATSAPP" or event.event != "message_received": return if not event.message: return if _recent_bot_replies.get(event.chat_id) == event.message: return # – Echo unserer eigenen letzten Antwort, ignorieren reply_text = generate_reply(event.message) _recent_bot_replies[event.chat_id] = reply_text send_message(event.chat_id, reply_text)
Die _letzte_bot_antworten Schutz ist wichtiger, als es aussieht: Das von Unipile nachricht_erhalten Ereignisse werden auch für Nachrichten ausgelöst, die das verknüpfte Konto sendet, von einem anderen Gerät oder über eigene API-Aufrufe. Ohne eine Schutzmaßnahme kann es also passieren, dass ein Agent auf seine eigene Antwort antwortet. Ein Dictionary reicht für eine Demo völlig aus; ein Agent für die Produktion sollte diesen Status jedoch in Redis oder einer Datenbank zusammen mit dem Konversationsverlauf und einem Idempotenzschlüssel speichern.
Der Webhook-Payload und der Nachricht senden Anrufe sind auf WhatsApp, LinkedIn, Instagram und Telegram genau gleich geformt, nur Kontotyp Änderungen, damit derselbe FastAPI-Handler die Antworten eines Agenten über jeden Kanal leiten kann, den ein Benutzer verbunden hat. Wie man dabei kanalspezifische Tonalität, Formatierung und Rate-Limits richtig handhabt, wird im Leitfaden zum Multi-Channel-API für KI-Agenten.
Erstelle deinen WhatsApp KI-Agenten
Verlässlichkeit

Wie gehen Sie in Python mit Rate Limits und Wiederholungsversuchen um?

Unipile gibt einen JSON-Body mit einem Typ Feld, wie errors/invalid_credentials oder Fehler/getrenntes_konto, wenn eine Anfrage fehlschlägt. Einige davon sind es wert, erneut versucht zu werden, wie eine unterbrochene Verbindung oder ein vorübergehendes Problem beim Anbieter; andere, wie ungültige Anmeldedaten, werden sich nicht von selbst beheben, egal wie oft man es noch einmal versucht. Wie schnell und wie viel Sie von einem einzelnen WhatsApp-Konto senden, bleibt eine Entscheidung auf Kundenseite, geprägt von den Rate-Limits, die WhatsApp selbst für dieses Konto vorschreibt, und keine feste Zahl, die Unipile zusätzlich auferlegt.
Die Hartnäckigkeit Packe das in einen Decorator anstelle einer manuell geschriebenen Schleife. Wickle das Gleiche Nachricht senden Funktion aus dem Sendeabschnitt mit exponentiellem Backoff und einer begrenzten Anzahl von Versuchen:
retry.py
# pip install tenacity import requests from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type @retry( stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=2, max=30), retry=retry_if_exception_type(requests.exceptions.HTTPError), ) def send_message_with_retry(chat_id: str, text: str) -> dict: response = requests.post( f"{BASE_URL}/chats/{chat_id}/messages", headers=HEADERS, data={"text": text}, ) response.raise_for_status() return response.json()
Fünf Versuche mit einem exponentiellen Backoff von 2 bis 30 Sekunden sind ein vernünftiger Standard für einen Hintergrundjob; reduzieren Sie die Anzahl der Versuche für alles, was in einem nutzerseitigen Anfragepfad läuft, da Hartnäckigkeit wird die Anfrage andernfalls während der Wiederholungsversuche offen halten. Derselbe Decorator umschließt die asynchrone Version aus dem Abschnitt zur Nebenläufigkeit, fügen Sie einfach hinzu await wo Hartnäckigkeit unterstützt es durch Asynchrone Wiederholung.
SDK

Gibt es ein offizielles Unipile Python-SDK?

Ja. unipile/unipile-python ist real und wird aktiv gewartet, mit einem Commit von vor Kurzem am 11. August 2026. Zwei Dinge sind erwähnenswert, bevor man danach greift: Es ist noch nicht auf PyPI veröffentlicht und zielt auf Unipiis API v2 ab, die sich noch in der Beta-Forschungsphase befindet, während jeder in diesem Leitfaden verwendete Endpunkt v1 ist.
Aktiv gewartet, nur auf GitHub
Python 3.9+, Pydantic 2.11+
Nicht auf PyPI, von GitHub installieren
Zielt auf die API v2 Beta ab, nicht auf v1
install_sdk.sh
pip install git+https://github.com/unipile/unipile-python.git
sdk_usage.py
import unipile configuration = unipile.Configuration() configuration.api_key["apiKey"] = "YOUR_ACCESS_TOKEN" api_client = unipile.ApiClient(configuration) messaging_api = unipile.MessagingApi(api_client)
Für alles, was dieser Leitfaden heute abdeckt, bauen Sie auf den v1-REST-Endpunkten auf mit Anfragen oder httpxsie sind stabil, dokumentiert und das, worauf jeder obige Codeausschnitt tatsächlich läuft. Sobald das Python-SDK die Betaphase verlässt und auf PyPI veröffentlicht wird, bedeutet die Migration größtenteils das Austauschen von HTTP-Aufrufen gegen typisierte Client-Methoden; die Endpunkte und das zugrunde liegende Connected-Account-Modell ändern sich nicht. Zum Vergleich: Das Node.js-SDK ist dasjenige, auf das derzeit im gesamten Hauptdokumentationsindex von Unipile verwiesen wird, und das ältere PHP-SDK ist seit Oktober 2023 archiviert.
Möchten Sie dieselbe Art von Integration für einen anderen Kanal bauen? Instagram API mit Python Der Anleitung folgt dem identischen Muster aus Verbinden, Senden, Abrufen und Webhook, das in diesem Artikel gezeigt wird.
Beginnen Sie noch heute mit der REST-API

WhatsApp API in Python: FAQ

Klare Antworten zu Bibliotheken, Verbindungen, SDKs und Webhooks für die Erstellung der WhatsApp-API in Python.

Es gibt keine einzelne beste Bibliothek, es kommt darauf an, was Sie bereits haben. Wenn Sie bereits für die Cloud-API von Meta zugelassen sind, WhatsApp Cloud API bietet Ihnen einen Pythonic Wrapper dafür. Wenn Sie die Meta-Business-Verifizierung komplett umgehen und stattdessen WhatsApp-Konten im Namen Ihrer Benutzer verbinden möchten, können Sie die REST-API von Unipile aufrufen mit Anfragen oder httpx deckt WhatsApp neben LinkedIn, Instagram und Telegram über eine einzige Benutzeroberfläche ab. pywhatkit lohnt sich, frühzeitig auszuschließen: Es betreibt WhatsApp Web in einem Browser und keine serverseitige API, weshalb es nicht zu einem Produktions-Backend passt.
Sende eine POST Antrag auf /api/v1/chats/{chat_id}/nachrichten with a text Feld und Ihr X-API-KEY Header, zum Beispiel requests.post(url, headers=headers, data={"text": "Hallo"}). Falls Sie keine haben chat_id doch, POST /api/v1/chats mit einem account_id und des Empfängers attendees_ids erstellt den Chat und sendet die erste Nachricht im selben Aufruf.
Ja. Die Verbindung eines WhatsApp-Kontos über Unipile erfordert lediglich, dass der Kontoinhaber einen QR-Code scannen oder einen Kopplungscode eingeben muss, genau wie bei WhatsApp Web. Es gibt keine Meta Business Platform-Anwendung und keine Telefonnummernverifizierung mit Meta, da die Integration im Namen des authentifizierten Benutzers als über eine registrierte WhatsApp Business-Nummer.
Ja, unipile/unipile-python ist ein aktiv gewartetes offizielles SDK, ist aber noch nicht auf PyPI: Installieren Sie es mit pip install git+https://github.com/unipile/unipile-python.git. Sie zielt auch auf die API v2 von Unipile ab, die sich in der Beta-Phase befindet, während jeder Endpunkt in diesem Leitfaden die stabile v1-API verwendet, sodass die meisten Python-Integrationen heute noch direkt auf Anfragen oder httpx anstelle des SDK.
Anfragen ist einfacher und reicht für Skripte, Cron-Jobs und geringes Versandvolumen aus. httpx lohnt sich der Umstieg, sobald man an zu viele Empfänger gleichzeitig sendet oder einen asynchronen FastAPI-Dienst aufbaut, denn es AsyncClient ermöglicht es Ihnen, mehrere Anfragen gleichzeitig aus derselben Event-Schleife abzufeuern, anstatt bei jeder einzelnen zu blockieren.
Eine FastAPI-App lokal ausführen, sie mit einem Tunnel freigeben wie ngrok oder cloudflared eine öffentliche HTTPS-URL zu erhalten und diese URL als zu registrieren anfrage_url wenn Sie einen Webhook erstellen mit Quelle festlegen auf messaging. Unipile leitet jede neue Nachricht an diese Tunnel-URL weiter, die sie während der Entwicklung direkt an Ihre lokale FastAPI-Route weiterleitet.
Ja. WhatsApp-Gruppen werden als normale Chats angezeigt, deshalb GET /chats und GET /chats/{chat_id}/attendees Listen Sie sie und ihre Mitglieder ohne Sonderbehandlung auf. Um einen Teilnehmer hinzuzufügen, einen zu entfernen oder den Gruppeneinladungslink abzurufen, senden Sie eine PATCH /chats/{chat_id} Anfrage mit einer Teilnehmer hinzufügen, Teilnehmer entfernen, oder Einladungslink abrufen Aktion, ausführlich beschrieben im Leitfaden zu Hinzufügen und Entfernen von WhatsApp-Gruppenmitgliedern.
Die zugrundeliegenden Endpunkte sind identisch, der Unterschied liegt in der Laufzeitumgebung und deren Ökosystem: Python bevorzugt Anfragen oder httpx mit asyncio für Nebenläufigkeit und FastAPI für Webhooks, während PHP-Integrationen typischerweise Guzzle verwenden und sich in eine Laravel-Anwendung mit Warteschlangen-Jobs einfügen. Wenn Ihr Tech-Stack PHP ist, dieselbe Integration in PHP durchläuft jeden äquivalenten Schritt.

Haben Sie noch Fragen? Unser Team ist für Sie da.

Sprechen Sie mit einem Experten
de_DEDE
en_USEN fr_FRFR es_ESES it_ITIT pt_BRBR nl_NLNL pl_PLPL tr_TRTR de_DEDE