Πώς λαμβάνετε τα μηνύματα WhatsApp και τα σχόλια των πελατών σας μέσω του webhook
Κάθε σύνδεση αποκτά το δικό της webhook για τα μηνύματα WhatsApp των πελατών σας ή τα σχόλια στα social media, μέσω του Partner API της easyCoexistence. Τα μηνύματα WhatsApp πηγαίνουν από τη Meta απευθείας σε αυτή τη διεύθυνση URL, υπογεγραμμένα με το μυστικό της εφαρμογής Tech Provider και όχι με κάποιο που κατέχετε εσείς, οπότε ένα μακρύ τυχαίο μυστικό στη διαδρομή του URL τα πιστοποιεί. Τα σχόλια και τα DMs του Instagram και του Facebook, καθώς και τα σχόλια του TikTok, προωθούνται όπως φτάνουν, υπογεγραμμένα ανά λογαριασμό με X-EC-Signature.
Το μέγιστο μήκος που επιτρέπει η Meta για το εναλλακτικό URL callback, το οποίο στέλνει τα μηνύματα ενός αριθμού στο endpoint σας.
Για πόσο χρόνο η Meta επαναλαμβάνει την αποστολή ενός webhook WhatsApp που το endpoint σας δεν έκανε δεκτό, με μειούμενη συχνότητα, κάτι που μπορεί να προκαλέσει διπλότυπα.
Το δίκτυο της Meta· οι αναζητήσεις whois διαδρομών για αυτό εμφανίζουν τις διευθύνσεις από τις οποίες προέρχονται τα webhooks WhatsApp, τις οποίες η Meta αλλάζει περιοδικά.
Το μέγιστο μέγεθος ενός payload webhook WhatsApp, σύμφωνα με τη Meta.
Η ηλικία μετά την οποία ένα προωθημένο γεγονός με υπογεγραμμένη χρονοσφραγίδα πρέπει να απορρίπτεται, με το HMAC να συγκρίνεται σε σταθερό χρόνο.
Πώς αποκτά κάθε σύνδεση τον δικό της προορισμό;
Μέσω μιας κλήσης ανά πόρο. Ένας αριθμός WhatsApp δέχεται PUT /connections/{id}/webhook με url και verify_token, ή το ίδιο ζεύγος ως webhook_url και webhook_verify_token στη συνεδρία σύνδεσής του, ώστε ο αριθμός να δρομολογείται προς εσάς από το πρώτο λεπτό. Ένας λογαριασμός social δέχεται PUT /channels/{id}/webhook αφού έχει συνδεθεί. Η τιμή 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 |
Πώς κατευθύνετε τα μηνύματα ενός αριθμού στο endpoint σας;
Δώστε ένα URL HTTPS του οποίου η διαδρομή περιέχει ένα μακρύ τυχαίο μυστικό, μαζί με ένα verify token: webhook_verify_token σε μια συνεδρία σύνδεσης, 8 έως 200 χαρακτήρες, ή verify_token στο PUT. Η Meta ελέγχει αμέσως το URL με ένα GET που φέρει hub.mode=subscribe, hub.verify_token και hub.challenge, και το endpoint σας πρέπει να απαντήσει με την τιμή hub.challenge όταν το token ταιριάζει. Αν αποτύχει αυτή η χειραψία, το PUT επιστρέφει 502 meta_rejected με το δικό του μήνυμα της Meta. Σε συνεδρία σύνδεσης ο αριθμός συνδέεται κανονικά, και το last_error της συνεδρίας εξηγεί γιατί το URL δεν εφαρμόστηκε.
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 του payload με κλειδί το App Secret της εφαρμογής που λαμβάνει. Για τους αριθμούς των πελατών σας, αυτή η εφαρμογή είναι η εφαρμογή Tech Provider της easyCoexistence, και το μυστικό της δεν κοινοποιείται ποτέ, οπότε η κεφαλίδα δεν μπορεί να επαληθευτεί από την πλευρά σας. Το μακρύ τυχαίο μυστικό στη διαδρομή του URL αποτελεί αντί γι' αυτό το διαπιστευτήριο: συγκρίνετέ το σε σταθερό χρόνο και απορρίψτε οτιδήποτε άλλο. Ως δεύτερο επίπεδο, θέστε σε λίστα επιτρεπόμενων τις διαδρομές που έχει καταχωρίσει η Meta με το AS32934, και ανανεώνετε τη λίστα, αφού η Meta αλλάζει περιοδικά τις διευθύνσεις IP της.
Ποια webhooks WhatsApp φτάνουν στο URL σας;
Τα πεδία που επιτρέπει το εναλλακτικό URL callback της Meta: messages, για όσα στέλνουν οι πελάτες και την κατάσταση όσων στέλνετε εσείς· smb_message_echoes, για όσα στέλνει η επιχείρηση από την εφαρμογή WhatsApp Business· και το ιστορικό της εφάπαξ εισαγωγής καθώς και το smb_app_state_sync. Η Meta δεν στέλνει ποτέ webhooks προτύπων, ούτε webhooks λογαριασμού όπως το account_update, σε override. Αυτά φτάνουν στο callback της easyCoexistence, γι' αυτό η έγκριση προτύπων διαβάζεται με polling και μια απόρριψη φτάνει σε εσάς ως γεγονός κατάστασης.
- Ο προορισμός ορίζεται στον λογαριασμό WhatsApp Business, άρα δύο αριθμοί στον ίδιο λογαριασμό τον μοιράζονται: δρομολογήστε με βάση το value.metadata.
phone_number_id. - Τα πολυμέσα φτάνουν ως ID· ανακτήστε το αρχείο από τη Meta με το token του πελάτη από την κλήση διαπιστευτηρίων.
- Τα payloads μπορούν να φτάσουν τα 3 MB, οπότε αυξήστε οποιοδήποτε όριο μεγέθους σώματος έχει οριστεί κάτω από αυτό.
Πώς μοιάζει ένα προωθημένο γεγονός social;
Ένα POST με Content-Type application/json και κεφαλίδα X-EC-Signature, που φέρει τέσσερα κλειδιά: platform· account_id, το ID του καναλιού που χρησιμοποιεί το Partner API· external_id, το ID του λογαριασμού στο δίκτυο· και entry. Για Instagram και Facebook, το entry είναι η καταχώρηση webhook της Meta αναλλοίωτη, με changes για σχόλια και αναφορές και messaging για DMs. Για το TikTok περιέχει το γεγονός comment.update με το περιεχόμενό του αναλυμένο, και τα comment_id, video_id και parent_comment_id ως συμβολοσειρές, ώστε τα 64-bit ID να μη στρογγυλοποιούνται.
- Οι λογαριασμοί Instagram είναι εγγεγραμμένοι σε comments, messages και mentions· τα Facebook Pages σε feed, messages και mention· το TikTok στέλνει comment.update.
- Η easyCoexistence δεν λαμβάνει γεγονότα σχολίων από YouTube ή LinkedIn: το PUT τους απαντά 400
not_supported, και τα σχόλιά τους διαβάζονται μέσω του API κάθε δικτύου με τα διαπιστευτήρια. - Οι προωθήσεις δεν φέρουν κεφαλίδα 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, βήμα προς βήμα;
Με το signing_secret που επέστρεψε το PUT /channels/{id}/webhook, το οποίο εμφανίζεται μόνο μία φορά και είναι μοναδικό για τον συγκεκριμένο λογαριασμό. Η κεφαλίδα έχει τη μορφή t=<unix>,v1=<hex>. Έπειτα, για κάθε παράδοση:
- Διαβάστε το ακατέργαστο σώμα του αιτήματος ως bytes, πριν από οποιαδήποτε ανάλυση JSON.
- Χωρίστε την κεφαλίδα με βάση τα κόμματα σε t, έναν Unix χρόνο σε δευτερόλεπτα, και v1, ένα hex digest.
- Απορρίψτε την παράδοση αν το t απέχει περισσότερο από 5 λεπτά από το ρολόι σας.
- Υπολογίστε HMAC-SHA256 πάνω στο t, μια τελεία και το ακατέργαστο σώμα, με κλειδί το μυστικό του λογαριασμού, ως hex.
- Συγκρίνετέ το με το v1 σε σταθερό χρόνο, και έπειτα απαντήστε 2xx και θέστε σε ουρά την εργασία.
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 δρομολογείται στο callback της easyCoexistence, όπου τα μηνύματά του απορρίπτονται χωρίς αποθήκευση, και δεν παίρνει εισαγωγή ιστορικού συνομιλιών, που ζητείται μόνο όταν υπάρχει προορισμός. Ένας λογαριασμός social χωρίς προορισμό δεν προωθείται: τα γεγονότα του φτάνουν στην εφαρμογή της easyCoexistence, αλλά κανένα δεν κρατείται για εσάς. Ορίστε κάθε προορισμό προτού τον χρειαστείτε.
Τι συμβαίνει σε έναν προορισμό όταν μια σύνδεση πέφτει ή αφαιρείται;
Ένας αριθμός διατηρεί τον προορισμό του στο αρχείο. Όταν ένας αριθμός που έπεσε επανασυνδεθεί, η easyCoexistence ορίζει ξανά το URL σας με τη Meta, και το ίδιο συμβαίνει όταν επανέρχεται ένας αριθμός σε αναστολή. Η αφαίρεση ενός λογαριασμού social διαγράφει τον προορισμό και το μυστικό του, οπότε μετά την επανασύνδεση καλέστε ξανά PUT /channels/{id}/webhook και αποθηκεύστε το νέο μυστικό. Αυτό το PUT εκδίδει νέο μυστικό κάθε φορά που καλείται με URL, και το παλιό σταματά να υπογράφει αμέσως.
Πώς να το ρυθμίσετε
- 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.
Συνηθισμένα λάθη
- Έλεγχος του X-Hub-Signature-256 στις παραδόσεις WhatsApp των πελατών σας. Η Meta την υπολογίζει με το app secret της easyCoexistence, που δεν κοινοποιείται ποτέ, οπότε ο έλεγχος δεν μπορεί να περάσει· πιστοποιήστε με το μυστικό στη διαδρομή του URL.
- Επαλήθευση του X-EC-Signature πάνω σε JSON που έχει αναλυθεί. Το HMAC καλύπτει το ακατέργαστο σώμα byte προς byte, και η επανασειριοποίησή του αλλάζει τα bytes, οπότε επαληθεύστε πριν από την ανάλυση.
- Χρήση ενός μυστικού για όλα τα κανάλια. Κάθε λογαριασμός social υπογράφει με το δικό του μυστικό, και τα γεγονότα κατάστασης με άλλο, οπότε αναζητήστε το μυστικό με βάση το account_id.
- Αργή εργασία πριν απαντήσετε σε ένα προωθημένο γεγονός. Στέλνεται μία φορά, περιμένει 8 δευτερόλεπτα για την απάντησή σας και δεν επαναλαμβάνεται ποτέ, οπότε απαντήστε πρώτα με 2xx και επεξεργαστείτε αργότερα.
Η easyCoexistence δρομολογεί τα μηνύματα κάθε αριθμού πελάτη από τη Meta απευθείας στον server σας, και προωθεί τα σχόλια και τα DMs του Instagram και του Facebook, καθώς και τα σχόλια του TikTok, στο endpoint σας όπως φτάνουν, υπογεγραμμένα ανά λογαριασμό, χωρίς να κρατείται αντίγραφο και με κάθε σύνδεση υπό παρακολούθηση 24/7. Από US$ 9 έως US$ 0,75 ανά σύνδεση τον μήνα, με μείωση όσο προσθέτετε συνδέσεις, με τις πρώτες 3 ημέρες δωρεάν.
Συχνές ερωτήσεις
Μπορώ να ελέγξω την υπογραφή της Meta στα μηνύματα WhatsApp των πελατών μου;
Όχι. Η Meta τα υπογράφει με το μυστικό της εφαρμογής Tech Provider της easyCoexistence, που δεν κοινοποιείται ποτέ. Πιστοποιήστε με το μακρύ τυχαίο μυστικό στη διαδρομή του URL σας, και προαιρετικά με τα εύρη IP της Meta.
Προωθούν τα YouTube και LinkedIn γεγονότα σχολίων;
Όχι. Η easyCoexistence δεν λαμβάνει γεγονότα σχολίων από κανένα από τα δύο, οπότε το PUT /channels/{id}/webhook απαντά 400 not_supported. Διαβάστε τα σχόλιά τους μέσω του API κάθε δικτύου με τα διαπιστευτήρια του καναλιού.
Επαναλαμβάνονται τα προωθημένα γεγονότα social αν ο server μου είναι εκτός λειτουργίας;
Όχι. Κάθε γεγονός στέλνεται μία φορά και δεν κρατείται αντίγραφο. Οι παραδόσεις WhatsApp διαφέρουν, επειδή η ίδια η Meta τις επαναλαμβάνει για έως 7 ημέρες.
Περνούν τα μηνύματα μέσω της easyCoexistence;
Όχι στο WhatsApp: η Meta παραδίδει τα μηνύματα ενός αριθμού απευθείας στο webhook που ορίσατε. Τα σχόλια και τα DMs από τα social δίκτυα προωθούνται στο endpoint σας όπως φτάνουν, υπογεγραμμένα ανά λογαριασμό, χωρίς να κρατείται αντίγραφο.
Συνεχίστε την ανάγνωση
Συνδέστε το πρώτο σας κανάλι σε δύο λεπτά.
Χωρίς αναμονή για έλεγχο από τις πλατφόρμες. Συνδέστε WhatsApp, Instagram, TikTok ή άλλο κανάλι, ζητήστε από το AI σας να δημοσιεύσει, να απαντήσει ή να δημιουργήσει αναφορά και δείτε το να δουλεύει.
- 3 ημέρες δωρεάν
- Ακύρωση ανά πάσα στιγμή
- Μόνο επίσημα API
- Παρακολούθηση 24/7
Επαληθεύτηκε στις