WhatsApp মেসেজ কীভাবে আপনার সার্ভারে পৌঁছায়: সরাসরি বা ম্যানেজড মোড, এবং স্বাক্ষর যাচাই
easyCoexistence-এর মাধ্যমে সংযুক্ত প্রতিটি নম্বরের একটি ইনকামিং মোড থাকে। সরাসরি আপনার সিস্টেমে (ডিরেক্ট): Meta তার ওয়েবহুক আপনার HTTPS এন্ডপয়েন্টে পাঠায়, URL-এর ভেতরের একটি সিক্রেটই পরিচয়পত্র, এবং অটোমেশন বন্ধ থাকে। easyCoexistence-এর মাধ্যমে (ম্যানেজড): Meta easyCoexistence-এ ডেলিভার করে, অটোমেশন উত্তর দিতে পারে, এবং একটি ঐচ্ছিক Forward URL পায় Meta-র মূল মান ও সংযোগের বিবরণ, যা X-EC-Signature দিয়ে সই করা থাকে, যাতে আপনি যাচাই করতে পারেন।
প্রতিটি ফরওয়ার্ড করা ডেলিভারিতে চেষ্টা হয় 1 মিনিট, 5 মিনিট, 30 মিনিট, 2 ঘণ্টা, 6 ঘণ্টা ও 24 ঘণ্টা ব্যবধানে, মোট প্রায় 33 ঘণ্টা।
প্রতিটি ফরওয়ার্ড চেষ্টা 2xx উত্তরের জন্য কতক্ষণ অপেক্ষা করে, তারপর তা ব্যর্থ গণ্য হয়।
স্বাক্ষরের t-এর বয়সের প্রস্তাবিত সীমা; রিট্রাইও নতুন করে সই হয়, তাই বৈধ ডেলিভারি সীমার ভেতরে থাকে।
সরাসরি ওয়েবহুক HTTP 200 ছাড়া যা কিছু পায়, Meta কতক্ষণ তা রিট্রাই করে; এতে মেসেজ আবার আসতে পারে।
ইতিহাসের অংশসহ Meta-র পাঠানো সবচেয়ে বড় ওয়েবহুক পেলোড।
ম্যানেজড নম্বরের জন্য রান লগ, মেসেজ ও উত্তরের টেক্সটসহ; মেসেজের টেক্সট নিজে 30, 90 বা 365 দিন রাখা হয়, আপনার পছন্দমতো।
সরাসরি ও ম্যানেজড-এর পার্থক্য কী?
Meta নম্বরের মেসেজ-ওয়েবহুক কোথায় ডেলিভার করে। ম্যানেজড, যা Through easyCoexistence হিসেবে দেখানো হয়, মানে Meta easyCoexistence-এ ডেলিভার করে, easyCoexistence Meta-র সই যাচাই করে, আপনার অটোমেশন চালায়, Conversations-এর জন্য চ্যাটগুলো রাখে এবং আপনি Forward URL সেট করলে প্রতিটি Meta পরিবর্তন আপনাকে পাঠায়, যা শুধু আপনার কাছে থাকা একটি সিক্রেট দিয়ে সই করা। সরাসরি, যা Straight to your system হিসেবে দেখানো হয়, মানে easyCoexistence নম্বরের WhatsApp Business Account-এ আপনার HTTPS এন্ডপয়েন্টকে ওয়েবহুক ওভাররাইড হিসেবে সেট করে, তাই 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। 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 পরিবর্তন, মোড়ানো অবস্থায়, 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> ফর্মে। আপনার ঘড়ি থেকে 5 মিনিটের বেশি দূরের t প্রত্যাখ্যান করুন, 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-এর ডিফল্ট সেপারেটরে স্পেস যোগ হয় এবং সই আর মেলে না।
# 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 node, নিজের Meta অ্যাপ আশা করে এমন WhatsApp trigger নয়।
- নম্বরের টোকেন দিয়ে Meta থেকে আইডি ধরে মিডিয়া ডাউনলোড করুন, যাতে জাল আইডি শুধু ব্যর্থ হয়।
- সেলফ-হোস্টেড সার্ভারে ঐচ্ছিকভাবে শুধু Meta-র নেটওয়ার্ক অনুমোদন করুন, অর্থাৎ AS32934 যে রুটগুলো ঘোষণা করে।
- অথবা Forward URL সহ ম্যানেজড মোডে যান, যেখানে X-EC-Signature প্রতিটি POST প্রমাণ করে।
সাধারণ ভুলগুলো
- Meta-র এনভেলপের জন্য লেখা কোড অপরিবর্তিত 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 পাঠানোগুলো স্ট্যাটাস হিসেবে (sent, delivered, read) messages ইভেন্টের ভেতরে মেসেজ আইডিসহ জানায়; টেক্সট নিজে অটোমেশনের রান লগে থাকে, যা 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 সেট আপ করুন। ফোনে অ্যাপটি কাজ করতে থাকে।
ফ্রি ট্রায়াল শুরু করুনযাচাই করা হয়েছে