InloggenGratis proefperiode starten
Meta Tech Provider

Een WhatsApp AI-agent bouwen in Node.js en Python op een Coexistence-nummer

Ontvang de berichten van het nummer, doorgestuurd met een HMAC-handtekening die je verifieert (X-EC-Signature), of rechtstreeks via de webhook van Meta met een geheim in de URL. Sla daarna elk bericht-id over dat al is verwerkt, blijf stil in een chat waar een echo laat zien dat een persoon vanaf de telefoon heeft geantwoord, en stuur het antwoord van je model via de Cloud API alleen binnen 24 uur na het laatste bericht van de klant.

easyCoexistence verbindt het nummer dat het bedrijf in de WhatsApp Business-app blijft gebruiken met de Cloud API van Meta, geeft je code zijn inloggegevens via get_api_credentials, en routeert berichten rechtstreeks van Meta naar je server of via een ondertekende doorstuur met automations aan.

5 min

Grootste toegestane afwijking tussen de t van de handtekening en je klok; elke nieuwe poging wordt opnieuw ondertekend met een verse t.

10 s

Hoelang een doorgestuurde POST wacht op een 2xx voordat easyCoexistence een nieuwe poging van die aflevering inplant.

7 days

Hoelang Meta een rechtstreekse webhook opnieuw probeert wanneer die geen HTTP 200 kreeg, wat hetzelfde bericht twee keer kan afleveren.

24 hours

Klantenserviceperiode na het laatste bericht van de gebruiker; daarbuiten accepteert Meta alleen template-berichten.

20 mps

Vaste doorvoer van een nummer dat met zowel de WhatsApp Business-app als de Cloud API wordt gebruikt.

Welke route moet een agent in code gebruiken?

Doorgestuurd betekent dat het nummer in de modus Automations blijft staan: Meta levert aan easyCoexistence, automations kunnen nog steeds draaien, en een ondertekende kopie van elke Meta-wijziging gaat naar je Forward URL. Een variant heeft helemaal geen doorstuur nodig: een Call my webhook-stap van een automation POST het bericht naar je endpoint en stuurt wat je als {"reply"} teruggeeft binnen 20 seconden, met dedupe, de telefoonpauze en de 24-uurscontrole al voor je gedaan.

Rechtstreeks betekent dat Meta zijn eigen webhook direct naar je endpoint stuurt, ingesteld met set_webhook_destination, en easyCoexistence de berichten nooit ziet. Automations staan voor dat nummer uit, dus elke controle is aan jou, en ook de import van de geschiedenis van 6 maanden, wanneer de bestemming binnen 24 uur na het verbinden is opgeslagen. De voorbeelden hieronder behandelen alle drie de ingangen met één gedeelde 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

Wat doet de agent met een bericht, in Node.js?

agent.mjs bevat de logica die beide routes delen. Het slaat het tijdstip van het laatste bericht van de klant op, pauzeert 4 uur in een chat wanneer een smb_message_echoes-event laat zien dat iemand vanuit de WhatsApp Business-app heeft geantwoord (wat de standaard easyCoexistence-automations gebruiken), slaat een bericht-id over dat al is verwerkt, en stuurt alleen binnen het 24-uursvenster. Het venster wordt gemeten vanaf de eigen tijdstempel van het bericht, niet vanaf het moment dat het bij jou aankwam, omdat een opnieuw geprobeerde aflevering uren later kan binnenkomen.

Gebruikers worden geïdentificeerd op BSUID (from_user_id, of to_user_id bij echo's) met het telefoonnummer als terugval, en een gebruiker die alleen via BSUID bekend is krijgt het antwoord met recipient in plaats van to. De modelaanroep gebruikt elke OpenAI-compatibele chat completions API; wissel die uit voor de SDK van je provider als je dat liever wilt.

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()}`);
}

Hoe verifieer en routeer je events in Node.js?

server.mjs biedt de drie ingangen. /ec/forward ontvangt de doorgestuurde berichten van beheerde nummers: het controleert X-EC-Signature op de ruwe bytes met het forward-geheim van het nummer, antwoordt met 200 vóór enig werk, en slaat een aflevering-id over die al is geaccepteerd, omdat een nieuwe poging dezelfde id met een verse handtekening draagt. Het event in de body is Meta's veldnaam en value is Meta's change, ongewijzigd. /ec/agent antwoordt op een Call my webhook-stap, ondertekend met het eigen Signing secret van die automation, en zet de geschiedenis om in chatbeurten. /meta/:secret is de rechtstreekse route: die beantwoordt Meta's GET-handshake met de ruwe hub.challenge en accepteert POST's alleen op het geheime pad.

De HMAC-sleutel is het volledige geheim, inclusief het whsec_-voorvoegsel, als UTF-8-tekst. express.raw houdt de bytes intact, en de limiet van 5 MB laat ruimte voor Meta-payloads tot 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);

Hoe ziet dezelfde agent eruit in Python?

Eén Flask-bestand met dezelfde drie routes en dezelfde regels. request.get_data() geeft de ruwe body voor de HMAC, hmac.compare_digest doet de vergelijking in constante tijd, en het werk draait op een achtergrondthread na de 200, zodat noch easyCoexistence noch Meta op je model wacht. Start het met flask --app agent run tijdens het ontwikkelen en achter gunicorn of een andere WSGI-server in productie.

De in-memory set en dictionaries werken voor één proces. Met meerdere workers of instanties verplaats je ze naar Redis of je database, met een set-if-absent-schrijfactie met vervaldatum voor bericht-id's, anders beantwoorden twee workers hetzelfde bericht.

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

Hoe voorkom je dubbele antwoorden?

Dubbele berichten hebben zes veelvoorkomende oorzaken, en de voorbeelden hierboven behandelen de eerste vijf:

  • Nieuwe pogingen van Meta. Een rechtstreekse webhook wordt tot 7 dagen opnieuw geprobeerd na alles behalve HTTP 200; houd een opslag van bericht-id's bij en sla id's over die al zijn verwerkt.
  • Nieuwe pogingen van doorsturen. easyCoexistence probeert een aflevering opnieuw die binnen 10 seconden geen 2xx kreeg, met dezelfde id; sla id's over die al zijn geaccepteerd, en dedupliceer daarna op het bericht-id, omdat een wijziging die Meta opnieuw aflevert onder een nieuwe id opnieuw wordt doorgestuurd.
  • Trage bevestigingen. Antwoord eerst en werk daarna; een handler die op het model wacht, loopt in een time-out en dezelfde event komt terug.
  • Een persoon aan de telefoon. Een smb_message_echoes-event betekent dat iemand vanuit de app heeft geantwoord; blijf een paar uur stil in die chat.
  • Meerdere workers. In-memory sets reiken niet over processen heen; verplaats de opslag naar Redis of je database.
  • Twee antwoordgevers. Een AI-antwoord-automation en je eigen agent op dezelfde chats beantwoorden beide, en je Graph API-verzendingen zijn geen echo's, dus ze pauzeren de automations niet. Kies per nummer één antwoordgever.

Waar komen de geheimen en inloggegevens vandaan?

Uit het dashboard of de MCP-connector, en ze horen alleen in de omgeving van je server. get_api_credentials geeft graph_api_base, waba_id, phone_number_id, send_endpoint en access_token terug, het eigen token van het bedrijf; de pagina van het nummer toont dezelfde waarden onder Plug in your own system. Is access_token null, verbind het nummer dan opnieuw vanaf een computer met Reconnect om een token uit te geven. Behandel het token als een wachtwoord, want wie het heeft kan namens het bedrijf berichten sturen.

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

Veelgemaakte fouten

  • De HMAC controleren op opnieuw geserialiseerde JSON. Pythons json.dumps voegt standaard spaties toe na scheidingstekens, dus een body die is geparsed en opnieuw gedumpt komt niet meer overeen; verifieer de ruwe bytes.
  • Het geheim base64-decoderen of het whsec_-voorvoegsel weglaten. De sleutel is de volledige string als UTF-8-tekst, precies zoals die je eenmaal is getoond.
  • X-Hub-Signature-256 valideren op de rechtstreekse route met je eigen Meta app secret. Meta ondertekent met het app secret van easyCoexistence, dat niet wordt gedeeld, dus echte events falen; authenticeer met het geheim in het pad.
  • De tijd van het venster bepalen aan de hand van de aankomsttijd. Een doorgestuurde aflevering die uren later opnieuw wordt geprobeerd, draagt nog steeds Meta's oorspronkelijke tijdstempel; vergelijk daarmee, anders antwoordt de agent na 24 uur en weigert Meta de verzending.
Dit doen met EasyCoexistence

Elk nummer wordt 24/7 bewaakt, met meldingen wanneer een verbinding wegvalt. Van US$ 9 tot US$ 0.75 per nummer per maand, dalend naarmate je nummers toevoegt, met de eerste 3 dagen gratis.

Veelgestelde vragen

Kan de agent spraakberichten en foto's begrijpen?

Ja, met je eigen code. De payload van Meta bevat het media-id: download het met GET /<media-id> en het token van het nummer, haal de teruggegeven URL op met dezelfde Authorization-header, en transcribeer of beschrijf het daarna met je model. Automations zien alleen placeholders zoals [voice message].

Welke modellen kunnen de voorbeelden gebruiken?

Elk model achter een OpenAI-compatibel chat completions-endpoint, inclusief dat van OpenAI en modellen die via OpenRouter worden bereikt, of vervang askModel en ask_model door de SDK van je provider. easyCoexistence rekent nooit voor AI: je provider factureert je rechtstreeks.

Kan de agent een gesprek starten?

Alleen met een goedgekeurd template, verstuurd met type template naar hetzelfde verzendendpoint. Op een Coexistence-nummer gaan templates alleen via de API uit, nooit vanuit de telefoon-app, en Meta factureert ze per bericht aan het eigen WhatsApp Business Account van het bedrijf.

Bedient één agent meerdere nummers?

Ja. Routeer op value.metadata.phone_number_id of connection.phone_number_id, en houd per nummer een verzend-endpoint, een token en een forward-geheim bij, omdat elk nummer het zijne heeft.

Lees verder

Klaar om te beginnen?

Stel WhatsApp Coexistence in enkele minuten in, niet maanden. De app blijft op je telefoon werken.

Start je gratis proefperiode

Geverifieerd op