MasukMulai uji coba gratis
Meta Tech Provider

Bagaimana pesan WhatsApp sampai ke server Anda: langsung atau terkelola, dan memverifikasi tanda tangan

Setiap nomor yang terhubung lewat easyCoexistence punya satu mode pesan masuk. Langsung ke sistem Anda (direct): Meta mengirim webhook-nya ke endpoint HTTPS Anda, rahasia di URL adalah kredensialnya, dan otomasi nonaktif. Lewat easyCoexistence (terkelola): Meta mengirim ke easyCoexistence, otomasi dapat membalas, dan Forward URL opsional menerima nilai asli dari Meta beserta detail koneksi, ditandatangani dengan X-EC-Signature agar Anda dapat memverifikasinya.

7 attempts

Percobaan per pengiriman yang diteruskan, berjarak 1 menit, 5 menit, 30 menit, 2 jam, 6 jam dan 24 jam, sekitar 33 jam seluruhnya.

10 s

Berapa lama setiap upaya penerusan menunggu 2xx sebelum dianggap gagal.

5 min

Batas usia yang disarankan untuk t pada tanda tangan; percobaan ulang ditandatangani ulang, sehingga pengiriman asli tetap berada dalam batas itu.

7 days

Berapa lama Meta mencoba kembali webhook langsung yang menerima respons selain HTTP 200, yang dapat membuat pesan terkirim berulang.

3 MB

Payload webhook terbesar yang dikirim Meta, termasuk potongan riwayat.

30 days

Log run yang disimpan untuk nomor terkelola, dengan teks pesan dan balasan; teks pesan itu sendiri disimpan 30, 90, atau 365 hari, sesuai pilihan Anda.

Apa perbedaan antara langsung dan terkelola?

Di mana Meta mengirim webhook pesan milik nomor tersebut. Terkelola, ditampilkan sebagai Through easyCoexistence, berarti Meta mengirim ke easyCoexistence, yang memeriksa tanda tangan Meta, menjalankan otomasi Anda, menyimpan chat untuk Conversations dan, jika Anda mengatur Forward URL, meneruskan setiap perubahan dari Meta kepada Anda, ditandatangani dengan rahasia yang hanya Anda pegang. Langsung, ditampilkan sebagai Straight to your system, berarti easyCoexistence mengatur endpoint HTTPS Anda sebagai webhook override pada WhatsApp Business Account nomor tersebut, sehingga Meta mengirim langsung ke Anda dan pesan tidak pernah sampai ke easyCoexistence.

Webhook operasional di balik pemantauan, seperti account_update dan perubahan kualitas, tetap berada di easyCoexistence di kedua mode, sehingga peringatan tetap berfungsi di mode mana pun.

Managed: Through easyCoexistenceDirect: Straight to your system
Meta delivers toeasyCoexistence, which verifies Meta's signatureYour HTTPS endpoint
AutomationsRun on the numberOff
Your copyOptional Forward URL, one Meta change per POSTMeta's envelope, unchanged
Proof it is genuineX-EC-Signature, HMAC-SHA256 with the number's secretA long random secret in the URL path
Failed deliveries7 attempts over about 33 hoursMeta retries for up to 7 days
History importNot requestedRequested when saved within 24 hours of connecting
Kept by easyCoexistenceMessage text 30, 90 or 365 days, run logs 30 daysNothing

Bagaimana cara memindahkan nomor di antara keduanya?

Pada halaman nomor, kartu Where incoming messages go menampilkan mode sebagai dua pilihan, Through easyCoexistence dan Straight to your system. Menyimpan tujuan webhook, di kartu Route incoming messages to your own webhook atau dengan set_webhook_destination, membuat nomor menjadi langsung. Memilih Through easyCoexistence seketika menghapus tujuan tersebut di Meta, jadi tambahkan URL yang sama sebagai Forward URL agar tetap menerima pesan. Penerusan yang masih antre dibatalkan ketika nomor keluar dari mode terkelola, dan nomor yang terhubung tanpa URL webhook dimulai dalam mode terkelola.

Dari AI Anda, set_inbound_mode mengganti mode dan mengatur penerusan dalam satu panggilan, lalu mengembalikan rahasia penerusan sekali saja:

set_inbound_mode: arguments and result
// set_inbound_mode arguments
{
  "connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "mode": "managed",
  "forward_url": "https://agent.example.com/ec/forward"
}

// result: forward_secret is shown once
{
  "connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "mode": "managed",
  "forward_url": "https://agent.example.com/ec/forward",
  "forward_secret": "whsec_Qm9vbXRoZXNlY3JldHNhcmVmYWtlMTIz",
  "secret_note": "Shown once. Verify X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with it; the body's value is Meta's original payload.",
  "direct_destination": null
}

Apa isi sebuah POST yang diteruskan?

Satu perubahan Meta per permintaan, dibungkus, bukan amplop object, entry dan changes milik Meta. id adalah id pengiriman, diulang di X-EC-Delivery dan tetap sama di seluruh percobaan ulang. event adalah nama field Meta, yaitu messages, smb_message_echoes, history atau smb_app_state_sync, diulang di X-EC-Event. received_at adalah waktu easyCoexistence menerima perubahan dari Meta, connection mengidentifikasi nomor, dan value persis seperti yang dikirim Meta, sehingga kode parsing yang ditulis untuk payload Meta tetap berfungsi. Status pengiriman datang di dalam event messages, di bawah value.statuses.

A forwarded messages event: headers and body
POST /ec/forward HTTP/1.1
Content-Type: application/json
User-Agent: easyCoexistence-forward/1
X-EC-Event: messages
X-EC-Delivery: 8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13
X-EC-Signature: t=1794405732,v1=<64 hex characters>

{
  "id": "8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13",
  "event": "messages",
  "received_at": "2026-11-11T14:02:11.482Z",
  "connection": {
    "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
    "phone": "+1 631-555-0142",
    "phone_number_id": "106540352242922",
    "waba_id": "102290129340398",
    "external_ref": null
  },
  "value": {
    "messaging_product": "whatsapp",
    "metadata": { "display_phone_number": "16315550142", "phone_number_id": "106540352242922" },
    "contacts": [{ "profile": { "name": "Ana Souza" }, "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" }],
    "messages": [{
      "from": "5511987654321",
      "from_user_id": "BR.13491208655302741918",
      "id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==",
      "timestamp": "1794405731",
      "type": "text",
      "text": { "body": "Do you deliver on Sundays?" }
    }]
  }
}

Bagaimana cara memverifikasi X-EC-Signature di Node.js?

Baca header sebagai t=<detik unix>,v1=<64 karakter hex>. Tolak t yang selisihnya lebih dari 5 menit dari jam Anda, hitung HMAC-SHA256 atas t, titik, dan body mentah, dengan kunci seluruh rahasia penerusan sebagai teks UTF-8, lalu bandingkan hasilnya dengan v1 dalam waktu konstan. Baru setelah itu parse JSON. Jawab 2xx dalam 10 detik dan kerjakan pekerjaannya setelahnya, serta ingat id pengiriman yang sudah Anda terima agar percobaan ulang tidak diproses dua kali.

forward-receiver.mjs (Node.js, no dependencies)
// forward-receiver.mjs: node forward-receiver.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";

const SECRET = process.env.EC_FORWARD_SECRET; // the whole whsec_... string is the HMAC key
const taken = new Set(); // delivery ids already accepted: use a database in production

export function verifyEcSignature(raw, header, secret = SECRET, maxAgeSec = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
  if (!m || !secret) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > maxAgeSec) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
  return crypto.timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}

http.createServer((req, res) => {
  const chunks = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    const raw = Buffer.concat(chunks);
    if (req.method !== "POST" || !verifyEcSignature(raw, req.headers["x-ec-signature"])) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(200).end(); // a 2xx within 10 s, before any work
    const d = JSON.parse(raw.toString("utf8"));
    if (taken.has(d.id)) return; // a retry of a delivery already accepted
    taken.add(d.id);
    // d.event is the Meta field (messages, smb_message_echoes, history, smb_app_state_sync)
    // d.value is Meta's change value, unchanged; queue it for your worker here.
    console.log(d.event, d.connection.phone_number_id, Object.keys(d.value));
  });
}).listen(process.env.PORT ?? 3000);

Bagaimana cara memverifikasinya di Python?

Empat pemeriksaan yang sama dengan pustaka standar: pola ketat untuk header, usia t, hmac.new atas t, titik, dan byte mentah, serta hmac.compare_digest. Di FastAPI, body mentah diambil dari await request.body(), dan BackgroundTasks menjalankan pekerjaan setelah 200 terkirim. Di Flask, gunakan request.get_data(), dan jangan pernah menyusun ulang body dengan json.dumps, karena pemisah default Python menambahkan spasi dan tanda tangan tidak lagi cocok.

forward_receiver.py (FastAPI)
# forward_receiver.py: pip install fastapi uvicorn, then uvicorn forward_receiver:app
import hashlib, hmac, json, os, re, time
from fastapi import BackgroundTasks, FastAPI, Request, Response

app = FastAPI()
SECRET = os.environ["EC_FORWARD_SECRET"].encode()  # the whole whsec_... string, as bytes
SIGNATURE = re.compile(r"t=([0-9]+),v1=([0-9a-f]{64})")
taken = set()  # delivery ids already accepted: use a database in production

def verify_ec_signature(raw: bytes, header: str, max_age: int = 300) -> bool:
    m = SIGNATURE.fullmatch(header.strip())
    if not m or abs(int(time.time()) - int(m[1])) > max_age:
        return False
    mac = hmac.new(SECRET, m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, m[2])

def process(delivery: dict) -> None:
    if delivery["id"] in taken:  # a retry of a delivery already accepted
        return
    taken.add(delivery["id"])
    print(delivery["event"], delivery["connection"]["phone_number_id"], list(delivery["value"]))

@app.post("/ec/forward")
async def forward(request: Request, tasks: BackgroundTasks):
    raw = await request.body()
    if not verify_ec_signature(raw, request.headers.get("x-ec-signature", "")):
        return Response(status_code=401)
    tasks.add_task(process, json.loads(raw))  # runs after the 200 goes out
    return Response(status_code=200)

Bagaimana pengiriman yang gagal dicoba kembali?

Penerusan dianggap terkirim ketika endpoint Anda menjawab dengan 2xx apa pun dalam 10 detik. Hasil lainnya, yaitu waktu habis, 4xx, 5xx, atau pengalihan (yang tidak diikuti), menjadwalkan upaya berikutnya sekitar 1 menit, 5 menit, 30 menit, 2 jam, 6 jam, dan 24 jam kemudian, dan setelah upaya ketujuh pengiriman dihentikan. Setiap upaya ditandatangani ulang dengan t yang baru, dan URL harus HTTPS publik, diperiksa saat disimpan dan lagi sebelum setiap pengiriman. Pengiriman keluar dari yang tertua lebih dulu, tetapi pengiriman yang dicoba kembali bisa tiba setelah yang lebih baru, jadi urutkan menurut timestamp dari Meta.

Pada tujuan langsung, Meta yang mencoba kembali: respons selain HTTP 200 dicoba kembali dengan frekuensi yang makin jarang hingga 7 hari, dan percobaan itu dapat membuat pesan terkirim berulang. Lakukan deduplikasi berdasarkan id pesan dari Meta di kedua mode, karena perubahan yang dikirim ulang oleh Meta akan diteruskan lagi dengan id pengiriman baru.

Bagaimana endpoint langsung tahu bahwa sebuah POST itu asli?

Bukan dari X-Hub-Signature-256. Meta menandatangani dengan app secret dari aplikasi yang memiliki langganan, yang untuk nomor yang terhubung di sini adalah milik easyCoexistence dan tidak dibagikan, jadi memeriksa header itu dengan app secret Meta Anda sendiri akan menolak pengiriman yang asli. Token verifikasi hanya membuktikan endpoint satu kali, saat handshake GET dari Meta. Cara yang berhasil:

  • Tambahkan 32 karakter acak atau lebih di path URL callback dan tolak permintaan yang tidak memilikinya; untuk mengganti, simpan URL baru.
  • Gunakan penerima generik, seperti node Webhook n8n, bukan pemicu WhatsApp yang mengharapkan aplikasi Meta Anda sendiri.
  • Unduh media berdasarkan id dari Meta dengan token nomor tersebut, sehingga id palsu akan gagal begitu saja.
  • Pada server self-hosted, opsional izinkan hanya jaringan Meta, yaitu rute yang diumumkan AS32934.
  • Atau beralih ke terkelola dengan Forward URL, di mana X-EC-Signature membuktikan setiap POST.

Kesalahan umum

  • Mengarahkan kode yang ditulis untuk amplop Meta ke Forward URL tanpa perubahan. Penerusan membawa satu perubahan: baca event dan value, bukan object, entry dan changes.
  • Menunggu X-EC-Event berupa statuses. Status pengiriman datang di dalam event messages, di value.statuses, dan balasan yang diketik di aplikasi datang sebagai smb_message_echoes.
  • Mengerjakan pekerjaan sebelum menjawab. Penerusan menunggu 10 detik, lalu pengiriman yang sama kembali dengan t yang baru; jawab 2xx dulu dan proses dari antrean.
  • Beralih ke terkelola dan mengira URL lama masih menerima pesan. Tujuan langsung dihapus pada saat itu; sertakan forward_url dalam panggilan set_inbound_mode yang sama.
Melakukan ini dengan EasyCoexistence

easyCoexistence menghubungkan nomor aplikasi WhatsApp Business ke Cloud API Meta melalui Coexistence dan memungkinkan Anda memilih, per nomor, ke mana pesannya dikirim: langsung dari Meta ke server Anda, atau lewat easyCoexistence agar otomasi dapat membalas dan salinan bertanda tangan sampai ke Forward URL Anda. Pemantauan dan peringatan berfungsi di kedua mode. US$ 9 turun ke US$ 0.75 per nomor per bulan, turun seiring Anda menambah nomor, dengan 3 hari pertama gratis.

Pertanyaan yang sering diajukan

Apakah server saya melihat apa yang dibalas otomasi?

Bukan teksnya. Meta melaporkan pengiriman lewat API sebagai status (sent, delivered, read) di dalam event messages, dengan id pesan; teks itu sendiri ada di log run otomasi, disimpan 30 hari di tab Runs, dan di Conversations selama waktu yang Anda pilih.

Bagaimana cara mengganti rahasia penerusan?

Klik New secret di halaman nomor, atau panggil set_inbound_mode dengan rotate_secret bernilai true. Rahasia baru ditampilkan sekali dan menandatangani semua pengiriman sejak saat itu, termasuk percobaan ulang pengiriman lama, jadi perbarui server Anda segera.

Apakah Forward URL memerlukan handshake GET dari Meta?

Tidak. Hanya tujuan langsung yang dipanggil Meta dan harus mengembalikan hub.challenge. Forward URL dipanggil oleh easyCoexistence dan hanya menerima POST yang ditandatangani.

Bisakah sebuah nomor memiliki tujuan langsung dan Forward URL sekaligus?

Tidak. Forward URL hanya berfungsi selama nomor dalam mode terkelola, dan menyimpan tujuan langsung membuat nomor menjadi langsung. Forward URL dan rahasianya tetap disimpan, sehingga beralih kembali ke terkelola akan melanjutkan penerusan.

Lanjut membaca

Siap memulai?

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

Mulai uji coba gratis

Diverifikasi pada