WhatsApp मैसेज आपके सर्वर तक कैसे पहुँचते हैं: डायरेक्ट या मैनेज्ड, और सिग्नेचर की पुष्टि
easyCoexistence के ज़रिए जुड़े हर नंबर का एक इनबाउंड मोड होता है। Straight to your system (डायरेक्ट मोड) में Meta अपने वेबहुक आपके HTTPS एंडपॉइंट पर भेजता है, URL में मौजूद सीक्रेट ही क्रेडेंशियल है, और ऑटोमेशन बंद रहते हैं। Through easyCoexistence (मैनेज्ड मोड) में Meta मैसेज easyCoexistence को भेजता है, ऑटोमेशन जवाब दे सकते हैं, और एक वैकल्पिक Forward URL को Meta का मूल value कनेक्शन के विवरण के साथ मिलता है, जो X-EC-Signature से साइन होता है ताकि आप उसकी जाँच कर सकें।
हर फ़ॉरवर्ड की गई डिलीवरी के लिए प्रयास 1 मिनट, 5 मिनट, 30 मिनट, 2 घंटे, 6 घंटे और 24 घंटे के अंतराल पर होते हैं, कुल लगभग 33 घंटे।
हर फ़ॉरवर्ड प्रयास कितनी देर तक 2xx का इंतज़ार करता है, उसके बाद ही उसे विफल माना जाता है।
सिग्नेचर के t पर सुझाई गई आयु सीमा; दोबारा कोशिशें फिर से साइन होती हैं, इसलिए असली डिलीवरी इस सीमा के भीतर रहती हैं।
HTTP 200 के अलावा कुछ भी पाने वाले डायरेक्ट वेबहुक को Meta कितनी देर तक दोबारा भेजता है; इससे मैसेज दोहराए जा सकते हैं।
Meta द्वारा भेजा गया सबसे बड़ा वेबहुक पेलोड, हिस्ट्री के हिस्सों सहित।
मैनेज्ड नंबर के लिए रखे गए रन लॉग, मैसेज और जवाब के टेक्स्ट के साथ; मैसेज का टेक्स्ट स्वयं 30, 90 या 365 दिन तक रखा जाता है, यह आपकी पसंद है।
डायरेक्ट और मैनेज्ड में क्या अंतर है?
यह तय होता है कि Meta नंबर के मैसेज वेबहुक कहाँ भेजता है। मैनेज्ड, जो Through easyCoexistence के रूप में दिखता है, का अर्थ है कि Meta easyCoexistence को भेजता है, जो Meta का सिग्नेचर जाँचता है, आपके ऑटोमेशन चलाता है, Conversations के लिए चैट सहेजता है और, अगर आपने Forward URL सेट किया है, तो Meta का हर change आपको भेज देता है, जो सिर्फ़ आपके पास मौजूद सीक्रेट से साइन होता है। डायरेक्ट, जो Straight to your system के रूप में दिखता है, का अर्थ है कि easyCoexistence आपका HTTPS एंडपॉइंट नंबर के WhatsApp Business Account पर वेबहुक ओवरराइड के रूप में सेट करता है, इसलिए Meta सीधे आपको पोस्ट करता है और मैसेज easyCoexistence तक कभी नहीं पहुँचते।
निगरानी और अलर्ट के पीछे के ऑपरेशनल वेबहुक, जैसे account_update और quality changes, दोनों मोड में easyCoexistence के पास रहते हैं, इसीलिए अलर्ट दोनों में काम करते रहते हैं।
| Managed: Through easyCoexistence | Direct: Straight to your system | |
|---|---|---|
| Meta delivers to | easyCoexistence, which verifies Meta's signature | Your HTTPS endpoint |
| Automations | Run on the number | Off |
| Your copy | Optional Forward URL, one Meta change per POST | Meta's envelope, unchanged |
| Proof it is genuine | X-EC-Signature, HMAC-SHA256 with the number's secret | A long random secret in the URL path |
| Failed deliveries | 7 attempts over about 33 hours | Meta retries for up to 7 days |
| History import | Not requested | Requested when saved within 24 hours of connecting |
| Kept by easyCoexistence | Message text 30, 90 or 365 days, run logs 30 days | Nothing |
नंबर को दोनों में से किसी एक मोड में कैसे बदलें?
नंबर के पेज पर Where incoming messages go कार्ड मोड को दो विकल्पों के रूप में दिखाता है, Through easyCoexistence और Straight to your system। Route incoming messages to your own वेबहुक कार्ड में, या set_webhook_destination से, वेबहुक डेस्टिनेशन सेव करने पर नंबर डायरेक्ट बन जाता है। Through easyCoexistence चुनने पर वह डेस्टिनेशन Meta पर तुरंत हट जाता है, इसलिए मैसेज मिलते रहने के लिए वही URL Forward URL के रूप में जोड़ें। जब कोई नंबर मैनेज्ड मोड छोड़ता है तो कतार में लगे फ़ॉरवर्ड हटा दिए जाते हैं, और बिना वेबहुक URL के जुड़े नंबर मैनेज्ड मोड में शुरू होते हैं।
अपने AI से set_inbound_mode मोड बदलता है और एक ही कॉल में फ़ॉरवर्ड भी सेट करता है, और फ़ॉरवर्ड सीक्रेट एक बार लौटाता है:
// 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
}फ़ॉरवर्ड किए गए POST में क्या होता है?
हर अनुरोध में Meta का एक change होता है, लपेटा हुआ, न कि Meta का object, entry और changes वाला envelope। id डिलीवरी id है, जो X-EC-Delivery में दोहराया जाता है और दोबारा कोशिशों में भी स्थिर रहता है। event Meta का field नाम है: messages, smb_message_echoes, history या smb_app_state_sync, जो X-EC-Event में दोहराया जाता है। received_at वह समय है जब easyCoexistence ने Meta से change लिया, connection नंबर की पहचान करता है, और value वही है जो Meta ने भेजा, इसलिए Meta के पेलोड के लिए लिखा पार्स करने वाला कोड इस पर भी काम करता है। डिलीवरी स्टेटस messages इवेंट के भीतर value.statuses में आते हैं।
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?" }
}]
}
}X-EC-Signature को Node.js में कैसे जाँचें?
हेडर को t=<unix seconds>,v1=<64 hex characters> के रूप में पढ़ें। जो t आपकी घड़ी से 5 मिनट से ज़्यादा दूर हो, उसे अस्वीकार करें। फिर t, एक डॉट और रॉ बॉडी पर HMAC-SHA256 की गणना करें, जिसकी कुंजी पूरा फ़ॉरवर्ड सीक्रेट UTF-8 टेक्स्ट के रूप में है, और परिणाम की तुलना v1 से constant time में करें। इसके बाद ही JSON पार्स करें। 10 सेकंड के भीतर 2xx से जवाब दें और काम बाद में करें, और स्वीकार की गई डिलीवरी के id याद रखें, ताकि कोई दोबारा कोशिश दो बार प्रोसेस न हो।
// 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);Python में इसे कैसे जाँचें?
मानक लाइब्रेरी के साथ वही चार जाँच: हेडर के लिए सख़्त पैटर्न, t की आयु, t, डॉट और रॉ बाइट्स पर hmac.new, और hmac.compare_digest। FastAPI में रॉ बॉडी await request.body() से आती है, और BackgroundTasks 200 भेजे जाने के बाद काम चलाता है। Flask में request.get_data() इस्तेमाल करें, और बॉडी को json.dumps से कभी दोबारा न बनाएँ, क्योंकि Python के डिफ़ॉल्ट separators में स्पेस जुड़ जाते हैं और सिग्नेचर मेल नहीं खाता।
# 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)असफल डिलीवरी दोबारा कैसे भेजी जाती हैं?
फ़ॉरवर्ड तब डिलीवर माना जाता है जब आपका एंडपॉइंट 10 सेकंड के भीतर किसी भी 2xx स्टेटस से जवाब दे। बाकी कुछ भी, जैसे टाइमआउट, 4xx, 5xx या रीडायरेक्ट (जिसका पालन नहीं होता), अगले प्रयास को लगभग 1 मिनट, 5 मिनट, 30 मिनट, 2 घंटे, 6 घंटे और 24 घंटे बाद के लिए शेड्यूल करता है, और सातवें प्रयास के बाद डिलीवरी छोड़ दी जाती है। हर प्रयास नए t के साथ फिर से साइन होता है, और यूआरएल सार्वजनिक HTTPS होना चाहिए, जिसे सेव करते समय और हर भेजने से पहले जाँचा जाता है। डिलीवरी सबसे पुरानी पहले जाती है, पर दोबारा कोशिश की गई डिलीवरी नई वाली के बाद पहुँच सकती है, इसलिए Meta के timestamps से क्रम लगाएँ।
डायरेक्ट डेस्टिनेशन पर दोबारा कोशिश Meta करता है: HTTP 200 के अलावा कुछ भी 7 दिन तक घटती आवृत्ति से दोबारा भेजा जाता है, और ये दोबारा कोशिशें मैसेज दोहरा सकती हैं। दोनों मोड में Meta के मैसेज id पर डुप्लिकेट हटाएँ, क्योंकि Meta द्वारा दोबारा भेजा गया change एक नए डिलीवरी id के साथ फिर से फ़ॉरवर्ड होता है।
डायरेक्ट एंडपॉइंट को कैसे पता चलता है कि POST असली है?
X-Hub-Signature-256 से नहीं। Meta उस ऐप के app secret से साइन करता है जिसका सब्सक्रिप्शन है, जो यहाँ जुड़े नंबर के लिए easyCoexistence का है और साझा नहीं किया जाता, इसलिए आपके अपने Meta app secret से उस हेडर की जाँच असली डिलीवरी को अस्वीकार कर देगी। verify token केवल एक बार, Meta के GET handshake के दौरान, एंडपॉइंट को साबित करता है। इसके बजाय जो काम करता है:
- कॉलबैक यूआरएल पाथ में 32 या ज़्यादा रैंडम अक्षर रखें और उनके बिना आने वाले अनुरोध अस्वीकार करें; बदलने के लिए नया यूआरएल सेव करें।
- एक सामान्य रिसीवर इस्तेमाल करें, जैसे n8n Webhook node, न कि WhatsApp trigger जो आपका अपना Meta ऐप माँगता है।
- नंबर के टोकन से Meta से media को id के आधार पर डाउनलोड करें, ताकि नकली id बस विफल हो जाए।
- सेल्फ-होस्टेड सर्वर पर चाहें तो केवल Meta के नेटवर्क की अनुमति दें, यानी AS32934 द्वारा घोषित रूट।
- या Forward URL के साथ मैनेज्ड पर स्विच करें, जहाँ X-EC-Signature हर POST को साबित करता है।
आम गड़बड़ियाँ
- Meta के envelope के लिए लिखा कोड बिना बदले Forward URL पर लगाना। एक फ़ॉरवर्ड में एक change होता है: event और value पढ़ें, object, entry और changes नहीं।
- X-EC-Event के statuses होने का इंतज़ार करना। डिलीवरी स्टेटस messages इवेंट के भीतर value.statuses में आते हैं, और ऐप में टाइप किए गए जवाब smb_message_echoes के रूप में आते हैं।
- जवाब देने से पहले काम करना। फ़ॉरवर्ड 10 सेकंड इंतज़ार करता है, फिर वही डिलीवरी नए t के साथ लौटती है; पहले 2xx दें और कतार से प्रोसेस करें।
- मैनेज्ड पर स्विच करके मान लेना कि पुराना यूआरएल अब भी मैसेज पाता रहेगा। डायरेक्ट डेस्टिनेशन उसी पल हट जाता है; उसी set_inbound_mode कॉल में forward_url पास करें।
easyCoexistence WhatsApp Business ऐप के नंबर को Coexistence के ज़रिए Meta के Cloud API से जोड़ता है, और हर नंबर के लिए आप चुन सकते हैं कि उसके मैसेज कहाँ जाएँ: सीधे Meta से आपके सर्वर पर, या easyCoexistence के ज़रिए, ताकि ऑटोमेशन जवाब दे सकें और साइन की गई कॉपी आपके Forward URL तक पहुँचे। निगरानी और अलर्ट दोनों मोड में काम करते हैं। प्रति नंबर प्रति माह US$ 9 से घटकर US$ 0.75, जैसे-जैसे नंबर जुड़ते हैं वैसे कीमत कम होती है, और पहले 3 दिन मुफ़्त।
अक्सर पूछे जाने वाले सवाल
क्या मेरा सर्वर देख पाएगा कि ऑटोमेशन ने क्या जवाब दिया?
टेक्स्ट नहीं। Meta एपीआई से भेजे गए मैसेज को messages इवेंट के भीतर स्टेटस (sent, delivered, read) के रूप में बताता है, मैसेज id के साथ। टेक्स्ट स्वयं ऑटोमेशन के रन लॉग में है, जो Runs टैब में 30 दिन रखा जाता है, और Conversations में आपके चुने हुए समय तक।
फ़ॉरवर्ड सीक्रेट कैसे रोटेट करें?
नंबर के पेज पर New secret पर क्लिक करें, या rotate_secret को true सेट करके set_inbound_mode कॉल करें। नया सीक्रेट एक बार दिखाया जाता है और उसी क्षण से सब कुछ साइन करता है, पुरानी डिलीवरी की दोबारा कोशिशें भी, इसलिए अपना सर्वर तुरंत अपडेट करें।
क्या Forward URL को Meta के GET handshake की ज़रूरत है?
नहीं। केवल डायरेक्ट डेस्टिनेशन को Meta कॉल करता है और उसे hub.challenge वापस देना होता है। Forward URL को easyCoexistence कॉल करता है, और वह केवल साइन किए गए POST पाता है।
क्या एक नंबर का एक साथ डायरेक्ट डेस्टिनेशन और Forward URL हो सकता है?
नहीं। Forward URL केवल तभी काम करता है जब नंबर मैनेज्ड हो, और डायरेक्ट डेस्टिनेशन सेव करने पर नंबर डायरेक्ट बन जाता है। Forward URL और उसका सीक्रेट सुरक्षित रहते हैं, इसलिए मैनेज्ड पर लौटने पर फ़ॉरवर्डिंग फिर शुरू हो जाती है।
पढ़ना जारी रखें
शुरू करने के लिए तैयार हैं?
WhatsApp Coexistence को महीनों में नहीं, मिनटों में कॉन्फ़िगर करें। ऐप्लिकेशन मोबाइल पर काम करता रहता है।
मुफ़्त ट्रायल शुरू करेंइस तारीख को सत्यापित