WhatsApp පණිවිඩ ඔබේ server එකට: Direct හෝ Managed, සහ X-EC-Signature සත්යාපනය
easyCoexistence හරහා සම්බන්ධ කළ සෑම අංකයකටම inbound mode එකක් ඇත. Straight to your system (direct): Meta එහි webhook ඔබේ HTTPS endpoint එකට යවයි, URL එකේ ඇති රහස් කේතය credential එකයි, සහ automation අක්රියයි. Through easyCoexistence (managed): Meta easyCoexistence වෙත යවයි, automation පිළිතුරු දිය හැක, සහ විකල්ප Forward URL එකට ලැබෙන්නේ Meta හි මුල් අගය සහ සම්බන්ධතාවයේ විස්තර, X-EC-Signature සමග අත්සන් කර, ඔබට සත්යාපනය කිරීමට.
Forward කළ delivery එකකට උත්සාහයන්, අතර 1 මිනිත්තුව, 5 මිනිත්තු, 30 මිනිත්තු, පැය 2, පැය 6 සහ පැය 24, මුළුතනින් පැය 33ක් පමණ.
සෑම forward උත්සාහයක්ම 2xx පිළිතුරක් බලා සිටින කාලය, ඊට පසු එය අසාර්ථක ලෙස ගණන් ගැනේ.
signature හි t හි වයස සඳහා යෝජිත සීමාව; retry නැවත අත්සන් කෙරෙන නිසා, සැබෑ deliveries එම සීමාව ඇතුළත පවතී.
Meta, HTTP 200 හැර වෙනත් ඕනෑම දෙයක් ලැබුණහොත් direct webhook එක නැවත උත්සාහ කරන කාලය, මේ නිසා පණිවිඩ නැවත පැමිණිය හැක.
Meta යවන විශාලතම webhook payload එකේ ප්රමාණය, history chunks ඇතුළුව.
Managed අංකයක් සඳහා තබා ගන්නා run logs, පණිවිඩ සහ පිළිතුරුවල පෙළ සමග; පණිවිඩ පෙළම දින 30, 90 හෝ 365ක් තබා ගැනේ, ඔබේ තේරීම.
Direct සහ managed අතර වෙනස කුමක්ද?
Meta අංකයේ පණිවිඩ webhooks යවන ස්ථානය. Managed, එනම් Through easyCoexistence ලෙස පෙන්වයි, Meta easyCoexistence වෙත යවයි; easyCoexistence Meta හි අත්සන පරීක්ෂා කර, ඔබේ automation ක්රියාත්මක කර, Conversations සඳහා chats තබා ගෙන, Forward URL එකක් සකස් කර ඇත්නම්, Meta හි සෑම change එකක්ම ඔබට පසුව යවයි, එය ඔබ පමණක් දන්නා රහසකින් අත්සන් කර. Direct, එනම් Straight to your system ලෙස පෙන්වයි, easyCoexistence ඔබේ HTTPS endpoint එක අංකයේ WhatsApp Business Account හි webhook override ලෙස සකසයි, එවිට Meta ඔබට කෙලින්ම POST කරයි සහ පණිවිඩ easyCoexistence වෙත කිසි විටෙකත් නොපැමිණේ.
monitoring සහ account_update, quality වෙනස්වීම් වැනි මෙහෙයුම් webhooks දෙකේම easyCoexistence සමග පවතී, එම නිසා alerts ඕනෑම ක්රමයකින් ක්රියා කරයි.
| 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 කාඩ්පත mode එක තේරීම් දෙකක් ලෙස පෙන්වයි, Through easyCoexistence සහ Straight to your system. Route incoming messages to your own webhook කාඩ්පතේ හෝ set_webhook_destination මගින් webhook destination එකක් සුරැකීම, අංකය direct බවට පත් කරයි. Through easyCoexistence තෝරා ගැනීම, Meta හි එම destination එක වහාම ඉවත් කරයි, එබැවින් ලැබීම දිගටම කරගෙන යාමට එම URL එකම Forward URL ලෙස එකතු කරන්න. අංකය managed mode එකෙන් ඉවත් වන විට පෝලිමේ ඇති forwards ඉවත් කෙරේ, සහ webhook URL නැතිව සම්බන්ධ කළ අංක managed ලෙස ආරම්භ වේ.
ඔබේ AI සහායකයෙන්, set_inbound_mode මගින් mode එක මාරු කර forward එක එක call එකකින් සකසයි, සහ forward secret එක එක් වරක් පමණක් ලබා දෙයි:
// 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
}forward කළ POST එකක අඩංගු වන්නේ කුමක්ද?
Meta හි object, entry සහ changes envelope වෙනුවට, එක් request එකකට එක Meta change එකක්, wrapped ලෙස. id යනු delivery id එකයි, X-EC-Delivery හි නැවත පෙන්වන අතර retries හරහා ස්ථාවරයි. event යනු Meta field නමයි: messages, smb_message_echoes, history හෝ smb_app_state_sync, X-EC-Event හි නැවත පෙන්වයි. received_at යනු easyCoexistence එම change එක Meta වෙතින් ලැබූ වේලාවයි, connection අංකය හඳුනාගනී, සහ value යනු Meta යැවූ ම අගයයි, එබැවින් Meta payload සඳහා ලියූ parse කරන code මෙයත් මත ක්රියා කරයි. Delivery statuses, messages events තුළ 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 සත්යාපනය කරන්නේ කෙසේද?
Header එක t=<unix තත්පර>,v1=<hex අක්ෂර 64> ලෙස කියවන්න. ඔබේ ඔරලෝසුවෙන් විනාඩි 5 කට වඩා ඈත t ප්රතික්ෂේප කරන්න, t, dot සහ raw body මත HMAC-SHA256 ගණනය කර, forward secret සම්පූර්ණයම UTF-8 පෙළ ලෙස යතුර කර, ප්රතිඵලය v1 සමග constant time තුළ සංසන්දනය කරන්න. ඉන්පසුව පමණක් JSON parse කරන්න. තත්පර 10 ඇතුළත 2xx පිළිතුරු දී වැඩ පසුව කරන්න, සහ ඔබ පිළිගත් delivery ids මතක තබාගන්න, එවිට retry එකක් දෙවරක් සකසන්නේ නැත.
// 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 හි එය සත්යාපනය කරන්නේ කෙසේද?
සම්මත library සමග එම checks හතර: header සඳහා දැඩි pattern එකක්, t හි වයස, t, dot සහ raw bytes මත hmac.new, සහ hmac.compare_digest. FastAPI හි raw body එක await request.body() මගින් ලැබේ, සහ 200 යැවූ පසු වැඩ BackgroundTasks මගින් ක්රියාත්මක වේ. Flask හි, request.get_data() භාවිත කරන්න, සහ කිසිවිට body එක json.dumps සමග නැවත ගොඩනගන්න එපා, මන්ද Python හි පෙරනිමි separators අවකාශ එකතු කරන නිසා signature නොගැලපේ.
# 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)අසාර්ථක delivery නැවත උත්සාහ කරන්නේ කෙසේද?
ඔබේ endpoint තත්පර 10 ඇතුළත ඕනෑම 2xx පිළිතුරක් දුන් විට forward එකක් delivered ලෙස ගණන් ගැනේ. වෙනත් ඕනෑම දෙයක්, timeout, 4xx, 5xx, හෝ redirect (අනුගමනය නොකෙරේ), ඊළඟ උත්සාහය විනාඩි 1, විනාඩි 5, විනාඩි 30, පැය 2, පැය 6 සහ පැය 24 කින් පසුව සැලසුම් කරයි, සහ හත්වන උත්සාහයෙන් පසු delivery එක අත්හැරේ. සෑම උත්සාහයක්ම නව t සමග නැවත අත්සන් කෙරේ, සහ URL එක සාර්වජනික HTTPS විය යුතුය, සුරකින විට සහ සෑම යැවීමකට පෙර නැවත පරීක්ෂා කෙරේ. Deliveries පැරණිම පළමුව යයි, නමුත් retry කළ එකක් නව ඒවාට පසුව පැමිණිය හැක, එබැවින් Meta හි timestamps අනුව පෙළගස්වන්න.
Direct destination එකක, retry කිරීම Meta කරයි: HTTP 200 හැර ඕනෑම දෙයක් දින 7 දක්වා අඩුවන වාරම්බයෙන් retry කෙරේ, සහ එම retries පණිවිඩ නැවත පැමිණිය හැක. දෙආකාරයෙන්ම Meta පණිවිඩ id මත deduplicate කරන්න, මන්ද Meta නැවත delivery කරන change එකක් නව delivery id එකක් යටතේ නැවත forward වේ.
Direct endpoint එකට POST එකක් සැබෑද යන්න දන්නේ කෙසේද?
X-Hub-Signature-256 මගින් නොවේ. Meta subscription හිමි app හි app secret මගින් අත්සන් කරයි, එය මෙහි සම්බන්ධ කළ අංකයක් සඳහා easyCoexistence හි වන අතර බෙදාගෙන නැත, එබැවින් එම header එක ඔබේම Meta app secret සමග පරීක්ෂා කිරීම සැබෑ deliveries ප්රතික්ෂේප කරයි. Verify token එක Meta හි GET handshake අතරතුර එක් වරක් පමණක් endpoint එක සනාථ කරයි. ඒ වෙනුවට වැඩ කරන දේ:
- Callback URL path එකේ අහඹු අක්ෂර 32 ක් හෝ වැඩි දමා, ඒවා නැති requests ප්රතික්ෂේප කරන්න; භ්රමණය කිරීමට, නව URL එකක් සුරකින්න.
- විශේෂිත WhatsApp trigger එකක් නොව, n8n Webhook node වැනි සාමාන්ය receiver එකක් භාවිත කරන්න, එය ඔබේම Meta app එකක් බලාපොරොත්තු වේ.
- අංකයේ token සමග Meta වෙතින් media id මගින් බාගන්න, එවිට ව්යාජ id එකක් සරලව අසාර්ථක වේ.
- ස්වයං-සත්කාරක servers මත, විකල්පයෙන් Meta ජාලයේ මාර්ග පමණක් අවසර දෙන්න, AS32934 විසින් ප්රකාශිත මාර්ග.
- නැතහොත් Forward URL සමග managed වෙත මාරු වන්න, එහිදී X-EC-Signature සෑම POST එකක්ම සනාථ කරයි.
සාමාන්ය වැරදි
- Meta හි envelope සඳහා ලියූ code, Forward URL එකට වෙනස් නොකර යොමු කිරීම. forward එකක් එක change එකක් පමණක් රැගෙන යයි: object, entry සහ changes නොව, event සහ value කියවන්න.
- X-EC-Event statuses වේ යැයි බලා සිටීම. Delivery statuses, messages events තුළ, value.statuses තුළ පැමිණේ, සහ app තුළ ටයිප් කළ පිළිතුරු smb_message_echoes ලෙස පැමිණේ.
- පිළිතුරු දීමට පෙර වැඩ කිරීම. forward එක තත්පර 10 ක් බලා සිටී, ඉන්පසු එම delivery එක නව t සමග නැවත පැමිණේ; පළමුව 2xx පිළිතුරු දී queue එකෙන් ක්රියාත්මක කරන්න.
- Managed වෙත මාරු වී පැරණි URL එක තවමත් ලබන බව උපකල්පනය කිරීම. Direct destination එක එම මොහොතේ ඉවත් වේ; එම set_inbound_mode call එකේම forward_url ලබා දෙන්න.
easyCoexistence WhatsApp Business app අංකයක් Coexistence හරහා Meta හි Cloud API වෙත සම්බන්ධ කරයි, සහ අංකයට අනුව පණිවිඩ යන ස්ථානය ඔබට තේරීමට ඉඩ දෙයි: Meta වෙතින් කෙලින්ම ඔබේ server වෙත, නැතහොත් easyCoexistence හරහා, automation පිළිතුරු දිය හැකි අතර අත්සන් කළ පිටපතක් ඔබේ Forward URL වෙත ළඟා වේ. Monitoring සහ alerts ආකාර දෙකේම ක්රියා කරයි. අංකයකට මාසිකව US$ 9 සිට US$ 0.75 දක්වා, අංක එකතු කරන විට අඩු වේ, පළමු දින 3 නොමිලේ.
නිතර අසන ප්රශ්න
automation පිළිතුරු දුන් දේ මගේ server එකට පෙනේද?
පෙළ නොවේ. Meta API යැවීම් statuses ලෙස (sent, delivered, read) messages events තුළ වාර්තා කරයි, පණිවිඩ id සමග; පෙළම automation හි run log එකේ ඇත, එය Runs tab එකේ දින 30 ක් ද, ඔබ තෝරාගත් කාලය සඳහා Conversations තුළ ද තබා ගැනේ.
forward secret භ්රමණය කරන්නේ කෙසේද?
අංකයේ පිටුවේ New secret ක්ලික් කරන්න, හෝ rotate_secret true සමග set_inbound_mode call කරන්න. නව secret එක එක් වරක් පෙන්වන අතර ඊට පසුව සෑම දෙයක්ම අත්සන් කරයි, පැරණි deliveries වල retries ද ඇතුළුව, එබැවින් ඔබේ server වහාම යාවත්කාලීන කරන්න.
Forward URL එකට Meta හි GET handshake අවශ්යද?
නැත. Direct destination එකක් පමණක් Meta විසින් ඇමතෙන අතර hub.challenge ප්රතිධ්වනි කළ යුතුය. Forward URL එකක් easyCoexistence විසින් ඇමතෙන අතර අත්සන් කළ POST පමණක් ලබයි.
අංකයකට එකවර direct destination එකක් සහ Forward URL එකක් තිබිය හැකිද?
නැත. Forward URL එක අංකය managed වන විට පමණක් ක්රියා කරයි, සහ direct destination එකක් සුරකීම එය direct බවට පත් කරයි. Forward URL සහ එහි secret තබා ගැනේ, එබැවින් managed වෙත ආපසු මාරු වීමෙන් forwarding නැවත ආරම්භ වේ.
තවදුරටත් කියවන්න
ආරම්භ කිරීමට සූදානම්ද?
WhatsApp Coexistence මිනිත්තු කිහිපයකින් සකසන්න, මාස ගණනකින් නොව. යෙදුම දුරකථනයේ දිගටම ක්රියා කරයි.
නොමිලේ trial කාලය ආරම්භ කරන්නසත්යාපනය කළේ