Paano tatanggapin ang mga mensahe sa WhatsApp at social comments ng mga customer sa pamamagitan ng webhook
Bawat koneksyon ay may sariling webhook para sa mga mensahe sa WhatsApp o social comments ng mga customer ninyo sa pamamagitan ng Partner API ng easyCoexistence. Diretso mula Meta papunta sa URL na iyon ang mga mensahe sa WhatsApp, naka-sign gamit ang secret ng Tech Provider app at hindi ang secret na hawak ninyo, kaya ang mahabang random na secret sa URL path ang nagpapatunay sa mga ito. Ang comments at DMs sa Instagram at Facebook, at ang TikTok comments, ay ipinapasa habang dumarating, naka-sign kada account gamit ang X-EC-Signature.
Pinakamahabang haba na pinapayagan ng Meta para sa alternate callback URL na nagpapadala ng mga mensahe ng numero sa inyong endpoint.
Gaano katagal sinusubukang muli ng Meta ang WhatsApp webhook na hindi tinanggap ng inyong endpoint, na may unti-unting pagbaba ng dalas, at maaaring magdulot ng mga duplicate.
Network ng Meta; ang whois route lookups dito ay naglilista ng mga address kung saan galing ang WhatsApp webhooks, na pana-panahong binabago ng Meta.
Pinakamalaking laki ng WhatsApp webhook payload ayon sa Meta.
Edad pagkatapos nito na dapat tanggihan ang naka-sign na timestamp ng ipinasang event, at ikinukumpara ang HMAC sa constant time.
Paano nagkakaroon ng sariling destination ang bawat koneksyon?
Sa pamamagitan ng isang tawag kada resource. Ang numero sa WhatsApp ay gumagamit ng PUT /connections/{id}/webhook na may url at verify_token, o ng parehong pares bilang webhook_url at webhook_verify_token sa connect session nito, para ma-route sa inyo ang numero mula sa unang minuto. Ang social account naman ay gumagamit ng PUT /channels/{id}/webhook na may url kapag nakakonekta na. Ang url na null sa alinman ay nagpapatigil ng delivery. Magkaiba ang dalawang landas sa kung sino ang nagde-deliver at kung paano ninyo ito ina-authenticate:
| 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 |
Paano ninyo itinuturo ang mga mensahe ng numero sa inyong endpoint?
Bigyan ito ng HTTPS URL na ang path ay may mahabang random na secret, kasama ang verify token: webhook_verify_token sa connect session, 8 hanggang 200 characters, o verify_token sa PUT. Agad na sinusuri ng Meta ang URL sa pamamagitan ng GET na may hub.mode=subscribe, hub.verify_token at hub.challenge, at dapat sumagot ang inyong endpoint ng halaga ng hub.challenge kapag tugma ang token. Kapag pumalya ang handshake na ito, ibinabalik ng PUT ang 502 meta_rejected kasama ang sariling mensahe ng Meta. Sa connect session naman, nakakonekta pa rin ang numero, at sinasabi ng last_error ng session kung bakit hindi nailapat ang 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
});Bakit hindi ninyo ma-verify ang signature ng Meta, at ano ang pumapalit dito?
Pinipirmahan ng Meta ang bawat delivery gamit ang X-Hub-Signature-256, isang HMAC-SHA256 ng payload na ang susi ay ang App Secret ng app na tumatanggap. Para sa mga numero ng inyong customer, ang app na iyon ay ang Tech Provider app ng easyCoexistence, at hindi ibinabahagi ang secret nito, kaya hindi ito mabe-verify sa panig ninyo. Ang mahabang random na secret sa URL path ang kapalit na credential: ikumpara ito sa constant time at tanggihan ang anumang iba. Bilang pangalawang layer, i-allowlist ang mga route na nakarehistro sa AS32934 ng Meta at i-refresh ang listahang iyon, dahil pana-panahong binabago ng Meta ang kanilang IP address.
Aling mga WhatsApp webhook ang umaabot sa URL ninyo?
Ang mga field na pinapayagan ng Meta na dalhin ng alternate callback URL: messages, para sa ipinapadala ng customer at sa status ng ipinapadala ninyo; smb_message_echoes, para sa ipinapadala ng negosyo mula sa WhatsApp Business app; at ang minsanang import ng history at smb_app_state_sync. Hindi kailanman nagpapadala ang Meta ng template webhooks, o ng account webhooks gaya ng account_update, sa override. Sa callback ng easyCoexistence napupunta ang mga iyon, kaya binabasa ang template review sa pamamagitan ng polling at ang pagbagsak nito ay umaabot sa inyo bilang status event.
- Nakatakda ang destination sa WhatsApp Business Account, kaya nagbabahagi ng iisa ang dalawang numero sa iisang account: i-route batay sa value.metadata.
phone_number_id. - Dumarating ang media bilang ID; kunin ang file mula sa Meta gamit ang token ng customer mula sa credentials call.
- Maaaring umabot sa 3 MB ang payload, kaya itaas ang anumang body-size limit na nakatakda sa mas mababa rito.
Ano ang itsura ng ipinasang social event?
Isang POST na may Content-Type application/json at header na X-EC-Signature, na may apat na key: platform; account_id, ang channel ID na ginagamit ng Partner API; external_id, ang ID ng account sa network; at entry. Para sa Instagram at Facebook, hindi binabago ang entry ng Meta: may changes para sa comments at mentions, at messaging para sa DMs. Para sa TikTok, naglalaman ito ng comment.update event na may naka-parse na content, at comment_id, video_id at parent_comment_id bilang string, para hindi ma-round ang 64-bit na ID.
- Naka-subscribe ang mga Instagram account sa comments, messages at mentions; ang mga Facebook Page sa feed, messages at mention; nagpapadala ang TikTok ng comment.update.
- Hindi tumatanggap ang easyCoexistence ng comment event mula sa YouTube o LinkedIn: sumasagot ang kanilang PUT ng 400
not_supported, at binabasa ang kanilang comments sa pamamagitan ng API ng bawat network gamit ang credentials. - Walang header na X-EC-Event o X-EC-Delivery ang mga forward, kaya i-deduplicate gamit ang sariling ID ng network, gaya ng comment ID o message 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>" }
}
}
]
}
}Paano i-verify ang X-EC-Signature, hakbang-hakbang?
Gamit ang signing_secret na ibinalik ng PUT /channels/{id}/webhook, na ipinapakita nang isang beses lang at natatangi sa account na iyon. Ang header ay may anyong t=<unix>,v1=<hex>. Pagkatapos, para sa bawat delivery:
- Basahin ang raw request body bilang bytes, bago anumang JSON parsing.
- Hatiin ang header sa mga comma para makuha ang t, isang Unix time sa segundo, at ang v1, isang hex digest.
- Tanggihan ang delivery kung higit sa 5 minuto ang layo ng t sa orasan ninyo.
- Kalkulahin ang HMAC-SHA256 sa t, isang tuldok, at ang raw body, gamit ang secret ng account na iyon, bilang hex.
- Ikumpara ito sa v1 sa constant time, saka sumagot ng 2xx at ilagay sa queue ang trabaho.
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);
});Ano ang mangyayari kapag walang nakatakdang destination?
Walang makakarating sa inyo, at walang naghihintay na ipadala sa bandang huli. Ang numerong walang webhook_url ay babalik sa callback ng easyCoexistence, kung saan nalalaglag ang mga mensahe nito nang hindi iniimbak, at hindi ito makakatanggap ng chat history import, na hinihingi lang kapag may umiiral nang destination. Ang social account na walang destination ay hindi ipinapasa: umaabot pa rin ang mga event nito sa app ng easyCoexistence, pero walang itinatabi para sa inyo. Itakda ang bawat destination bago ninyo kailanganin ang trapiko.
Ano ang mangyayari sa destination kapag nalaglag o inalis ang isang koneksyon?
Pinapanatili ng numero ang destination nito sa record. Kapag muling kumonekta ang numerong nalaglag, muling itatakda ng easyCoexistence ang URL ninyo sa Meta, at ganoon din kapag bumalik ang numerong na-suspend. Ang pag-alis ng social account ay nagbubura ng destination at secret nito, kaya pagkatapos nitong muling kumonekta, tawagin muli ang PUT /channels/{id}/webhook at itabi ang bagong secret. Naglalabas ng bagong secret ang PUT na iyon tuwing tinatawag na may URL, at agad na hihinto sa pag-sign ang luma.
Paano ito i-set up
- 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.
Mga karaniwang pagkakamali
- Pag-check ng X-Hub-Signature-256 sa mga WhatsApp delivery ng inyong customer. Pinipirmahan ito ng Meta gamit ang app secret ng easyCoexistence, na hindi ibinabahagi, kaya hindi ito makakapasa sa check; mag-authenticate gamit ang secret sa URL path.
- Pag-verify ng X-EC-Signature sa parsed JSON. Ang HMAC ay sumasaklaw sa raw body na byte-for-byte, at kapag muling i-serialize ang body, nagbabago ang mga byte, kaya i-verify bago mag-parse.
- Paggamit ng iisang secret para sa bawat channel. Ang bawat social account ay pumipirma gamit ang sariling secret, at ang status event ay may iba, kaya hanapin ang secret gamit ang account_id.
- Paggawa ng mabagal na trabaho bago sumagot sa ipinasang event. Ipinapadala ito nang isang beses, naghihintay ng 8 segundo para sa sagot ninyo, at hindi na sinusubukang muli, kaya sumagot muna ng 2xx at iproseso pagkatapos.
Dinidiretso ng easyCoexistence ang mga mensahe ng numero ng bawat customer mula Meta papunta sa inyong server, at ipinapasa ang Instagram at Facebook comments at DMs, pati TikTok comments, sa inyong endpoint habang dumarating, naka-sign kada account, nang walang kopyang itinatago at may 24/7 na pagmo-monitor sa bawat koneksyon. US$ 9 hanggang US$ 0.75 kada koneksyon kada buwan, bumababa habang nagdadagdag kayo ng koneksyon, at may free trial sa unang 3 araw.
Mga madalas itanong
Maaari bang i-verify ang signature ng Meta sa mga mensahe sa WhatsApp ng mga customer ninyo?
Hindi. Pinipirmahan ito ng Meta gamit ang secret ng Tech Provider app ng easyCoexistence, na hindi ibinabahagi. Mag-authenticate gamit ang mahabang random na secret sa URL path ninyo, at opsyonal ang IP range ng Meta.
Ipinapasa ba ng koneksyon sa YouTube at LinkedIn ang comment events?
Hindi. Walang natatanggap na comment event ang easyCoexistence mula sa alinman sa dalawa, kaya sumasagot ang PUT /channels/{id}/webhook ng 400 not_supported. Basahin ang kanilang comments sa pamamagitan ng API ng bawat network gamit ang credentials ng channel.
Ire-retry ba ang mga ipinasang social event kapag down ang server ninyo?
Hindi. Ipinapadala ang bawat isa nang isang beses, at walang kopyang itinatago. Iba ang WhatsApp deliveries, dahil mismong nagre-retry ang Meta ng mga iyon hanggang 7 araw.
Dumadaan ba sa easyCoexistence ang mga mensahe?
Hindi sa WhatsApp: diretso mula Meta papunta sa webhook na itinakda ninyo ang mga mensahe ng numero. Ang comments at DMs mula sa mga social network ay ipinapasa sa inyong endpoint habang dumarating, naka-sign kada account, nang walang kopyang itinatago.
Magpatuloy sa pagbabasa
I-connect ang inyong unang channel sa loob ng dalawang minuto.
Walang review ng platform na hihintayin. I-connect ang WhatsApp, Instagram, TikTok o iba pang channel, pagkatapos ay utusan ang inyong AI na mag-post, mag-reply o gumawa ng report, at panoorin itong gumana.
- 3 araw na libre
- Mag-cancel anumang oras
- Official API lang
- Minomonitor 24/7
Na-verify noong