Miten vastaanotat asiakkaidesi WhatsApp-viestit ja somekommentit webhookin kautta
Jokaisella yhteydellä on oma webhook asiakkaidesi WhatsApp-viesteille tai somekommenteille easyCoexistencen Partner API:n kautta. WhatsApp-viestit kulkevat Metasta suoraan tuohon URL-osoitteeseen. Ne allekirjoitetaan Tech Provider -sovelluksen salaisuudella, jota et itse pidä hallussasi, joten URL-polun pitkä satunnainen salaisuus tunnistaa ne. Instagram- ja Facebook-kommentit ja DM:t sekä TikTok-kommentit välitetään saapumisjärjestyksessä, ja ne allekirjoitetaan tilikohtaisesti X-EC-Signature-otsikolla.
Metan enimmäispituus vaihtoehtoiselle takaisinkutsu-URL:lle, joka lähettää numeron viestit päätepisteeseesi.
Kuinka pitkään Meta yrittää uudelleen WhatsApp-webhookia, jota päätepisteesi ei hyväksynyt, harvenevalla tahdilla; tämä voi aiheuttaa kaksoiskappaleita.
Metan verkko; whois-reittihaut listaavat osoitteet, joista WhatsApp-webhookit tulevat, ja Meta vaihtaa niitä ajoittain.
Suurin mahdollinen WhatsApp-webhookin sisältökoko Metan mukaan.
Ikä, jonka jälkeen välitetyn tapahtuman allekirjoitettu aikaleima tulee hylätä; HMAC verrataan vakioajassa.
Miten jokainen yhteys saa oman kohteen?
Yhdellä kutsulla per resurssi. WhatsApp-numero käyttää PUT /connections/{id}/webhook -kutsua, jossa on url ja verify_token, tai saman parin nimillä webhook_url ja webhook_verify_token yhteysistunnossa, jolloin numero reitittyy sinulle ensimmäisestä minuutista lähtien. Sometili käyttää PUT /channels/{id}/webhook -kutsua, kun se on yhdistetty. Jos url on null kummalla tahansa, toimitus loppuu. Kaksi polkua eroavat siinä, kuka toimittaa ja miten tunnistaudut:
| 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 |
Miten ohjaat numeron viestit päätepisteeseesi?
Anna HTTPS-URL, jonka polussa on pitkä satunnainen salaisuus, sekä vahvistustunnus: webhook_verify_token yhteysistunnossa, 8–200 merkkiä, tai verify_token PUT-kutsussa. Meta tarkistaa URL:n heti GET-pyynnöllä, jossa on hub.mode=subscribe, hub.verify_token ja hub.challenge, ja päätepisteesi vastaa hub.challenge-arvolla, kun tunnus täsmää. Jos tämä kättely epäonnistuu, PUT palauttaa 502 meta_rejected Metan omalla viestillä; yhteysistunnossa numero yhdistyy silti, ja session last_error kertoo, miksi URL:ää ei otettu käyttöön.
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
});Miksi Metan allekirjoitusta ei voi tarkistaa, ja mikä sen korvaa?
Meta allekirjoittaa jokaisen toimituksen X-Hub-Signature-256-otsikolla, joka on HMAC-SHA256 sisällöstä vastaanottavan sovelluksen App Secretillä. Asiakkaidesi numeroille tuo sovellus on easyCoexistencen Tech Provider -sovellus, jonka salaisuutta ei jaeta, joten otsikkoa ei voi tarkistaa omalla puolellasi. Tunnistautumisen hoitaa sen sijaan URL-polun pitkä satunnainen salaisuus: vertaa sitä vakioajassa ja hylkää kaikki muu. Toisena kerroksena sallilista Metalle rekisteröidyistä AS32934-reiteistä ja päivitä lista säännöllisesti, sillä Meta vaihtaa IP-osoitteitaan ajoittain.
Mitkä WhatsApp-webhookit tavoittavat URL-osoitteesi?
Kentät, jotka vaihtoehtoinen takaisinkutsu-URL voi kantaa: messages asiakkaiden lähettämille viesteille ja lähetettyjen viestien tilalle; smb_message_echoes yritykseltä WhatsApp Business -sovelluksesta lähteville viesteille; sekä kertaluonteisen tuonnin history ja smb_app_state_sync. Meta ei koskaan lähetä viestipohjien webhookeja eikä tilitason webhookeja, kuten account_update, ohitusosoitteeseen. Ne menevät easyCoexistencen takaisinkutsuun, minkä vuoksi viestipohjan tarkistus luetaan kyselemällä ja hylkäys tulee tilatapahtumana.
- Kohde asetetaan WhatsApp Business -tilille, joten yhden tilin kaksi numeroa jakavat sen: reititä kentän value.metadata.
phone_number_idperusteella. - Media saapuu tunnuksena; hae tiedosto Metalta asiakkaan tokenilla credentials-kutsusta.
- Sisällöt voivat olla jopa 3 MB, joten nosta kaikki runkokokorajat sen yli.
Miltä välitetty sometapahtuma näyttää?
POST-pyyntö, jossa on Content-Type application/json ja X-EC-Signature-otsikko, ja siinä neljä avainta: platform; account_id, Partner API:n käyttämä kanavatunnus; external_id, tilin tunnus verkossa; ja entry. Instagramissa ja Facebookissa entry on Metan webhook-entry sellaisenaan, jossa ovat changes kommenteille ja maininnoille sekä messaging DM:lle. TikTokissa se sisältää comment.update-tapahtuman jäsennettynä, ja comment_id, video_id ja parent_comment_id merkkijonoina, jottei 64-bittisiä tunnuksia pyöristetä.
- Instagram-tilit on tilattu kommentteihin, viesteihin ja maininnoihin; Facebook-sivut feediin, viesteihin ja maininnoihin; TikTok lähettää comment.update-tapahtuman.
- easyCoexistence ei vastaanota kommenttitapahtumia YouTubesta eikä LinkedInistä: niiden PUT vastaa 400
not_supported, ja niiden kommentit luetaan kunkin verkon API:sta tunnistetiedoilla. - Välityksissä ei ole X-EC-Event- eikä X-EC-Delivery-otsikkoa, joten poista kaksoiskappaleet verkon omilla tunnuksilla, kuten kommenttitunnus tai viestin 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>" }
}
}
]
}
}Miten X-EC-Signature vahvistetaan vaihe vaiheelta?
Käytä signing_secretiä, jonka PUT /channels/{id}/webhook palautti; se näytetään vain kerran ja on ainutlaatuinen kyseiselle tilille. Otsikko on muotoa t=<unix>,v1=<hex>. Tee sitten jokaiselle toimitukselle seuraavat:
- Lue pyynnön raakarunko tavuina ennen mitään JSON-jäsennystä.
- Jaa otsikko pilkuilla osiin t, Unix-aika sekunneissa, ja v1, heksadesimaalinen tiiviste.
- Hylkää toimitus, jos t on yli 5 minuuttia kellostasi.
- Laske HMAC-SHA256 tekstistä t, piste ja raakarunko, avaimena tilin oma salaisuus, heksana.
- Vertaa sitä v1:een vakioajassa, vastaa sitten 2xx ja jonota työ.
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);
});Mitä tapahtuu, kun kohdetta ei ole asetettu?
Mitään ei tavoita sinua, eikä mikään odota lähetystä myöhemmin. Numero ilman webhook_url-kenttää siirtyy easyCoexistencen takaisinkutsuun, jossa sen viestit pudotetaan tallentamatta, eikä se saa keskusteluhistorian tuontia, joka pyydetään vasta kun kohde on olemassa. Sometili ilman kohdetta ei välity: sen tapahtumat menevät yhä easyCoexistencen sovellukseen, mutta niitä ei pidetä sinulle. Aseta jokainen kohde ennen kuin tarvitset liikennettä.
Mitä kohteelle tapahtuu, kun yhteys katkeaa tai se poistetaan?
Numero säilyttää kohteensa kirjauksessa. Kun katkennut numero yhdistyy uudelleen, easyCoexistence asettaa URL-osoitteesi Metaan uudelleen, ja sama tapahtuu, kun keskeytetty numero palaa. Sometilin poistaminen tyhjentää sen kohteen ja salaisuuden, joten kun tili yhdistyy uudelleen, kutsu PUT /channels/{id}/webhook uudelleen ja tallenna uusi salaisuus. Tuo PUT antaa uuden salaisuuden aina, kun sitä kutsutaan URL:n kanssa, ja vanha lakkaa allekirjoittamasta heti.
Näin otat sen käyttöön
- 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.
Yleiset virheet
- Tarkistat X-Hub-Signature-256-otsikon asiakkaidesi WhatsApp-toimituksissa. Meta laskee sen easyCoexistencen sovelluksen salaisuudella, jota ei jaeta, joten tarkistus ei voi onnistua; tunnistaudu URL-polun salaisuudella.
- Vahvistat X-EC-Signature-allekirjoituksen jäsennetyn JSONin yli. HMAC kattaa raakarungon tavu tavulta, ja sen uudelleen sarjoittaminen muuttaa tavut, joten vahvista ennen jäsennystä.
- Yhden salaisuuden käyttäminen kaikille kanaville. Jokainen sometili allekirjoittaa omalla salaisuudellaan ja tilatapahtumat toisella, joten hae salaisuus account_id-kentän perusteella.
- Hidas työ ennen vastausta välitettyyn tapahtumaan. Se lähetetään kerran, odottaa vastaustasi 8 sekuntia eikä sitä yritetä uudelleen, joten vastaa ensin 2xx ja käsittele myöhemmin.
easyCoexistence reitittää jokaisen asiakasnumeron viestit suoraan Metasta palvelimellesi ja välittää Instagram- ja Facebook-kommentit sekä DM:t ja TikTok-kommentit päätepisteeseesi saapumisjärjestyksessä, allekirjoitettuina tilikohtaisesti, ilman kopiota ja jokainen yhteys valvottuna 24/7. US$ 9:stä US$ 0,75:een per yhteys kuukaudessa, hinta laskee yhteyksien lisääntyessä, ensimmäiset 3 päivää ilmaiseksi.
Usein kysytyt kysymykset
Voinko tarkistaa Metan allekirjoituksen asiakkaideni WhatsApp-viesteistä?
Et. Meta allekirjoittaa ne easyCoexistencen Tech Provider -sovelluksen salaisuudella, jota ei jaeta. Tunnistaudu URL-polun pitkällä satunnaisella salaisuudella ja halutessasi Metan IP-osoitealueilla.
Välittävätkö YouTube- ja LinkedIn-yhteydet kommenttitapahtumia?
Eivät. easyCoexistence ei vastaanota kommenttitapahtumia kummastakaan, joten PUT /channels/{id}/webhook vastaa 400 not_supported. Lue niiden kommentit kunkin verkon API:n kautta kanavan tunnistetiedoilla.
Yritetäänkö välitettyjä sometapahtumia uudelleen, jos palvelimeni on alhaalla?
Ei. Jokainen lähetetään kerran eikä kopiota säilytetä. WhatsApp-toimitukset ovat toisin, koska Meta yrittää niitä itse uudelleen jopa 7 päivää.
Kulkevatko viestit easyCoexistencen kautta?
Eivät WhatsAppissa: Meta toimittaa numeron viestit suoraan asettamaasi webhookiin. Sosiaalisten verkkojen kommentit ja DM:t välitetään päätepisteeseesi saapumisjärjestyksessä, allekirjoitettuina tilikohtaisesti, ilman kopiota.
Lue lisää
Yhdistä ensimmäinen kanavasi kahdessa minuutissa.
Ei alustojen tarkastuksia odotettavana. Yhdistä WhatsApp, Instagram, TikTok tai jokin muu kanava, pyydä sitten tekoälyäsi julkaisemaan, vastaamaan tai raportoimaan ja seuraa, kun se hoitaa homman.
- 3 päivää ilmaiseksi
- Peruuta milloin tahansa
- Vain viralliset API:t
- Valvottu 24/7
Vahvistettu