Log masukMulakan percubaan percuma
Meta Tech Provider

Bagaimana mesej WhatsApp sampai ke pelayan anda: terus atau diurus, dan mengesahkan tandatangan

Setiap nombor yang disambungkan melalui easyCoexistence mempunyai satu mod mesej masuk. Terus ke sistem anda (langsung): Meta menghantar webhook ke endpoint HTTPS anda, rahsia dalam URL ialah kelayakan, dan automasi dimatikan. Melalui easyCoexistence (diurus): Meta menghantar ke easyCoexistence, automasi boleh menjawab, dan URL Forward pilihan menerima nilai asal Meta bersama butiran sambungan, ditandatangani dengan X-EC-Signature untuk anda sahkan.

7 attempts

Percubaan bagi setiap penghantaran ke hadapan, berjarak 1 minit, 5 minit, 30 minit, 2 jam, 6 jam dan 24 jam, kira-kira 33 jam keseluruhan.

10 s

Tempoh setiap percubaan penghantaran ke hadapan menunggu respons 2xx sebelum dikira gagal.

5 min

Had cadangan bagi umur t tandatangan; cubaan semula ditandatangani semula, jadi penghantaran tulen kekal dalam had ini.

7 days

Tempoh Meta mencuba semula webhook terus yang menerima apa-apa selain HTTP 200, yang boleh mengulang mesej.

3 MB

Saiz muatan webhook terbesar yang dihantar Meta, termasuk blok sejarah.

30 days

Log larian yang disimpan bagi nombor diurus, dengan teks mesej dan balasan; teks mesej itu sendiri disimpan selama 30, 90 atau 365 hari, mengikut pilihan anda.

Apakah perbezaan antara terus dan diurus?

Di mana Meta menghantar webhook mesej nombor tersebut. Diurus, ditunjukkan sebagai Melalui easyCoexistence, bermakna Meta menghantar ke easyCoexistence, yang menyemak tandatangan Meta, menjalankan automasi anda, menyimpan sembang untuk Conversations dan, jika anda menetapkan URL Forward, menghantar setiap perubahan Meta kepada anda dengan rahsia yang hanya anda pegang. Terus, ditunjukkan sebagai Terus ke sistem anda, bermakna easyCoexistence menetapkan endpoint HTTPS anda sebagai penggantian webhook pada Akaun WhatsApp Business nombor tersebut, jadi Meta menghantar terus kepada anda dan mesej tidak sampai ke easyCoexistence.

Webhook operasi di sebalik pemantauan, seperti account_update dan perubahan kualiti, kekal bersama easyCoexistence dalam kedua-dua mod, sebab itulah amaran terus berfungsi dalam kedua-dua keadaan.

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 anda menukar nombor antara kedua-dua mod?

Pada halaman nombor, kad Ke mana mesej masuk pergi menunjukkan mod sebagai dua pilihan, Melalui easyCoexistence dan Terus ke sistem anda. Menyimpan destinasi webhook, dalam kad Hala mesej masuk ke webhook anda sendiri atau dengan set_webhook_destination, menjadikan nombor itu terus. Memilih Melalui easyCoexistence serta-merta membuang destinasi itu di Meta, jadi tambahkan URL yang sama sebagai URL Forward untuk terus menerima. Penghantaran yang sedang beratur dibuang apabila nombor keluar daripada mod diurus, dan nombor yang disambungkan tanpa URL webhook bermula dalam mod diurus.

Daripada AI anda, set_inbound_mode menukar mod dan menetapkan URL Forward dalam satu panggilan, dan memulangkan rahsia Forward sekali sahaja:

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 yang terkandung dalam POST yang dihantar ke hadapan?

Satu perubahan Meta bagi setiap permintaan, dibungkus, bukan sampul objek, entri dan changes Meta. id ialah id penghantaran, diulang dalam X-EC-Delivery dan kekal sama merentasi cubaan semula. event ialah nama medan Meta, messages, smb_message_echoes, history atau smb_app_state_sync, diulang dalam X-EC-Event. received_at ialah masa easyCoexistence menerima perubahan itu daripada Meta, connection mengenal pasti nombor, dan value ialah tepat apa yang Meta hantar, jadi kod penghurai yang ditulis untuk muatan Meta berfungsi ke atasnya. Status penghantaran tiba di dalam peristiwa 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 anda mengesahkan X-EC-Signature dalam Node.js?

Baca header sebagai t=<saat unix>,v1=<64 aksara heksadesimal>. Tolak t yang lebih daripada 5 minit daripada jam anda, kira HMAC-SHA256 ke atas t, titik dan badan mentah, dikunci dengan keseluruhan rahsia forward sebagai teks UTF-8, dan bandingkan hasilnya dengan v1 dalam perbandingan masa tetap. Hanya selepas itu urai JSON. Jawab 2xx dalam masa 10 saat dan lakukan kerja selepasnya, dan ingat id penghantaran yang telah anda terima supaya cubaan semula 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 anda mengesahkannya dalam Python?

Empat semakan yang sama dengan pustaka piawai: corak ketat untuk header, umur t, hmac.new ke atas t, titik dan bait mentah, dan hmac.compare_digest. Dalam FastAPI, badan mentah datang daripada await request.body(), dan BackgroundTasks menjalankan kerja selepas 200 dihantar. Dalam Flask, gunakan request.get_data(), dan jangan sekali-kali bina semula badan dengan json.dumps, kerana pemisah lalai Python menambah ruang dan tandatangan tidak lagi sepadan.

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 penghantaran yang gagal dicuba semula?

Penghantaran dikira telah dihantar apabila endpoint anda menjawab mana-mana 2xx dalam masa 10 saat. Apa-apa selain itu, tamat masa, 4xx, 5xx atau pengalihan, yang tidak diikuti, menjadualkan percubaan seterusnya kira-kira 1 minit, 5 minit, 30 minit, 2 jam, 6 jam dan 24 jam kemudian, dan selepas percubaan ketujuh penghantaran itu ditinggalkan. Setiap percubaan ditandatangani semula dengan t yang baharu, dan URL mesti HTTPS awam, disemak apabila disimpan dan sekali lagi sebelum setiap penghantaran. Penghantaran keluar mengikut urutan tertua dahulu, tetapi penghantaran yang dicuba semula boleh tiba selepas yang lebih baharu, jadi susun mengikut cap masa Meta.

Dalam destinasi terus, Meta yang melakukan cubaan semula: apa-apa selain HTTP 200 dicuba semula dengan kekerapan yang semakin berkurang sehingga 7 hari, dan cubaan itu boleh mengulang mesej. Nyahduplikasi mengikut id mesej Meta dalam kedua-dua mod, kerana perubahan yang dihantar semula oleh Meta akan diteruskan semula di bawah id penghantaran baharu.

Bagaimana endpoint terus tahu POST itu tulen?

Bukan daripada X-Hub-Signature-256. Meta menandatangani dengan rahsia aplikasi bagi aplikasi yang memiliki langganan, iaitu untuk nombor yang disambungkan di sini ialah milik easyCoexistence dan tidak dikongsi, jadi menyemak header itu dengan rahsia aplikasi Meta anda sendiri menolak penghantaran tulen. Verify token hanya membuktikan endpoint sekali, semasa jabat tangan GET Meta. Yang berfungsi sebaliknya:

  • Letakkan 32 aksara rawak atau lebih dalam laluan URL panggil balik dan tolak permintaan tanpanya; untuk menukar, simpan URL baharu.
  • Gunakan penerima generik, seperti nod Webhook n8n, bukan pencetus WhatsApp yang memerlukan aplikasi Meta anda sendiri.
  • Muat turun media mengikut id daripada Meta dengan token nombor itu, supaya id yang dipalsukan hanya gagal.
  • Pada pelayan yang dihoskan sendiri, anda boleh membenarkan hanya rangkaian Meta, laluan yang diumumkan oleh AS32934.
  • Atau beralih kepada diurus dengan URL Forward, di mana X-EC-Signature membuktikan setiap POST.

Kesilapan biasa

  • Mengarahkan kod yang ditulis untuk sampul Meta ke URL Forward tanpa diubah suai. Penghantaran ke hadapan membawa satu perubahan sahaja: baca event dan value, bukan object, entry dan changes.
  • Menunggu X-EC-Event bernilai statuses. Status penghantaran tiba dalam peristiwa messages, di value.statuses, dan balasan yang ditaip dalam aplikasi tiba sebagai smb_message_echoes.
  • Melakukan kerja sebelum menjawab. Penghantaran ke hadapan menunggu 10 saat, kemudian penghantaran yang sama kembali dengan t baharu; jawab 2xx dahulu dan proses daripada baris gilir.
  • Beralih kepada diurus dan menganggap URL lama masih menerima. Destinasi terus dibuang pada saat itu; masukkan forward_url dalam panggilan set_inbound_mode yang sama.
Menggunakan EasyCoexistence untuk ini

easyCoexistence menyambungkan nombor aplikasi WhatsApp Business ke Cloud API Meta melalui Coexistence dan membolehkan anda memilih, bagi setiap nombor, ke mana mesejnya pergi: terus daripada Meta ke pelayan anda, atau melalui easyCoexistence supaya automasi boleh menjawab dan salinan bertandatangan sampai ke URL Forward anda. Pemantauan dan amaran berfungsi dalam kedua-dua mod. Harga bermula US$ 9 turun ke US$ 0.75 bagi setiap nombor sebulan, kian menurun apabila anda menambah nombor, dengan 3 hari percubaan percuma pertama.

Soalan lazim

Adakah pelayan saya akan nampak apa yang automasi balas?

Bukan teksnya. Meta melaporkan penghantaran API sebagai status (sent, delivered, read) dalam peristiwa messages, dengan id mesej; teks itu sendiri ada dalam log larian automasi, disimpan 30 hari dalam tab Runs, dan dalam Conversations selama tempoh yang anda pilih.

Bagaimana saya menukar rahsia Forward?

Klik Rahsia baharu pada halaman nombor, atau panggil set_inbound_mode dengan rotate_secret ditetapkan kepada true. Rahsia baharu dipaparkan sekali dan menandatangani semua yang berikutnya, termasuk cubaan semula penghantaran lama, jadi kemas kini pelayan anda dengan segera.

Adakah URL Forward memerlukan jabat tangan GET Meta?

Tidak. Hanya destinasi terus dipanggil oleh Meta dan perlu memulangkan semula hub.challenge. URL Forward dipanggil oleh easyCoexistence dan hanya menerima POST yang ditandatangani.

Bolehkah satu nombor mempunyai destinasi terus dan URL Forward serentak?

Tidak. URL Forward hanya berfungsi selagi nombor itu diurus, dan menyimpan destinasi terus menjadikannya terus. URL Forward dan rahsianya dikekalkan, jadi beralih semula kepada diurus menyambung semula penghantaran ke hadapan.

Teruskan membaca

Sedia untuk bermula?

Sediakan WhatsApp Coexistence dalam beberapa minit, bukan berbulan-bulan. Aplikasi terus berfungsi pada telefon.

Mulakan Percubaan Percuma

Disahkan pada