Πώς φτάνουν τα μηνύματα WhatsApp στον διακομιστή σας: άμεσα ή διαχειριζόμενα, και επαλήθευση της υπογραφής
Κάθε αριθμός που συνδέεται μέσω του easyCoexistence έχει έναν τρόπο εισερχόμενων μηνυμάτων. Απευθείας στο σύστημά σας (άμεσος τρόπος): η Meta στέλνει τα webhooks της στο HTTPS endpoint σας, ένα μυστικό στο URL είναι το διαπιστευτήριο, και οι αυτοματισμοί είναι απενεργοποιημένοι. Μέσω του easyCoexistence (διαχειριζόμενος τρόπος): η Meta στέλνει στο easyCoexistence, οι αυτοματισμοί μπορούν να απαντούν, και ένα προαιρετικό Forward URL λαμβάνει την αρχική τιμή της Meta μαζί με τα στοιχεία σύνδεσης, υπογεγραμμένη με X-EC-Signature για να την επαληθεύσετε.
Προσπάθειες ανά προωθημένη παράδοση, με διαστήματα 1 λεπτό, 5 λεπτά, 30 λεπτά, 2 ώρες, 6 ώρες και 24 ώρες, περίπου 33 ώρες συνολικά.
Χρονικό όριο αναμονής για απάντηση 2xx σε κάθε προσπάθεια προώθησης, πριν θεωρηθεί αποτυχημένη.
Προτεινόμενο όριο ηλικίας για το t της υπογραφής· οι επαναδοκιμές υπογράφονται ξανά, άρα οι γνήσιες παραδόσεις μένουν μέσα σε αυτό.
Πόσο καιρό επαναδοκιμάζει η Meta ένα άμεσο webhook που έλαβε οτιδήποτε εκτός από HTTP 200, κάτι που μπορεί να επαναλάβει μηνύματα.
Μέγιστο μέγεθος payload webhook που στέλνει η Meta, συμπεριλαμβανομένων των τμημάτων ιστορικού.
Αρχεία καταγραφής εκτελέσεων που κρατιούνται για διαχειριζόμενο αριθμό, με το κείμενο μηνυμάτων και απαντήσεων· το ίδιο το κείμενο μηνυμάτων κρατιέται 30, 90 ή 365 ημέρες, της επιλογής σας.
Ποια είναι η διαφορά μεταξύ άμεσου και διαχειριζόμενου;
Εδώ καθορίζεται πού η Meta στέλνει τα webhooks μηνυμάτων του αριθμού. Στη διαχειριζόμενη λειτουργία, που εμφανίζεται ως Μέσω του easyCoexistence, η Meta στέλνει στο easyCoexistence, το οποίο ελέγχει την υπογραφή της Meta, εκτελεί τους αυτοματισμούς σας, κρατά τις συνομιλίες για τις Συνομιλίες και, αν ορίσετε Forward URL, προωθεί κάθε αλλαγή της Meta σε εσάς υπογεγραμμένη με ένα μυστικό που κατέχετε μόνο εσείς. Στην άμεση λειτουργία, που εμφανίζεται ως Απευθείας στο σύστημά σας, το easyCoexistence ορίζει το HTTPS endpoint σας ως webhook override στο WhatsApp Business Account του αριθμού, ώστε η Meta να στέλνει απευθείας σε εσάς και τα μηνύματα να μη φτάνουν ποτέ στο easyCoexistence.
Τα λειτουργικά webhooks πίσω από την παρακολούθηση, όπως τα 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 |
Πώς μεταβάλλετε έναν αριθμό από τον έναν τρόπο στον άλλο;
Στη σελίδα του αριθμού, η κάρτα Πού πηγαίνουν τα εισερχόμενα μηνύματα δείχνει τη λειτουργία ως δύο επιλογές, Μέσω του easyCoexistence και Απευθείας στο σύστημά σας. Η αποθήκευση προορισμού webhook, στην κάρτα Δρομολόγηση εισερχόμενων μηνυμάτων στο δικό σας webhook ή με set_webhook_destination, κάνει τον αριθμό άμεσο. Η επιλογή Μέσω του easyCoexistence αφαιρεί αμέσως αυτόν τον προορισμό από τη Meta, οπότε προσθέστε το ίδιο URL ως Forward URL για να συνεχίσετε να λαμβάνετε. Οι προωθήσεις σε αναμονή απορρίπτονται όταν ένας αριθμός φεύγει από τη διαχειριζόμενη λειτουργία, και οι αριθμοί που συνδέθηκαν χωρίς URL webhook ξεκινούν ως διαχειριζόμενοι.
Από τον βοηθό τεχνητής νοημοσύνης σας, το 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 ανά αίτημα, τυλιγμένη, αντί για το περιτύλιγμα object, entry και changes της Meta. Το 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, ώστε ο κώδικας που γράφτηκε για το payload της 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 λεπτά από το ρολόι σας, υπολογίστε HMAC-SHA256 πάνω στο t, μια τελεία και το ακατέργαστο σώμα, με κλειδί ολόκληρο το μυστικό προώθησης ως κείμενο UTF-8, και συγκρίνετε το αποτέλεσμα με το v1 σε σταθερό χρόνο. Μόνο τότε αναλύστε το JSON. Απαντήστε με 2xx μέσα σε 10 δευτερόλεπτα και κάντε τη δουλειά στη συνέχεια, και θυμηθείτε τα αναγνωριστικά παραδόσεων που έχετε δεχτεί, ώστε μια επαναδοκιμή να μην επεξεργάζεται δύο φορές.
// 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, το hmac.new πάνω στο t, μια τελεία και τα ακατέργαστα bytes, και το 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)Πώς επαναδοκιμάζονται οι αποτυχημένες παραδόσεις;
Μια προώθηση θεωρείται παραδομένη όταν το endpoint σας απαντά με οποιοδήποτε 2xx μέσα σε 10 δευτερόλεπτα. Οτιδήποτε άλλο, χρονικό όριο, 4xx, 5xx ή ανακατεύθυνση, που δεν ακολουθείται, προγραμματίζει την επόμενη προσπάθεια περίπου 1 λεπτό, 5 λεπτά, 30 λεπτά, 2 ώρες, 6 ώρες και 24 ώρες αργότερα, και μετά την έβδομη προσπάθεια η παράδοση εγκαταλείπεται. Κάθε προσπάθεια υπογράφεται ξανά με νέο t, και το URL πρέπει να είναι δημόσιο HTTPS, ελεγμένο όταν αποθηκεύεται και ξανά πριν από κάθε αποστολή. Οι παραδόσεις φεύγουν από την παλαιότερη στη νεότερη, αλλά μια επαναδοκιμασμένη μπορεί να φτάσει μετά από νεότερες, γι' αυτό ταξινομήστε με βάση τις χρονοσφραγίδες της Meta.
Σε άμεσο προορισμό, τις επαναδοκιμές τις κάνει η Meta: οτιδήποτε εκτός από HTTP 200 επαναλαμβάνεται με μειούμενη συχνότητα έως 7 ημέρες, και αυτές οι επαναλήψεις μπορούν να επαναλάβουν ένα μήνυμα. Αφαιρέστε τα διπλότυπα με βάση το αναγνωριστικό μηνύματος της Meta και στις δύο λειτουργίες, καθώς μια αλλαγή που η Meta ξαναστέλνει προωθείται ξανά με νέο αναγνωριστικό παράδοσης.
Πώς ξέρει ένα άμεσο endpoint ότι ένα POST είναι γνήσιο;
Όχι από το X-Hub-Signature-256. Η Meta υπογράφει με το app secret της εφαρμογής που κατέχει τη συνδρομή, που για αριθμό συνδεδεμένο εδώ είναι του easyCoexistence και δεν μοιράζεται. Άρα ο έλεγχος αυτής της κεφαλίδας με το δικό σας app secret της Meta απορρίπτει γνήσιες παραδόσεις. Το verify token αποδεικνύει το endpoint μόνο μία φορά, κατά τη χειραψία GET της Meta. Αυτό που λειτουργεί αντί γι' αυτό:
- Βάλτε 32 ή περισσότερους τυχαίους χαρακτήρες στη διαδρομή του callback URL και απορρίπτετε αιτήματα χωρίς αυτούς· για αλλαγή, αποθηκεύστε νέο URL.
- Χρησιμοποιήστε γενικό receiver, όπως τον κόμβο n8n Webhook, και όχι WhatsApp trigger που απαιτεί τη δική σας εφαρμογή Meta.
- Κατεβάστε τα πολυμέσα με το id από τη Meta, με το token του αριθμού, ώστε ένα πλαστό id απλώς να αποτυγχάνει.
- Σε αυτοφιλοξενούμενους διακομιστές, προαιρετικά επιτρέψτε μόνο το δίκτυο της Meta, δηλαδή τις διαδρομές που ανακοινώνει το AS32934.
- Ή μεταβείτε σε διαχειριζόμενη λειτουργία με Forward URL, όπου το X-EC-Signature αποδεικνύει κάθε POST.
Συνηθισμένα λάθη
- Το να δείχνετε στο Forward URL κώδικα γραμμένο για το περιτύλιγμα της Meta χωρίς καμία αλλαγή. Μια προώθηση φέρει μία αλλαγή: διαβάστε τα event και value, όχι τα object, entry και changes.
- Αναμονή για X-EC-Event με τιμή statuses. Οι καταστάσεις παράδοσης έρχονται μέσα σε γεγονότα messages, στο value.statuses, και οι απαντήσεις που πληκτρολογούνται στην εφαρμογή έρχονται ως smb_message_echoes.
- Εκτέλεση της δουλειάς πριν από την απάντηση. Μια προώθηση περιμένει 10 δευτερόλεπτα, και τότε η ίδια παράδοση επιστρέφει με νέο t· απαντήστε πρώτα με 2xx και επεξεργαστείτε από μια ουρά.
- Αλλαγή σε διαχειριζόμενη λειτουργία με την προσδοκία ότι το παλιό URL εξακολουθεί να λαμβάνει. Ο άμεσος προορισμός αφαιρείται εκείνη ακριβώς τη στιγμή· περάστε το forward_url στην ίδια κλήση set_inbound_mode.
Το easyCoexistence συνδέει έναν αριθμό WhatsApp Business app με το Cloud API της Meta μέσω του Coexistence και σας επιτρέπει να επιλέξετε, για κάθε αριθμό, πού πηγαίνουν τα μηνύματά του: απευθείας από τη Meta στον διακομιστή σας, ή μέσω του easyCoexistence ώστε οι αυτοματισμοί να μπορούν να απαντούν και ένα υπογεγραμμένο αντίγραφο να φτάνει στο Forward URL σας. Η παρακολούθηση και οι ειδοποιήσεις λειτουργούν και στις δύο λειτουργίες. Από US$ 9 έως US$ 0,75 ανά αριθμό τον μήνα, με μείωση όσο προσθέτετε αριθμούς, με τις πρώτες 3 ημέρες δωρεάν.
Συχνές ερωτήσεις
Θα δει ο διακομιστής μου τι απάντησε ένας αυτοματισμός;
Όχι το κείμενο. Η Meta αναφέρει τις αποστολές API ως καταστάσεις (sent, delivered, read) μέσα σε γεγονότα messages, με το id μηνύματος· το ίδιο το κείμενο βρίσκεται στο αρχείο καταγραφής εκτέλεσης του αυτοματισμού, που κρατιέται 30 ημέρες στην καρτέλα Runs, και στις Συνομιλίες για το χρονικό διάστημα που επιλέξατε.
Πώς αλλάζω το μυστικό προώθησης;
Πατήστε Νέο μυστικό στη σελίδα του αριθμού ή καλέστε το set_inbound_mode με rotate_secret ορισμένο σε true. Το νέο μυστικό εμφανίζεται μία φορά και υπογράφει τα πάντα από εκεί και πέρα, και τις επαναδοκιμές παλαιότερων παραδόσεων συμπεριλαμβανομένων, γι' αυτό ενημερώστε αμέσως τον διακομιστή σας.
Χρειάζεται το Forward URL τη χειραψία GET της Meta;
Όχι. Μόνο ένας άμεσος προορισμός καλείται από τη Meta και πρέπει να επαναλάβει το hub.challenge. Το Forward URL καλείται από το easyCoexistence και λαμβάνει μόνο υπογεγραμμένα POST.
Μπορεί ένας αριθμός να έχει άμεσο προορισμό και Forward URL ταυτόχρονα;
Όχι. Το Forward URL λειτουργεί μόνο όσο ο αριθμός είναι διαχειριζόμενος, και η αποθήκευση άμεσου προορισμού τον κάνει άμεσο. Το Forward URL και το μυστικό του διατηρούνται, οπότε η επιστροφή σε διαχειριζόμενη λειτουργία συνεχίζει την προώθηση.
Συνεχίστε την ανάγνωση
Έτοιμοι να ξεκινήσετε;
Ρυθμίστε το WhatsApp Coexistence σε λίγα λεπτά, όχι σε μήνες. Η εφαρμογή συνεχίζει να λειτουργεί στο τηλέφωνο.
Ξεκινήστε δωρεάν δοκιμήΕπαληθεύτηκε στις