AnmeldenKostenlose Testphase starten
Meta Tech Provider

Einen WhatsApp-KI-Agenten in Node.js und Python auf einer Coexistence-Nummer bauen

Empfangen Sie die Nachrichten der Nummer entweder weitergeleitet mit einer HMAC-Signatur, die Sie prüfen (X-EC-Signature), oder direkt über den Webhook von Meta mit einem Secret in der URL. Überspringen Sie danach jede Nachrichten-ID, die bereits verarbeitet wurde, schweigen Sie in einem Chat, in dem ein Echo zeigt, dass eine Person vom Telefon aus geantwortet hat, und senden Sie die Antwort Ihres Modells über die Cloud API nur innerhalb von 24 Stunden nach der letzten Nachricht des Kunden.

easyCoexistence verbindet die Nummer, die das Unternehmen weiterhin in der WhatsApp-Business-App nutzt, mit der Cloud API von Meta.

5 min

Größte zulässige Abweichung zwischen dem t der Signatur und Ihrer Uhr; jeder Wiederholungsversuch wird mit einem neuen t erneut signiert.

10 s

Wie lange ein weitergeleiteter POST auf ein 2xx wartet, bevor easyCoexistence einen erneuten Versuch dieser Zustellung plant.

7 days

Wie lange Meta einen direkten Webhook wiederholt, der kein HTTP 200 erhalten hat; dabei kann dieselbe Nachricht zweimal ankommen.

24 hours

Kundenservice-Fenster nach der letzten Nachricht des Nutzers; außerhalb davon nimmt Meta nur Vorlagennachrichten an.

20 mps

Feste Durchsatzrate einer Nummer, die sowohl mit der WhatsApp-Business-App als auch mit der Cloud API genutzt wird.

Welchen Weg sollte ein programmierter Agent nutzen?

Weitergeleitet bedeutet, dass die Nummer im Modus Automations bleibt: Meta liefert an easyCoexistence, Automations können weiterhin laufen, und eine signierte Kopie jeder Änderung von Meta geht an Ihre Forward URL. Eine Variante benötigt gar keine Weiterleitung: Ein Schritt Call my webhook sendet die Nachricht per POST an Ihren Endpoint und übermittelt jede Antwort {"reply"}, die Sie innerhalb von 20 Sekunden zurückgeben. Deduplizierung, Telefonpause und 24-Stunden-Prüfung übernimmt dabei easyCoexistence.

Direkt bedeutet, dass Meta seinen eigenen Webhook an Ihren Endpoint sendet, eingerichtet mit set_webhook_destination, und easyCoexistence die Nachrichten nie sieht. Die Automations sind für diese Nummer deaktiviert, daher liegen alle Schutzmechanismen bei Ihnen, ebenso der 6-Monats-Verlaufsimport, sofern das Ziel innerhalb von 24 Stunden nach der Verbindung gespeichert wird. Die Beispiele unten behandeln alle drei Einstiegspunkte mit einem gemeinsamen Kern.

Forwarded, signedDirect from Meta
Number modeAutomations on (managed)Direct to your server
BodyOne Meta change: id, event, received_at, connection, valueMeta's envelope: object, entry, changes
AuthenticationX-EC-Signature, HMAC-SHA256 with a per-number secretA secret in the URL path
AcknowledgeAny 2xx within 10 secondsHTTP 200; Meta retries other codes
Retries7 attempts over about 33 hoursUp to 7 days
ReplyGraph API, or {"reply"} to a Call my webhook stepGraph API
History importNot requestedRequested if saved within 24 hours of connecting

Was macht der Agent mit einer Nachricht in Node.js?

agent.mjs enthält die Logik, die beide Wege teilen. Der Agent speichert den Zeitpunkt der letzten Kundennachricht und pausiert vier Stunden lang in einem Chat, sobald ein smb_message_echoes-Ereignis zeigt, dass jemand aus der WhatsApp-Business-App geantwortet hat (das nutzen die Standard-Automations von easyCoexistence). Er überspringt eine Nachrichten-ID, die bereits verarbeitet wurde, und sendet nur innerhalb des 24-Stunden-Fensters. Das Fenster wird ab dem eigenen Zeitstempel der Nachricht gemessen, nicht ab dem Moment, in dem sie bei Ihnen ankam, denn eine wiederholte Zustellung kann Stunden später eintreffen.

Nutzer werden über die BSUID identifiziert (from_user_id bzw. to_user_id bei Echos), mit der Telefonnummer als Fallback. Ein Nutzer, der nur über die BSUID bekannt ist, wird mit recipient statt to angesprochen. Der Modellaufruf funktioniert mit jeder OpenAI-kompatiblen Chat-Completions-API; ersetzen Sie sie durch das SDK Ihres Anbieters, falls Sie das bevorzugen.

agent.mjs: the shared logic
// agent.mjs: what the agent does with one Meta change, whichever route brought it.
const DAY = 24 * 3600 * 1000;
const PAUSE = 4 * 3600 * 1000;   // quiet time after a person replies (automations default to 4 h)
const seen = new Set();          // handled ids: use Redis or your database in production
const lastInbound = new Map();   // user -> ms of their last message
const quietUntil = new Map();    // user -> ms until which a person has the chat

export function firstTime(id) {
  if (seen.has(id)) return false;
  seen.add(id);
  return true;
}

export async function handleChange(field, value) {
  if (field === "smb_message_echoes") {
    // Someone answered from the WhatsApp Business app: step back on that chat.
    for (const e of value.message_echoes ?? []) {
      quietUntil.set(e.to_user_id ?? e.to, Number(e.timestamp) * 1000 + PAUSE);
    }
    return;
  }
  if (field !== "messages") return;              // statuses ride in value.statuses: ignored here
  for (const m of value.messages ?? []) {
    if (!firstTime(m.id)) continue;               // Meta delivered this message before
    const user = m.from_user_id ?? m.from;        // BSUID first, phone number as fallback
    lastInbound.set(user, Math.max(Number(m.timestamp) * 1000, lastInbound.get(user) ?? 0));
    if ((quietUntil.get(user) ?? 0) > Date.now()) continue; // a person has this chat
    if (m.type !== "text") continue;              // media: fetch it by id first (see the FAQ)
    const reply = await askModel([{ role: "user", content: m.text.body }]);
    if (!reply) continue;
    if (Date.now() - lastInbound.get(user) >= DAY) continue; // window closed: template only
    await sendText({ phone: m.from, bsuid: m.from_user_id }, reply);
  }
}

// Any OpenAI-compatible chat completions API (OpenAI, OpenRouter...).
export async function askModel(turns) {
  const res = await fetch(`${process.env.AI_BASE_URL}/chat/completions`, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.AI_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      model: process.env.AI_MODEL,
      messages: [{ role: "system", content: process.env.AI_INSTRUCTIONS ?? "Answer briefly." }, ...turns],
    }),
  });
  if (!res.ok) throw new Error(`AI provider answered ${res.status}`);
  const data = await res.json();
  return data.choices?.[0]?.message?.content?.trim() ?? "";
}

// send_endpoint and access_token come from get_api_credentials.
async function sendText({ phone, bsuid }, text) {
  const res = await fetch(process.env.SEND_ENDPOINT, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.WA_TOKEN}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      messaging_product: "whatsapp",
      recipient_type: "individual",
      ...(phone ? { to: phone } : { recipient: bsuid }), // a BSUID-only user gets recipient
      type: "text",
      text: { body: text.slice(0, 4096) },
    }),
  });
  if (!res.ok) throw new Error(`Graph API answered ${res.status}: ${await res.text()}`);
}

Wie verifizieren und leiten Sie Ereignisse in Node.js?

server.mjs stellt die drei Einstiegspunkte bereit. /ec/forward nimmt die Weiterleitungen einer verwalteten Nummer entgegen: Die Route prüft X-EC-Signature auf den Rohbytes mit dem Forward-Secret der Nummer, antwortet mit 200, bevor irgendeine Arbeit beginnt, und überspringt eine Zustell-ID, die bereits akzeptiert wurde, denn ein Wiederholungsversuch trägt dieselbe ID mit neuer Signatur. Das Feld event im Body ist Metas Feldname, und value ist Metas change, unverändert. /ec/agent beantwortet einen Schritt Call my webhook, signiert mit dem eigenen Signing secret dieser Automation, und wandelt den Verlauf in Chat-Turns um. /meta/:secret ist die direkte Route: Sie beantwortet Metas GET-Handshake mit dem unveränderten hub.challenge und akzeptiert POSTs nur auf dem Secret-Pfad.

Der HMAC-Schlüssel ist das vollständige Secret, einschließlich des Präfixes whsec_, als UTF-8-Text. express.raw bewahrt die Bytes unverändert, und das 5-MB-Limit lässt Raum für Meta-Payloads von bis zu 3 MB.

server.mjs: verification and routes (Express)
// server.mjs: Node 18+, npm i express, then node server.mjs
import crypto from "node:crypto";
import express from "express";
import { askModel, firstTime, handleChange } from "./agent.mjs";

const app = express();

// X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, keyed with the whole secret.
export function verifyEc(raw, header, secret, toleranceSec = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
  if (!m || !Buffer.isBuffer(raw) || !secret) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false; // stale or replayed
  const expected = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
  return crypto.timingSafeEqual(expected, Buffer.from(m[2], "hex"));
}

function sameSecret(a, b) {
  const x = Buffer.from(String(a)), y = Buffer.from(String(b ?? ""));
  return x.length === y.length && crypto.timingSafeEqual(x, y);
}

// Route A, forwarded: a managed number's Forward URL. One Meta change per POST.
app.post("/ec/forward", express.raw({ type: "*/*", limit: "5mb" }), (req, res) => {
  if (!verifyEc(req.body, req.get("X-EC-Signature"), process.env.EC_FORWARD_SECRET)) return res.sendStatus(401);
  res.sendStatus(200);                                   // acknowledge inside 10 s, then work
  const d = JSON.parse(req.body.toString("utf8"));
  if (!firstTime(`delivery:${d.id}`)) return;            // a retry of a delivery already taken
  handleChange(d.event, d.value).catch(console.error);   // d.event is the Meta field name
});

// Route A, synchronous: a "Call my webhook" step. Answer {"reply"} within 20 s.
app.post("/ec/agent", express.raw({ type: "*/*", limit: "1mb" }), async (req, res) => {
  if (!verifyEc(req.body, req.get("X-EC-Signature"), process.env.EC_AUTOMATION_SECRET)) return res.sendStatus(401);
  const step = JSON.parse(req.body.toString("utf8"));
  const turns = step.history.map((h) => ({ role: h.direction === "in" ? "user" : "assistant", content: h.text }));
  while (turns[0]?.role === "assistant") turns.shift();
  if (!turns.length) turns.push({ role: "user", content: step.message?.text ?? "" }); // tests carry no history
  res.json({ reply: await askModel(turns) });            // step.dry_run is true on "Test it"
});

// Route B, direct: Meta's own envelope. The secret path is the credential.
app.get("/meta/:secret", (req, res) => {
  if (!sameSecret(req.params.secret, process.env.PATH_SECRET)) return res.sendStatus(404);
  if (req.query["hub.mode"] === "subscribe" && req.query["hub.verify_token"] === process.env.VERIFY_TOKEN) {
    return res.type("text/plain").send(String(req.query["hub.challenge"]));
  }
  res.sendStatus(403);
});

app.post("/meta/:secret", express.json({ limit: "5mb" }), (req, res) => {
  if (!sameSecret(req.params.secret, process.env.PATH_SECRET)) return res.sendStatus(404);
  res.sendStatus(200);                                   // Meta retries anything but 200
  for (const entry of req.body.entry ?? []) {
    for (const change of entry.changes ?? []) handleChange(change.field, change.value).catch(console.error);
  }
});

app.listen(process.env.PORT ?? 3000);

Wie sieht derselbe Agent in Python aus?

Eine Flask-Datei mit denselben drei Routen und denselben Regeln. request.get_data() liefert den Rohtext für die HMAC, hmac.compare_digest führt den zeitkonstanten Vergleich aus, und die Arbeit läuft nach der 200-Antwort in einem Hintergrund-Thread, sodass weder easyCoexistence noch Meta auf Ihr Modell warten. Starten Sie sie während der Entwicklung mit flask --app agent run und im Produktivbetrieb hinter gunicorn oder einem anderen WSGI-Server.

Das In-Memory-Set und die Dictionaries eignen sich für einen einzelnen Prozess. Bei mehreren Workern oder Instanzen verschieben Sie sie in Redis oder Ihre Datenbank. Für Nachrichten-IDs verwenden Sie einen Set-if-absent-Schreibvorgang mit Ablaufzeit, sonst beantworten zwei Worker dieselbe Nachricht.

agent.py: the whole agent (Flask)
# agent.py: pip install flask requests, then flask --app agent run
import hashlib, hmac, json, os, re, threading, time
import requests
from flask import Flask, abort, request

app = Flask(__name__)
DAY, PAUSE = 24 * 3600, 4 * 3600
seen, last_inbound, quiet_until = set(), {}, {}  # use Redis or a database in production
lock = threading.Lock()

def verify_ec(raw: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    m = re.fullmatch(r"t=([0-9]+),v1=([0-9a-f]{64})", (header or "").strip())
    if not m or not secret or abs(time.time() - int(m[1])) > tolerance:
        return False
    expected = hmac.new(secret.encode(), m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, m[2])

def first_time(key: str) -> bool:
    with lock:
        if key in seen:
            return False
        seen.add(key)
        return True

def ask_model(turns: list) -> str:  # any OpenAI-compatible chat completions API
    r = requests.post(f"{os.environ['AI_BASE_URL']}/chat/completions", timeout=30,
                      headers={"Authorization": f"Bearer {os.environ['AI_KEY']}"},
                      json={"model": os.environ["AI_MODEL"], "messages": [
                          {"role": "system", "content": os.environ.get("AI_INSTRUCTIONS", "Answer briefly.")}, *turns]})
    r.raise_for_status()
    return (r.json()["choices"][0]["message"]["content"] or "").strip()

def send_text(phone, bsuid, text: str) -> None:  # SEND_ENDPOINT and WA_TOKEN: get_api_credentials
    to = {"to": phone} if phone else {"recipient": bsuid}
    r = requests.post(os.environ["SEND_ENDPOINT"], timeout=15,
                      headers={"Authorization": f"Bearer {os.environ['WA_TOKEN']}"},
                      json={"messaging_product": "whatsapp", "recipient_type": "individual", **to,
                            "type": "text", "text": {"body": text[:4096]}})
    r.raise_for_status()

def handle_change(field: str, value: dict) -> None:
    if field == "smb_message_echoes":  # a person answered from the app: step back
        for e in value.get("message_echoes", []):
            quiet_until[e.get("to_user_id") or e.get("to")] = int(e["timestamp"]) + PAUSE
        return
    if field != "messages":
        return
    for m in value.get("messages", []):
        if not first_time(m["id"]):  # Meta delivered this message before
            continue
        user = m.get("from_user_id") or m.get("from")
        last_inbound[user] = max(int(m["timestamp"]), last_inbound.get(user, 0))
        if quiet_until.get(user, 0) > time.time() or m.get("type") != "text":
            continue
        reply = ask_model([{"role": "user", "content": m["text"]["body"]}])
        if reply and time.time() - last_inbound[user] < DAY:  # past 24 h: template only
            send_text(m.get("from"), m.get("from_user_id"), reply)

def later(field, value):
    threading.Thread(target=handle_change, args=(field, value), daemon=True).start()

@app.post("/ec/forward")  # route A: a managed number's Forward URL
def forward():
    raw = request.get_data()
    if not verify_ec(raw, request.headers.get("X-EC-Signature", ""), os.environ["EC_FORWARD_SECRET"]):
        abort(401)
    d = json.loads(raw)
    if first_time("delivery:" + d["id"]):  # skip retries of a delivery already taken
        later(d["event"], d["value"])
    return "", 200

@app.post("/ec/agent")  # route A: a "Call my webhook" step, answer within 20 s
def agent_step():
    raw = request.get_data()
    if not verify_ec(raw, request.headers.get("X-EC-Signature", ""), os.environ["EC_AUTOMATION_SECRET"]):
        abort(401)
    step = json.loads(raw)
    turns = [{"role": "user" if h["direction"] == "in" else "assistant", "content": h["text"]}
             for h in step["history"]]
    while turns and turns[0]["role"] == "assistant":
        turns.pop(0)
    turns = turns or [{"role": "user", "content": step["message"]["text"] or ""}]
    return {"reply": ask_model(turns)}

@app.get("/meta/<secret>")  # route B: Meta's GET handshake
def meta_handshake(secret):
    if not hmac.compare_digest(secret.encode(), os.environ["PATH_SECRET"].encode()):
        abort(404)
    if (request.args.get("hub.mode") == "subscribe"
            and request.args.get("hub.verify_token") == os.environ["VERIFY_TOKEN"]):
        return request.args.get("hub.challenge", ""), 200, {"Content-Type": "text/plain"}
    abort(403)

@app.post("/meta/<secret>")  # route B: Meta's envelope, straight from Meta
def meta_events(secret):
    if not hmac.compare_digest(secret.encode(), os.environ["PATH_SECRET"].encode()):
        abort(404)
    for entry in (request.get_json(silent=True) or {}).get("entry", []):
        for change in entry.get("changes", []):
            later(change.get("field"), change.get("value", {}))
    return "", 200

Wie vermeiden Sie doppelte Antworten?

Duplikate haben sechs häufige Ursachen; die Beispiele oben behandeln die ersten fünf:

  • Wiederholungen durch Meta. Ein direkter Webhook wird bis zu 7 Tage lang wiederholt, sobald etwas anderes als HTTP 200 zurückkommt. Führen Sie einen Speicher mit Nachrichten-IDs und überspringen Sie IDs, die bereits verarbeitet wurden.
  • Wiederholungen der Weiterleitung. easyCoexistence wiederholt eine Zustellung, die innerhalb von 10 Sekunden keine 2xx-Antwort erhielt, mit derselben ID. Überspringen Sie bereits akzeptierte IDs und deduplizieren Sie danach über die Nachrichten-ID, denn eine Änderung, die Meta erneut zustellt, wird unter einer neuen ID weitergeleitet.
  • Langsame Bestätigungen. Antworten Sie zuerst und arbeiten Sie danach. Ein Handler, der auf das Modell wartet, läuft in ein Timeout, und dasselbe Ereignis kommt zurück.
  • Eine Person am Telefon. Ein smb_message_echoes-Ereignis bedeutet, dass jemand aus der App geantwortet hat. Bleiben Sie in diesem Chat einige Stunden still.
  • Mehrere Worker. In-Memory-Sets reichen nicht über Prozesse hinweg. Verschieben Sie die Speicher in Redis oder Ihre Datenbank.
  • Zwei Antwortende. Eine KI-Antwort-Automation und Ihr eigener Agent antworten im selben Chat beide. Ihre Graph-API-Sendungen gelten nicht als Echos und pausieren daher keine Automations. Wählen Sie je Nummer genau einen Antwortenden.

Woher stammen die Secrets und Zugangsdaten?

Aus dem Dashboard oder dem MCP-Connector; sie gehören ausschließlich in die Umgebung Ihres Servers. get_api_credentials liefert graph_api_base, waba_id, phone_number_id, send_endpoint und access_token, also das eigene Token des Unternehmens. Die Seite der Nummer zeigt dieselben Werte unter Plug in your own system. Ist access_token null, verbinden Sie die Nummer an einem Computer über Reconnect neu, um ein Token auszustellen. Behandeln Sie das Token wie ein Passwort, denn wer es besitzt, kann im Namen des Unternehmens Nachrichten senden.

EC_FORWARD_SECRETShown once when you save a Forward URL, or returned once by set_inbound_mode; New secret rotates it
EC_AUTOMATION_SECRETSigning secret on the automation's page, under its Call my webhook step
SEND_ENDPOINT, WA_TOKENsend_endpoint and access_token from get_api_credentials
PATH_SECRET, VERIFY_TOKENDirect route: 32 or more random characters in the URL, and the handshake token you chose
AI_BASE_URL, AI_KEY, AI_MODELAny OpenAI-compatible API, such as https://api.openai.com/v1 or https://openrouter.ai/api/v1

Häufige Fehler

  • Die HMAC-Prüfung auf erneut serialisiertem JSON. Pythons json.dumps fügt standardmäßig Leerzeichen nach den Trennzeichen ein, daher stimmt ein Body, der erneut geparst und ausgegeben wird, nicht mehr überein. Prüfen Sie die Rohbytes.
  • Das Secret wird Base64-dekodiert oder das Präfix whsec_ entfernt. Der Schlüssel ist der vollständige String als UTF-8-Text, genau so, wie er Ihnen einmal angezeigt wurde.
  • X-Hub-Signature-256 wird auf der direkten Route mit Ihrem eigenen Meta-App-Secret geprüft. Meta signiert jedoch mit dem App-Secret von easyCoexistence, das nicht geteilt wird, daher schlagen echte Ereignisse fehl. Authentifizieren Sie stattdessen mit dem Secret im Pfad.
  • Das Zeitfenster wird ab dem Ankunftszeitpunkt berechnet. Eine Weiterleitung, die Stunden später wiederholt wird, trägt weiterhin Metas ursprünglichen Zeitstempel. Vergleichen Sie damit, sonst antwortet der Agent nach 24 Stunden und Meta lehnt die Sendung ab.
Mit EasyCoexistence

Ihrem Code stellt es die Zugangsdaten über get_api_credentials bereit, und Nachrichten leitet es direkt von Meta an Ihren Server oder über eine signierte Weiterleitung mit aktiven Automations weiter. Jede Nummer wird rund um die Uhr überwacht, mit Warnungen bei Verbindungsabbrüchen. Von US$ 9 bis hinunter zu US$ 0.75 pro Nummer und Monat, sinkend mit jeder weiteren Nummer, die ersten 3 Tage kostenlos.

Häufig gestellte Fragen

Kann der Agent Sprachnachrichten und Fotos verstehen?

Ja, mit Ihrem eigenen Code. Metas Payload enthält die Medien-ID: Laden Sie die Datei mit GET /<media-id> und dem Token der Nummer herunter, rufen Sie die zurückgegebene URL mit demselben Authorization-Header ab und transkribieren oder beschreiben Sie den Inhalt dann mit Ihrem Modell. Automations sehen nur Platzhalter wie [voice message].

Welche Modelle können die Beispiele nutzen?

Jedes Modell hinter einem OpenAI-kompatiblen Chat-Completions-Endpoint, einschließlich der Modelle von OpenAI und jener, die über OpenRouter erreichbar sind. Alternativ ersetzen Sie askModel bzw. ask_model durch das SDK Ihres Anbieters. easyCoexistence stellt niemals KI-Kosten in Rechnung: Ihr Anbieter rechnet direkt mit Ihnen ab.

Kann der Agent eine Unterhaltung beginnen?

Nur mit einer genehmigten Vorlage, gesendet als type template an denselben Send-Endpoint. Auf einer Coexistence-Nummer werden Vorlagen ausschließlich über die API gesendet, niemals aus der Telefon-App, und Meta berechnet sie pro Nachricht dem eigenen WhatsApp-Business-Konto des Unternehmens.

Bedient ein Agent mehrere Nummern?

Ja. Leiten Sie nach value.metadata.phone_number_id oder connection.phone_number_id, und halten Sie für jede Nummer einen Send-Endpoint, ein Token und ein Forward-Secret bereit, da jede Nummer ihre eigenen besitzt.

Weiterlesen

Bereit für den Start?

Richten Sie WhatsApp Coexistence in wenigen Minuten statt Monaten ein. Die App funktioniert weiterhin auf dem Telefon.

Kostenlose Testphase starten

Verifiziert am