WhatsApp پیغام آپ کے سرور تک کیسے پہنچتے ہیں: ڈائریکٹ یا مینیج، اور دستخط کی تصدیق
easyCoexistence کے ذریعے جڑے ہر نمبر کا ایک ان باؤنڈ موڈ ہوتا ہے۔ آپ کے سسٹم پر سیدھا (ڈائریکٹ): Meta اپنے ویب ہکس آپ کے HTTPS اینڈ پوائنٹ پر بھیجتا ہے، URL میں موجود ایک سیکرٹ ہی کریڈینشل ہے، اور آٹومیشنز بند ہوتی ہیں۔ easyCoexistence کے ذریعے (مینیج شدہ): Meta easyCoexistence کو بھیجتا ہے، آٹومیشنز جواب دے سکتی ہیں، اور ایک اختیاری Forward URL کو Meta کی اصل ویلیو اور کنکشن کی تفصیلات ملتی ہیں، جن پر X-EC-Signature سے دستخط ہوتے ہیں تاکہ آپ تصدیق کر سکیں۔
ہر فارورڈ شدہ ڈیلیوری کے لیے کوششیں، 1 منٹ، 5 منٹ، 30 منٹ، 2 گھنٹے، 6 گھنٹے اور 24 گھنٹے کے وقفوں پر، کل تقریباً 33 گھنٹے تک۔
ہر فارورڈ کوشش کتنی دیر 2xx کا انتظار کرتی ہے اس سے پہلے کہ اسے ناکام شمار کیا جائے۔
دستخط کے t کی عمر پر تجویز کردہ حد؛ دوبارہ کوششوں پر دوبارہ دستخط ہوتے ہیں، اس لیے اصل ڈیلیوریاں اسی حد کے اندر رہتی ہیں۔
Meta براہ راست ویب ہک کو کتنی دیر دوبارہ بھیجتا ہے جس کا جواب HTTP 200 کے سوا کچھ بھی ہو، اور یہ پیغامات دہرا سکتا ہے۔
Meta کا بھیجا گیا سب سے بڑا ویب ہک پے لوڈ، ہسٹری کے حصوں سمیت۔
مینیج نمبر کے لیے رکھے گئے رن لاگز، پیغام اور جواب کے متن کے ساتھ؛ پیغام کا متن خود 30، 90 یا 365 دن تک رکھا جاتا ہے، آپ کی مرضی۔
ڈائریکٹ اور مینیج میں کیا فرق ہے؟
یہ طے کرتا ہے کہ Meta نمبر کے پیغامات کے ویب ہکس کہاں پہنچاتا ہے۔ مینیج، جو 'easyCoexistence کے ذریعے' کے طور پر دکھایا جاتا ہے، میں Meta easyCoexistence کو بھیجتا ہے، جو Meta کے دستخط کی جانچ کرتا ہے، آپ کی آٹومیشنز چلاتا ہے، Conversations کے لیے چیٹس رکھتا ہے، اور اگر آپ Forward URL سیٹ کریں تو ہر Meta تبدیلی ایسے دستخط کے ساتھ آپ کو بھیجتا ہے جس کا سیکرٹ صرف آپ کے پاس ہو۔ ڈائریکٹ، جو 'آپ کے سسٹم پر سیدھا' کے طور پر دکھایا جاتا ہے، میں easyCoexistence آپ کا HTTPS اینڈ پوائنٹ نمبر کے WhatsApp Business Account پر ویب ہک اووررائیڈ کے طور پر سیٹ کرتا ہے، اس لیے Meta سیدھا آپ کو پوسٹ کرتا ہے اور پیغامات easyCoexistence تک کبھی نہیں پہنچتے۔
نگرانی کے پیچھے آپریشنل ویب ہکس، جیسے account_update اور معیار کی تبدیلیاں، دونوں موڈز میں 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۔ اپنے ویب ہک پر آنے والے میسجز روٹ کریں کارڈ میں، یا 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 کی ایک تبدیلی ہوتی ہے، جو Meta کے object، entry اور changes والے لفافے کے بجائے ایک ریپ شدہ شکل میں ہوتی ہے۔ id ڈیلیوری کی شناخت ہے، جو X-EC-Delivery میں دہرایا جاتا ہے اور دوبارہ کوششوں میں یکساں رہتا ہے۔ event Meta کے فیلڈ کا نام ہے، یعنی messages، smb_message_echoes، history یا smb_app_state_sync، جو X-EC-Event میں دہرایا جاتا ہے۔ received_at وہ وقت ہے جب easyCoexistence نے Meta سے تبدیلی حاصل کی، 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?" }
}]
}
}Node.js میں X-EC-Signature کی تصدیق کیسے کریں؟
ہیڈر کو t=<unix seconds>,v1=<64 hex characters> کی شکل میں پڑھیں۔ اگر t آپ کی گھڑی سے 5 منٹ سے زیادہ دور ہو تو رد کریں۔ پھر t، ایک ڈاٹ اور خام باڈی پر HMAC-SHA256 کا حساب لگائیں، جس کی کلید پوری فارورڈ سیکرٹ ہو، UTF-8 متن کے طور پر، اور نتیجے کا v1 سے کانسٹنٹ ٹائم میں موازنہ کریں۔ اس کے بعد ہی JSON پارس کریں۔ 10 سیکنڈ کے اندر 2xx جواب دیں اور کام بعد میں کریں، اور قبول شدہ ڈیلیوری آئی ڈیز یاد رکھیں تاکہ دوبارہ کوشش دو بار پروسیس نہ ہو۔
// 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 کے ساتھ دوبارہ دستخط ہوتی ہے، اور URL عوامی HTTPS ہونا چاہیے، جو محفوظ کرتے وقت اور ہر بھیجنے سے پہلے دوبارہ جانچا جاتا ہے۔ ڈیلیوریاں سب سے پرانی پہلے جاتی ہیں، لیکن دوبارہ کی گئی ڈیلیوری نئی ڈیلیوریوں کے بعد پہنچ سکتی ہے، اس لیے Meta کے ٹائم اسٹیمپ کے مطابق ترتیب دیں۔
ڈائریکٹ منزل پر دوبارہ کوشش Meta کرتا ہے: HTTP 200 کے علاوہ کوئی بھی جواب 7 دن تک کم ہوتی رفتار سے دوبارہ بھیجا جاتا ہے، اور یہ دوبارہ کوششیں پیغام دہرا سکتی ہیں۔ دونوں موڈز میں Meta کی میسج آئی ڈی پر ڈپلیکیٹ ہٹائیں، کیونکہ جس تبدیلی کو Meta دوبارہ بھیجتا ہے وہ نئی ڈیلیوری آئی ڈی کے ساتھ دوبارہ فارورڈ ہوتی ہے۔
براہ راست اینڈ پوائنٹ کیسے جانتا ہے کہ POST اصلی ہے؟
X-Hub-Signature-256 سے نہیں۔ Meta اس ایپ کے ایپ سیکرٹ سے دستخط کرتا ہے جو سبسکرپشن کی مالک ہے، جو یہاں جڑے نمبر کے لیے easyCoexistence کی ہے اور شیئر نہیں ہوتی، اس لیے اپنے Meta ایپ سیکرٹ سے یہ ہیڈر جانچنے پر اصل ڈیلیوریاں رد ہو جاتی ہیں۔ تصدیقی ٹوکن صرف ایک بار، Meta کے GET ہینڈ شیک کے دوران، اینڈ پوائنٹ ثابت کرتا ہے۔ اس کے بجائے یہ کام کرتا ہے:
- کال بیک URL کے پاتھ میں 32 یا زیادہ بے ترتیب حروف رکھیں اور ان کے بغیر درخواستیں رد کریں؛ گردش کے لیے نیا URL محفوظ کریں۔
- ایک عام ریسیور استعمال کریں، جیسے n8n کا Webhook نوڈ، نہ کہ وہ WhatsApp ٹریگر جو آپ کی اپنی Meta ایپ مانگے۔
- نمبر کے ٹوکن سے Meta سے میڈیا کو id کے ذریعے ڈاؤن لوڈ کریں، تاکہ جعلی id بس ناکام ہو جائے۔
- خود میزبانی والے سرورز پر، اختیاری طور پر صرف Meta کے نیٹ ورک کی اجازت دیں، یعنی AS32934 کے اعلان کردہ روٹس۔
- یا Forward URL کے ساتھ مینیج پر جائیں، جہاں X-EC-Signature ہر POST ثابت کرتا ہے۔
عام غلطیاں
- Meta کے envelope کے لیے لکھا کوڈ بغیر تبدیلی کے Forward URL پر لگانا۔ ایک فارورڈ ایک ہی تبدیلی لے کر آتا ہے: event اور value پڑھیں، object، entry اور changes نہیں۔
- X-EC-Event کے statuses کا انتظار کرنا۔ ڈیلیوری اسٹیٹس messages ایونٹس کے اندر value.statuses میں آتے ہیں، اور ایپ میں ٹائپ کیے گئے جوابات smb_message_echoes کے طور پر آتے ہیں۔
- جواب دینے سے پہلے کام کرنا۔ فارورڈ 10 سیکنڈ انتظار کرتا ہے، پھر وہی ڈیلیوری نئے t کے ساتھ واپس آتی ہے؛ پہلے 2xx دیں اور قطار سے پروسیس کریں۔
- مینیج پر جانا اور فرض کرنا کہ پرانا URL اب بھی وصول کرتا ہے۔ ڈائریکٹ ڈیسٹی نیشن اسی لمحے ہٹ جاتی ہے؛ اسی set_inbound_mode کال میں forward_url دیں۔
easyCoexistence ایک WhatsApp Business ایپ نمبر کو Coexistence کے ذریعے Meta کے Cloud API سے جوڑتا ہے، اور آپ ہر نمبر کے لیے طے کرتے ہیں کہ اس کے پیغامات کہاں جائیں: براہ راست Meta سے آپ کے سرور پر، یا easyCoexistence کے ذریعے، تاکہ آٹومیشنز جواب دے سکیں اور دستخط شدہ کاپی آپ کے Forward URL تک پہنچے۔ مانیٹرنگ اور الرٹس دونوں موڈز میں کام کرتے ہیں۔ فی جڑا ہوا نمبر، فی مہینہ US$ 9 سے گھٹ کر US$ 0.75 تک، جیسے جیسے نمبر بڑھیں؛ پہلے 3 دن فری ٹرائل۔
اکثر پوچھے جانے والے سوالات
کیا میرا سرور دیکھ سکتا ہے کہ آٹومیشن نے کیا جواب دیا؟
متن نہیں۔ Meta API کے بھیجے گئے پیغامات کو messages ایونٹس کے اندر اسٹیٹس (sent، delivered، read) کے طور پر میسج آئی ڈی کے ساتھ رپورٹ کرتا ہے؛ خود متن آٹومیشن کے رن لاگ میں ہے، جو Runs ٹیب میں 30 دن تک رکھا جاتا ہے، اور Conversations میں اتنی مدت تک جو آپ نے چنی۔
فارورڈ سیکرٹ کیسے گھمائیں؟
نمبر کے صفحے پر New secret پر کلک کریں، یا rotate_secret کو true کے ساتھ set_inbound_mode کال کریں۔ نیا سیکرٹ ایک بار دکھایا جاتا ہے اور اس کے بعد سے ہر چیز پر دستخط کرتا ہے، پرانی ڈیلیوریوں کی دوبارہ کوششوں سمیت، اس لیے اپنا سرور فوراً اپ ڈیٹ کریں۔
کیا Forward URL کو Meta کا GET ہینڈ شیک درکار ہے؟
نہیں۔ صرف ڈائریکٹ منزل کو Meta کال کرتا ہے اور اسے hub.challenge واپس دینا ہوتا ہے۔ Forward URL کو easyCoexistence کال کرتا ہے اور وہ صرف دستخط شدہ POST وصول کرتا ہے۔
کیا ایک نمبر کی ایک ساتھ ڈائریکٹ منزل اور Forward URL ہو سکتی ہے؟
نہیں۔ Forward URL صرف اس وقت کام کرتا ہے جب نمبر مینیج ہو، اور ڈائریکٹ منزل محفوظ کرنے سے نمبر ڈائریکٹ ہو جاتا ہے۔ Forward URL اور اس کا سیکرٹ محفوظ رہتے ہیں، اس لیے دوبارہ مینیج پر جانے سے فارورڈنگ بحال ہو جاتی ہے۔
مزید پڑھیں
شروع کرنے کے لیے تیار ہیں؟
WhatsApp Coexistence چند منٹ میں سیٹ اپ کریں، مہینوں میں نہیں۔ ایپ فون پر کام کرتی رہتی ہے۔
فری ٹرائل شروع کریںتصدیق شدہ تاریخ