वेबहुक के ज़रिए ग्राहकों के WhatsApp मैसेज और सोशल कमेंट कैसे प्राप्त करें
हर कनेक्शन को easyCoexistence के Partner एपीआई के ज़रिए अपने ग्राहकों के WhatsApp मैसेज या सोशल कमेंट के लिए अपना अलग वेबहुक मिलता है। WhatsApp मैसेज Meta से सीधे उस यूआरएल पर जाते हैं, और इन पर आपके पास मौजूद सीक्रेट के बजाय Tech Provider ऐप के सीक्रेट से साइन होता है, इसलिए यूआरएल पाथ में रखा लंबा रैंडम सीक्रेट इन्हें प्रमाणित करता है। Instagram और Facebook के कमेंट व DMs, और TikTok के कमेंट, आते ही आगे भेजे जाते हैं, हर खाते के अपने सीक्रेट से X-EC-Signature के साथ साइन किए हुए।
Meta की अधिकतम लंबाई, वैकल्पिक कॉलबैक यूआरएल के लिए जो किसी नंबर के मैसेज आपके एंडपॉइंट तक पहुँचाता है।
वह अवधि जिसके बाद Meta उस WhatsApp वेबहुक को दोबारा भेजता रहता है जिसे आपके एंडपॉइंट ने स्वीकार नहीं किया, घटती आवृत्ति के साथ, जिससे डुप्लिकेट आ सकते हैं।
Meta का नेटवर्क; उसके लिए whois रूट लुकअप उन पतों की सूची देते हैं जहाँ से WhatsApp वेबहुक आते हैं, और Meta इन्हें समय-समय पर बदलता है।
Meta के अनुसार WhatsApp वेबहुक पेलोड का सबसे बड़ा आकार।
वह उम्र जिसके बाद आगे भेजे गए इवेंट का साइन किया हुआ टाइमस्टैम्प अस्वीकार कर देना चाहिए, और HMAC की तुलना constant time में होती है।
किसी कनेक्शन को अपना अलग डेस्टिनेशन कैसे मिलता है?
हर संसाधन के लिए एक कॉल से। WhatsApp नंबर के लिए PUT /connections/{id}/webhook पर url और verify_token भेजें, या connect session पर वही जोड़ी webhook_url और webhook_verify_token के रूप में दें, ताकि नंबर पहले मिनट से ही आपके पास रूट हो। सोशल खाते के लिए जुड़ जाने के बाद PUT /channels/{id}/webhook पर url भेजें। दोनों में से किसी भी पर url को null करने से डिलीवरी बंद हो जाती है। दोनों रास्ते इस बात में अलग हैं कि डिलीवरी कौन करता है और आप प्रमाणीकरण कैसे करते हैं:
| WhatsApp number | Instagram, Facebook, TikTok | |
|---|---|---|
| Set with | webhook_url on the session, or PUT /connections/{id}/webhook | PUT /channels/{id}/webhook, after it connects |
| Delivered by | Meta, straight to your URL | easyCoexistence, forwarding each event as it arrives |
| Body | Meta's webhook, unchanged | platform, account_id, external_id and the network's entry |
| Authenticate | A long random secret in the URL path | X-EC-Signature, keyed with the account's secret |
| Retries | Meta's own, for up to 7 days | None: one attempt |
| Copy kept | None | None |
आप किसी नंबर के मैसेज अपने एंडपॉइंट पर कैसे भेजें?
उसे एक HTTPS यूआरएल दें जिसके path में लंबा रैंडम सीक्रेट हो, साथ में एक वेरिफ़ाई टोकन: connect session पर webhook_verify_token, 8 से 200 अक्षर का, या PUT पर verify_token। Meta तुरंत यूआरएल की जाँच hub.mode=subscribe, hub.verify_token और hub.challenge वाले GET से करता है, और टोकन मेल खाने पर आपके एंडपॉइंट को hub.challenge की वैल्यू लौटानी होगी। यदि यह हैंडशेक विफल हो जाए, तो PUT 502 meta_rejected लौटाता है और Meta का अपना संदेश देता है; connect session पर नंबर फिर भी जुड़ जाता है, और session का last_error बताता है कि यूआरएल क्यों लागू नहीं हुआ।
import express from "express";
import { timingSafeEqual } from "node:crypto";
const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();
function same(a, b) {
const x = Buffer.from(String(a)), y = Buffer.from(String(b));
return x.length === y.length && timingSafeEqual(x, y);
}
// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
return res.sendStatus(403);
}
res.send(req.query["hub.challenge"]);
});
// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
res.sendStatus(200); // answer first: Meta retries for up to 7 days
enqueue(req.body); // deduplicate on each message id before acting
});आप Meta का सिग्नेचर क्यों नहीं जाँच सकते, और उसकी जगह क्या है?
Meta हर डिलीवरी को X-Hub-Signature-256 से साइन करता है, जो पेलोड का HMAC-SHA256 है और प्राप्त करने वाले ऐप के App Secret से बना होता है। आपके ग्राहकों के नंबरों के लिए वह ऐप easyCoexistence का Tech Provider ऐप है, और उसका सीक्रेट कभी साझा नहीं होता, इसलिए आपकी ओर से यह हेडर सत्यापित नहीं हो सकता। इसकी जगह यूआरएल पाथ में रखा लंबा रैंडम सीक्रेट क्रेडेंशियल है: उसकी तुलना constant time में करें और बाकी सब अस्वीकार करें। दूसरी परत के रूप में, Meta के AS32934 के रजिस्टर्ड रूट्स की allowlist रखें और उस सूची को ताज़ा करते रहें, क्योंकि Meta अपने IP पते समय-समय पर बदलता है।
कौन से WhatsApp वेबहुक आपके यूआरएल तक पहुँचते हैं?
वे फ़ील्ड जो Meta किसी वैकल्पिक कॉलबैक यूआरएल में भेजने देता है: messages, ग्राहकों के भेजे मैसेज और आपके भेजे गए मैसेज की स्थिति के लिए; smb_message_echoes, उन मैसेज के लिए जो कारोबार WhatsApp Business ऐप से भेजता है; और एक बार होने वाले इंपोर्ट का history और smb_app_state_sync। Meta कभी टेम्पलेट वेबहुक, या account_update जैसे अकाउंट वेबहुक, किसी ओवरराइड पर नहीं भेजता। वे easyCoexistence के कॉलबैक पर जाते हैं, इसीलिए टेम्पलेट रिव्यू पोलिंग से पढ़ा जाता है और ड्रॉप एक स्टेटस इवेंट के रूप में आपके पास आता है।
- डेस्टिनेशन WhatsApp Business Account पर सेट होता है, इसलिए एक ही अकाउंट के दो नंबर उसे साझा करते हैं: value.metadata.
phone_number_idसे रूट करें। - मीडिया एक ID के रूप में आता है; फ़ाइल को ग्राहक के टोकन से Meta पर जाकर लाएँ, जो credentials कॉल से मिलता है।
- पेलोड 3 MB तक हो सकते हैं, इसलिए उससे नीचे सेट की गई किसी भी body-size सीमा को बढ़ाएँ।
आगे भेजे गए सोशल इवेंट का रूप कैसा होता है?
एक POST, Content-Type application/json और X-EC-Signature हेडर के साथ, जिसमें चार keys हैं: platform; account_id, वह channel ID जो Partner एपीआई इस्तेमाल करता है; external_id, नेटवर्क पर खाते का ID; और entry। Instagram और Facebook के लिए entry Meta का वेबहुक entry जैसा का तैसा है, कमेंट और मेंशन के लिए changes और DMs के लिए messaging के साथ। TikTok के लिए इसमें comment.update इवेंट है, उसका content पार्स किया हुआ, और comment_id, video_id और parent_comment_id स्ट्रिंग के रूप में, ताकि 64-bit ID गोल न हों।
- Instagram खाते कमेंट, मैसेज और मेंशन के लिए सब्सक्राइब होते हैं; Facebook Pages feed, messages और mention के लिए; TikTok comment.update भेजता है।
- easyCoexistence YouTube या LinkedIn से कोई कमेंट इवेंट नहीं पाता: उनके PUT 400
not_supportedलौटाते हैं, और उनके कमेंट हर नेटवर्क के API से credentials के साथ पढ़े जाते हैं। - आगे भेजे गए इवेंट में X-EC-Event या X-EC-Delivery हेडर नहीं होता, इसलिए नेटवर्क के अपने ID से डुप्लिकेट हटाएँ, जैसे कमेंट ID या मैसेज mid।
{
"platform": "instagram",
"account_id": "<CHANNEL_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793440800,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}X-EC-Signature को कदम-दर-कदम कैसे सत्यापित करें?
PUT /channels/{id}/webhook द्वारा लौटाए गए signing_secret से, जो केवल एक बार दिखता है और उस खाते के लिए अनोखा होता है। हेडर t=<unix>,v1=<hex> के रूप में आता है। फिर हर डिलीवरी के लिए:
- कच्चे request body को बाइट्स के रूप में पढ़ें, किसी भी JSON पार्सिंग से पहले।
- हेडर को कॉमा पर बाँटें: t में सेकंड में Unix समय, और v1 में hex digest।
- अगर t आपकी घड़ी से 5 मिनट से ज़्यादा दूर हो, तो डिलीवरी अस्वीकार करें।
- t, एक बिंदु (.) और कच्चे body पर HMAC-SHA256 निकालें, उस खाते के सीक्रेट से की गई, hex में।
- उसकी तुलना v1 से constant time में करें, फिर 2xx से जवाब दें और काम queue में डालें।
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database
app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
);
if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
return res.sendStatus(401); // missing or stale timestamp
}
let event;
try {
event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
} catch {
return res.sendStatus(400);
}
const secret = secrets.get(event.account_id);
if (!secret || !sig.v1) return res.sendStatus(401);
const expected = createHmac("sha256", secret)
.update(sig.t + ".")
.update(req.body) // the raw bytes, exactly as they arrived
.digest("hex");
if (expected.length !== sig.v1.length ||
!timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
return res.sendStatus(401);
}
res.sendStatus(204); // one attempt and no retries: acknowledge, then work
enqueue(event);
});जब कोई डेस्टिनेशन सेट न हो तो क्या होता है?
कुछ भी आप तक नहीं पहुँचता, और न ही बाद में भेजने के लिए कुछ रुका रहता है। जिस नंबर का webhook_url नहीं है, वह easyCoexistence के कॉलबैक पर चला जाता है, जहाँ उसके मैसेज बिना सहेजे गिरा दिए जाते हैं, और उसे चैट इतिहास का इंपोर्ट नहीं मिलता, जो तभी माँगा जाता है जब डेस्टिनेशन मौजूद हो। जिस सोशल खाते का डेस्टिनेशन नहीं है, वह आगे नहीं भेजा जाता: उसके इवेंट फिर भी easyCoexistence के ऐप तक पहुँचते हैं, पर आपके लिए कुछ भी रोका नहीं जाता। ट्रैफ़िक की ज़रूरत पड़ने से पहले हर डेस्टिनेशन सेट कर लें।
जब कनेक्शन टूटता है या हटाया जाता है तो डेस्टिनेशन का क्या होता है?
नंबर अपना डेस्टिनेशन रिकॉर्ड में रखता है। जब टूटा हुआ नंबर दोबारा जुड़ता है, तो easyCoexistence आपका यूआरएल Meta के साथ फिर से सेट करता है, और निलंबित नंबर वापस आने पर भी यही होता है। सोशल खाता हटाने पर उसका डेस्टिनेशन और सीक्रेट साफ़ हो जाते हैं, इसलिए दोबारा जुड़ने के बाद PUT /channels/{id}/webhook फिर से भेजें और नया सीक्रेट सहेजें। यह PUT जब भी यूआरएल के साथ बुलाया जाए, नया सीक्रेट जारी करता है, और पुराना तुरंत साइन करना बंद कर देता है।
कैसे कॉन्फ़िगर करें
- Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
- Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
- Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
- Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.
आम गड़बड़ियाँ
- अपने ग्राहकों के WhatsApp डिलीवरी पर X-Hub-Signature-256 जाँचना। Meta उसे easyCoexistence के ऐप सीक्रेट से बनाता है, जो कभी साझा नहीं होता, इसलिए जाँच पास नहीं हो सकती; यूआरएल पाथ के सीक्रेट से प्रमाणित करें।
- पार्स किए गए JSON पर X-EC-Signature सत्यापित करना। HMAC कच्चे body को बाइट-दर-बाइट कवर करता है, और उसे दोबारा serialize करने से बाइट्स बदल जाते हैं, इसलिए पार्स करने से पहले सत्यापित करें।
- हर चैनल के लिए एक ही सीक्रेट इस्तेमाल करना। हर सोशल खाता अपने सीक्रेट से साइन करता है, और स्टेटस इवेंट एक अलग सीक्रेट से, इसलिए सीक्रेट account_id से खोजें।
- आगे भेजे गए इवेंट का जवाब देने से पहले धीमा काम करना। वह एक बार भेजा जाता है, आपके जवाब के लिए 8 सेकंड रुकता है और कभी दोबारा नहीं भेजा जाता, इसलिए पहले 2xx लौटाएँ और बाद में प्रोसेस करें।
easyCoexistence हर ग्राहक नंबर के मैसेज Meta से सीधे आपके सर्वर तक रूट करता है, और Instagram व Facebook के कमेंट व DMs तथा TikTok के कमेंट आते ही आपके एंडपॉइंट पर हर खाते के सीक्रेट से साइन करके भेजता है, बिना कोई कॉपी रखे, और हर कनेक्शन 24/7 मॉनिटर होता है। प्रति कनेक्शन प्रति माह US$ 9 से US$ 0.75 तक, कनेक्शन बढ़ने के साथ घटते हुए, पहले 3 दिन मुफ़्त।
अक्सर पूछे जाने वाले सवाल
क्या मैं अपने ग्राहकों के WhatsApp मैसेज पर Meta का सिग्नेचर जाँच सकता हूँ?
नहीं। Meta उन्हें easyCoexistence के Tech Provider ऐप के सीक्रेट से साइन करता है, जो कभी साझा नहीं होता। अपने यूआरएल पाथ के लंबे रैंडम सीक्रेट से प्रमाणित करें, और वैकल्पिक रूप से Meta की IP रेंज से।
क्या YouTube और LinkedIn कनेक्शन कमेंट इवेंट आगे भेजते हैं?
नहीं। easyCoexistence दोनों में से किसी से कमेंट इवेंट नहीं पाता, इसलिए PUT /channels/{id}/webhook 400 not_supported लौटाता है। उनके कमेंट हर नेटवर्क के API से, चैनल के credentials के साथ पढ़ें।
अगर मेरा सर्वर बंद हो तो आगे भेजे गए सोशल इवेंट दोबारा भेजे जाते हैं?
नहीं। हर इवेंट एक बार भेजा जाता है और उसकी कोई कॉपी नहीं रखी जाती। WhatsApp डिलीवरी अलग है, क्योंकि Meta स्वयं उन्हें 7 दिन तक दोबारा भेजता है।
क्या मैसेज easyCoexistence से होकर गुज़रते हैं?
WhatsApp पर नहीं: Meta किसी नंबर के मैसेज सीधे उस वेबहुक पर भेजता है जो आपने सेट किया है। सोशल नेटवर्क के कमेंट और DMs आते ही आपके एंडपॉइंट पर हर खाते के सीक्रेट से साइन करके आगे भेजे जाते हैं, बिना कोई कॉपी रखे।
पढ़ना जारी रखें
दो मिनट में अपना पहला चैनल कनेक्ट करें।
किसी प्लैटफ़ॉर्म की समीक्षा का इंतज़ार नहीं। WhatsApp, Instagram, TikTok या कोई और चैनल कनेक्ट करें, फिर अपने AI से पोस्ट करने, जवाब देने या रिपोर्ट बनाने को कहें और उसे काम करते देखें।
- 3 दिन मुफ़्त
- कभी भी रद्द करें
- सिर्फ़ आधिकारिक एपीआई
- 24/7 निगरानी
इस तारीख को सत्यापित