Tutorials

Hermes Agent mit WhatsApp verbinden: Schritt-für-Schritt-Anleitung

Melden

Diese Anleitung führt Sie durch den Prozess, einen Hermes Agent (basierend auf der Nous-Hermes-Modellfamilie oder einem Hermes-Agentic-Framework) mit WhatsApp zu verknüpfen. Dadurch kann Ihr KI-Agent direkt auf WhatsApp-Nachrichten reagieren, Aufgaben ausführen und als persönlicher oder geschäftlicher Assistent fungieren.

In diesem Tutorial nutzen wir die offizielle Meta WhatsApp Cloud API in Kombination mit einem Python-Backend, das Anfragen an den Hermes Agent weiterleitet.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes bereitgestellt haben:

  1. Meta for Developers Account: Ein Entwicklerkonto bei developers.facebook.com.
  2. Hermes Agent: Ein lokal laufendes Modell (z. B. via Ollama/vLLM) oder Zugriff über eine Inferenz-API (z. B. Together AI, Fireworks oder OpenRouter).
  3. Python 3.10+ auf Ihrem Server oder Entwicklungsrechner.
  4. Ein Tunneling-Tool: Z. B. ngrok, um Ihre lokale Umgebung mit WhatsApp zu verbinden (für Produktion: ein vServer mit SSL-Zertifikat).

Schritt 1: WhatsApp Business API einrichten

  1. Melden Sie sich im Meta for Developers Portal an.
  2. Klicken Sie auf App erstellen und wählen Sie als Typ Business.
  3. Geben Sie der App einen Namen und scrollen Sie im Dashboard zum Produkt WhatsApp. Klicken Sie auf Einrichten.
  4. Sie erhalten Zugriff auf ein temporäres Test-Dashboard. Notieren Sie sich folgende Daten:
    • Temporäres Zugriffstoken (Temporary Access Token)
    • Telefonnummern-ID (Phone Number ID)
    • Fügen Sie Ihre private Mobilnummer als Empfängernummer zum Testen hinzu.

Schritt 2: Hermes Agent bereitstellen

Für dieses Tutorial nutzen wir Ollama, um ein Nous-Hermes-Modell lokal laufen zu lassen (alternativ können Sie jedes API-basierte Hermes-Setup nutzen).

  1. Installieren Sie Ollama und laden Sie das Hermes-Modell herunter:
    ollama run nous-hermes2
  2. Das Modell läuft nun lokal und ist standardmäßig unter http://localhost:11434 erreichbar.

Schritt 3: Webhook-Server mit Python erstellen

Der Webhook fungiert als Brücke: Er empfängt Nachrichten von WhatsApp, leitet sie an den Hermes Agent weiter und sendet die generierte Antwort zurück an den Nutzer.

  1. Installieren Sie die nötigen Python-Pakete:

    pip install fastapi uvicorn requests httpx

  2. Erstellen Sie eine Datei namens hermes_whatsapp.py:

import httpx
import requests
from fastapi import FastAPI, HTTPException, Query, Request

app = FastAPI()

# KONFIGURATION (Ersetzen Sie diese durch Ihre Meta-Daten)
WHATSAPP_TOKEN = "IHR_META_ACCESS_TOKEN"
PHONE_NUMBER_ID = "IHRE_PHONE_NUMBER_ID"
VERIFY_TOKEN = (
    "MEIN_GEHEIMER_VERIFY_TOKEN"  # Frei wählbar (z.B. "hermes_secret_123")
)
HERMES_API_URL = "http://localhost:11434/api/generate"  # Ollama Endpunkt

# 1. WhatsApp Webhook-Verifizierung (GET)


@app.get("/webhook")
async def verify_webhook(
    mode: str = Query(None, alias="hub.mode"),
    token: str = Query(None, alias="hub.verify_token"),
    challenge: str = Query(None, alias="hub.challenge"),
):
    if mode == "subscribe" and token == VERIFY_TOKEN:
        return int(challenge)
    raise HTTPException(status_code=403, detail="Verifizierung fehlgeschlagen")


# 2. Nachrichten empfangen & antworten (POST)


@app.post("/webhook")
async def receive_whatsapp(request: Request):
    data = await request.json()

    try:
        # Prüfen, ob eine Textnachricht vorliegt
        entry = data["entry"][0]["changes"][0]["value"]
        if "messages" in entry:
            message = entry["messages"][0]
            from_number = message["from"]  # WhatsApp-Nummer des Nutzers
            user_text = message["text"]["body"]

            # Anfrage an Hermes Agent senden
            hermes_reply = ask_hermes(user_text)

            # Antwort via WhatsApp zurücksenden
            send_whatsapp_message(from_number, hermes_reply)

    except (KeyError, IndexError):
        # Benachrichtigungen wie "Status gelesen" ignorieren
        pass

    return {"status": "ok"}


def ask_hermes(prompt: str) -> str:
    """Interaktion mit dem Hermes Agent."""
    payload = {
        "model": "nous-hermes2",
        "prompt": f"System: Du bist ein nützlicher WhatsApp-KI-Assistent, angetrieben von Hermes.\nUser: {prompt}\nAssistant:",
        "stream": False,
    }
    response = requests.post(HERMES_API_URL, json=payload)
    return response.json().get("response", "Entschuldigung, ein Fehler trat auf.")


def send_whatsapp_message(to_number: str, text: str):
    """Nachricht über Meta Graph API senden."""
    url = f"https://graph.facebook.com/v18.0/{PHONE_NUMBER_ID}/messages"
    headers = {
        "Authorization": f"Bearer {WHATSAPP_TOKEN}",
        "Content-Type": "application/json",
    }
    payload = {
        "messaging_product": "whatsapp",
        "to": to_number,
        "type": "text",
        "text": {"body": text},
    }
    requests.post(url, headers=headers, json=payload)

Schritt 4: Server öffentlich erreichbar machen & Webhook konfigurieren

WhatsApp muss Ihren Server über eine öffentlich erreichbare HTTPS-Adresse erreichen können.

  1. Server starten:

    uvicorn hermes_whatsapp:app --host 0.0.0.0 --port 8000

  2. Tunneling via ngrok starten (in einem zweiten Terminal):

    ngrok http 8000

    Kopieren Sie die generierte HTTPS-URL (z. B. https://a1b2-c3d4.ngrok-free.app).

  3. Webhook bei Meta hinterlegen:

    • Gehen Sie in Ihrem Meta App-Dashboard zu WhatsApp > Konfiguration.
    • Klicken Sie bei Webhook auf Bearbeiten.
    • Callback-URL: Fügen Sie Ihre URL mit /webhook ein (z. B. https://a1b2-c3d4.ngrok-free.app/webhook).
    • Verifizierungstoken: Tragen Sie denselben Token ein, den Sie im Python-Skript gewählt haben (z. B. hermes_secret_123).
    • Klicken Sie auf Verifizieren und speichern.
    • Klicken Sie auf Webhook-Felder verwalten und abonnieren Sie das Feld messages.

Schritt 5: Verbindung testen

  1. Nehmen Sie das Telefon zur Hand, dessen Nummer Sie in Schritt 1 als Testnummer autorisiert haben.
  2. Senden Sie eine WhatsApp-Nachricht an die temporäre Telefonnummer von Meta.
  3. Ergebnis:
    • Die Nachricht landet im Python-Webhook.
    • Der Server übergibt die Eingabe an den Hermes Agent.
    • Hermes verarbeitet den Prompt und sendet die Antwort innerhalb von Sekunden per WhatsApp zurück.

Wichtige Hinweise für den Produktivbetrieb

  • Persistente Tokens: Das Meta-Testtoken läuft nach 24 Stunden ab. Für den Live-Betrieb müssen Sie im Meta Business Manager ein System-Benutzer-Token (Permanent Token) anlegen.
  • Hosting: Nutzen Sie für den Produktiveinsatz keinen temporären Tunnel (wie ngrok), sondern hosten Sie das Skript auf einem Server (z. B. via Docker, AWS, Hetzner) mit einer festen Domain und SSL-Zertifikat (z. B. via Let’s Encrypt).
  • Konversationsverlauf (Memory): Das gezeigte Minimal-Skript ist "stateless". Um dem Agenten ein Gedächtnis zu geben, sollten Sie eine Datenbank (z. B. Redis oder SQLite) anbinden, die Chat-Verläufe anhand der from_number speichert und als Kontext an Hermes übergibt.
0