MasukMulai uji coba gratis
Meta Tech Provider

Membangun agen AI WhatsApp di Node.js dan Python pada nomor Coexistence

Terima pesan dari nomor itu, baik yang diteruskan dengan tanda tangan HMAC yang Anda verifikasi (X-EC-Signature) maupun langsung dari webhook Meta dengan rahasia di URL. Lalu lewati ID pesan yang sudah ditangani, diam pada chat yang echo-nya menunjukkan ada orang membalas dari ponsel, dan kirim jawaban model Anda lewat Cloud API hanya dalam 24 jam sejak pesan terakhir pelanggan.

easyCoexistence menghubungkan nomor yang terus dipakai bisnis di aplikasi WhatsApp Business ke Cloud API Meta, memberi kode Anda kredensialnya lewat get_api_credentials, dan merutekan pesan langsung dari Meta ke server Anda atau lewat forward bertanda tangan dengan mode otomasi aktif.

5 min

Selisih terbesar yang diterima antara t pada tanda tangan dan jam Anda; setiap percobaan ulang ditandatangani lagi dengan t yang baru.

10 s

Berapa lama POST yang diteruskan menunggu respons 2xx sebelum easyCoexistence menjadwalkan percobaan ulang pengiriman tersebut.

7 days

Berapa lama Meta mencoba kembali webhook langsung yang tidak menerima HTTP 200, yang bisa mengirim pesan yang sama dua kali.

24 hours

Jendela layanan pelanggan setelah pesan terakhir pengguna; di luar jendela itu, Meta hanya menerima pesan template.

20 mps

Throughput tetap untuk nomor yang dipakai bersama aplikasi WhatsApp Business dan Cloud API.

Jalur mana yang sebaiknya dipakai agen berbasis kode?

Diteruskan berarti nomor tetap di mode otomasi aktif: Meta mengirim ke easyCoexistence, otomasi tetap bisa berjalan, dan salinan bertanda tangan dari setiap perubahan Meta dikirim ke URL Forward Anda. Varian lain tidak memerlukan forward sama sekali: langkah otomasi 'Call my webhook' mengirim POST pesan ke endpoint Anda dan mengirim balasan apa pun yang Anda kembalikan dalam bentuk {"reply"} dalam 20 detik, dengan deduplikasi, jeda saat ponsel dipakai, dan cek 24 jam dilakukan untuk Anda.

Langsung berarti Meta mengirim webhook-nya sendiri langsung ke endpoint Anda, diatur dengan set_webhook_destination, dan easyCoexistence tidak pernah melihat pesannya. Otomasi dimatikan untuk nomor itu, sehingga semua pengaman menjadi tanggung jawab Anda, begitu pula impor riwayat 6 bulan saat tujuan disimpan dalam 24 jam setelah terhubung. Contoh di bawah menangani ketiga titik masuk dengan satu inti bersama.

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

Apa yang dilakukan agen dengan sebuah pesan, di Node.js?

agent.mjs berisi logika yang dipakai bersama oleh kedua jalur. Ia mencatat waktu pesan terakhir pelanggan, berhenti sementara selama 4 jam pada suatu chat ketika event smb_message_echoes menunjukkan seseorang membalas dari aplikasi WhatsApp Business (yang dipakai otomasi bawaan easyCoexistence), melewati ID pesan yang sudah ditangani, dan hanya mengirim di dalam jendela 24 jam. Jendela diukur dari timestamp pesan itu sendiri, bukan dari saat pesan sampai ke Anda, karena pengiriman yang dicoba ulang bisa tiba berjam-jam terlambat.

Pengguna diidentifikasi dengan BSUID (from_user_id, atau to_user_id pada echo) dengan nomor telepon sebagai acuan cadangan, dan pengguna yang hanya dikenal lewat BSUID dibalas dengan recipient, bukan to. Pemanggilan model memakai API chat completions apa pun yang kompatibel dengan OpenAI; ganti dengan SDK penyedia Anda jika lebih suka.

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

Bagaimana cara memverifikasi dan merutekan event di Node.js?

server.mjs menyediakan tiga titik masuk. /ec/forward menerima pesan yang diteruskan dari nomor terkelola: ia memverifikasi X-EC-Signature pada byte mentah dengan forward secret nomor itu, menjawab 200 sebelum melakukan pekerjaan apa pun, dan melewati ID pengiriman yang sudah diterima, karena percobaan ulang membawa ID yang sama dengan tanda tangan baru. Field event pada body berisi nama field Meta, dan value berisi perubahan Meta tanpa diubah. /ec/agent menjawab langkah Call my webhook, ditandatangani dengan Signing secret milik otomasi itu, dan mengubah riwayat menjadi giliran chat. /meta/:secret adalah jalur langsung: ia menjawab handshake GET dari Meta dengan hub.challenge mentah dan hanya menerima POST pada path rahasia.

Kunci HMAC adalah seluruh rahasia, termasuk prefiks whsec_, sebagai teks UTF-8. express.raw menjaga byte tetap utuh, dan batas 5 MB-nya menyisakan ruang untuk payload Meta hingga 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);

Seperti apa agen yang sama dalam Python?

Satu file Flask dengan ketiga rute yang sama dan aturan yang sama. request.get_data() mengembalikan body mentah untuk HMAC, hmac.compare_digest melakukan perbandingan dengan waktu konstan, dan pekerjaan berjalan di thread latar belakang setelah 200, sehingga baik easyCoexistence maupun Meta tidak menunggu model Anda. Jalankan dengan flask --app agent run saat pengembangan, dan di belakang gunicorn atau server WSGI lain saat produksi.

Set dan dictionary di memori cocok untuk satu proses. Dengan beberapa worker atau instans, pindahkan ke Redis atau database Anda, memakai penulisan set-if-absent dengan masa kedaluwarsa untuk ID pesan, atau dua worker akan membalas pesan yang sama.

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

Bagaimana cara menghindari balasan ganda?

Balasan ganda punya enam penyebab umum, dan contoh di atas menangani lima yang pertama:

  • Percobaan ulang dari Meta. Webhook langsung dicoba ulang hingga 7 hari setelah apa pun selain HTTP 200; simpan daftar ID pesan dan lewati ID yang sudah ditangani.
  • Percobaan ulang pada forward. easyCoexistence mencoba kembali pengiriman yang tidak menerima 2xx dalam 10 detik, dengan ID yang sama; lewati ID yang sudah diterima, lalu deduplikasi berdasarkan ID pesan, karena perubahan yang dikirim ulang oleh Meta diteruskan lagi dengan ID baru.
  • Konfirmasi yang lambat. Jawab dulu lalu kerjakan; handler yang menunggu model akan kehabisan waktu, dan event yang sama akan datang lagi.
  • Orang yang memakai ponsel. Event smb_message_echoes berarti seseorang membalas dari aplikasi; diam pada chat itu selama beberapa jam.
  • Beberapa worker. Set di memori tidak berlaku lintas proses; pindahkan penyimpanannya ke Redis atau database Anda.
  • Dua penjawab. Otomasi balasan AI dan agen Anda sendiri pada chat yang sama sama-sama menjawab, dan pengiriman Graph API Anda bukan echo, jadi tidak menjeda otomasi. Pilih satu penjawab untuk setiap nomor.

Dari mana rahasia dan kredensial berasal?

Dari dashboard atau konektor MCP, dan hanya boleh disimpan di environment server Anda. get_api_credentials mengembalikan graph_api_base, waba_id, phone_number_id, send_endpoint, dan access_token, yaitu token milik bisnis itu sendiri; halaman nomor menampilkan nilai yang sama di bawah 'Hubungkan ke sistem Anda sendiri'. Jika access_token bernilai null, hubungkan ulang nomor dari komputer dengan 'Hubungkan ulang' untuk menerbitkan token. Perlakukan token seperti kata sandi, karena siapa pun yang memegangnya dapat mengirim pesan atas nama bisnis.

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

Kesalahan umum

  • Memeriksa HMAC pada JSON yang diserialisasi ulang. json.dumps di Python secara default menambahkan spasi setelah pemisah, jadi body yang di-parse lalu di-dump lagi tidak cocok; verifikasi byte mentahnya.
  • Mendekode base64 pada rahasia atau membuang prefiks whsec_-nya. Kuncinya adalah seluruh string sebagai teks UTF-8, persis seperti yang ditampilkan kepada Anda sekali saja.
  • Memvalidasi X-Hub-Signature-256 pada jalur langsung dengan app secret Meta milik Anda sendiri. Meta menandatangani dengan app secret milik easyCoexistence, yang tidak dibagikan, sehingga event asli gagal; autentikasi dengan rahasia pada path.
  • Membaca jendela dari waktu kedatangan. Forward yang dicoba ulang berjam-jam kemudian tetap membawa timestamp asli Meta; bandingkan dengannya, atau agen membalas setelah 24 jam dan Meta menolak pengiriman.
Melakukan ini dengan EasyCoexistence

Setiap nomor dipantau 24/7, dengan peringatan saat koneksi terputus. US$ 9 turun hingga US$ 0.75 per nomor per bulan, makin murah seiring Anda menambah nomor, dengan 3 hari pertama gratis.

Pertanyaan yang sering diajukan

Apakah agen bisa memahami voice note dan foto?

Bisa, dengan kode Anda sendiri. Payload Meta membawa ID media: unduh dengan GET /<media-id> dan token nomor itu, ambil URL yang dikembalikan dengan header Authorization yang sama, lalu transkripsikan atau deskripsikan dengan model Anda. Otomasi hanya melihat placeholder seperti [voice message].

Model apa yang bisa dipakai contoh?

Model apa pun di balik endpoint chat completions yang kompatibel dengan OpenAI, termasuk milik OpenAI dan yang diakses lewat OpenRouter, atau ganti askModel dan ask_model dengan SDK penyedia Anda. easyCoexistence tidak pernah menagih biaya AI: penyedia Anda yang menagih Anda langsung.

Bisakah agen memulai percakapan?

Hanya dengan template yang disetujui, dikirim dengan type template ke endpoint kirim yang sama. Pada nomor Coexistence, template hanya dikirim lewat API, tidak pernah dari aplikasi ponsel, dan Meta menagih per pesan ke WhatsApp Business Account milik bisnis itu sendiri.

Apakah satu agen bisa melayani beberapa nomor?

Bisa. Rutekan berdasarkan value.metadata.phone_number_id atau connection.phone_number_id, dan simpan endpoint kirim, token, dan forward secret untuk setiap nomor, karena setiap nomor punya miliknya sendiri.

Lanjut membaca

Siap memulai?

Konfigurasikan WhatsApp Coexistence dalam hitungan menit, bukan bulan. Aplikasi tetap berfungsi di ponsel.

Mulai uji coba gratis

Diverifikasi pada