Prijavite seZapočnite besplatno probno razdoblje
easyCoexistence Službeni API-ji

Kako primati poruke vaših kupaca na WhatsAppu i komentare na društvenim mrežama putem webhooka

Svaka veza dobiva vlastiti webhook za WhatsApp poruke vaših kupaca ili komentare na društvenim mrežama, putem Partner API-ja usluge easyCoexistence. WhatsApp poruke s platforme Meta idu izravno na taj URL i potpisane su tajnom aplikacije Tech Provider, a ne tajnom koju držite vi, pa dugi nasumični tajni niz u putanji URL-a služi kao provjera autentičnosti. Komentari i DM-ovi s Instagrama i Facebooka te komentari s TikToka prosljeđuju se čim stignu, a svaki ih račun potpisuje vlastitim potpisom X-EC-Signature.

200 characters

Maksimalna duljina koju Meta dopušta za alternativni povratni URL koji šalje poruke broja na vaš endpoint.

7 days

Koliko dugo Meta ponavlja WhatsApp webhook koji vaš endpoint nije prihvatio, sve rjeđe, što može stvoriti duplikate.

AS32934

Mrežni blok Mete; whois pretrage ruta za njega navode adrese s kojih stižu WhatsApp webhooki, a Meta ih povremeno mijenja.

3 MB

Najveća veličina WhatsApp webhook payloada prema dokumentaciji platforme Meta.

5 minutes

Dob nakon koje treba odbaciti potpisani vremenski žig prosljeđenog događaja, uz usporedbu HMAC-a u konstantnom vremenu.

Kako svaka veza dobiva vlastito odredište?

Jednim pozivom po resursu. Broj na WhatsAppu prima PUT /connections/{id}/webhook s url i verify_token, ili isti par kao webhook_url i webhook_verify_token u svojoj sesiji povezivanja, pa broj prima poruke od prve minute. Društveni račun prima PUT /channels/{id}/webhook s url nakon povezivanja. Vrijednost url null na bilo kojem od njih isključuje isporuku. Dva puta se razlikuju po tome tko isporučuje i kako se autentificirate:

WhatsApp numberInstagram, Facebook, TikTok
Set withwebhook_url on the session, or PUT /connections/{id}/webhookPUT /channels/{id}/webhook, after it connects
Delivered byMeta, straight to your URLeasyCoexistence, forwarding each event as it arrives
BodyMeta's webhook, unchangedplatform, account_id, external_id and the network's entry
AuthenticateA long random secret in the URL pathX-EC-Signature, keyed with the account's secret
RetriesMeta's own, for up to 7 daysNone: one attempt
Copy keptNoneNone

Kako usmjeriti poruke broja na vaš endpoint?

Dajte mu HTTPS URL čija putanja sadrži dugi nasumični tajni niz, plus verify token: webhook_verify_token u sesiji povezivanja, duljine 8 do 200 znakova, ili verify_token u PUT zahtjevu. Meta odmah provjerava URL GET zahtjevom s hub.mode=subscribe, hub.verify_token i hub.challenge, a vaš endpoint mora odgovoriti vrijednošću hub.challenge kad se token podudara. Ako ta provjera ne uspije, PUT vraća 502 meta_rejected s porukom koju je vratila Meta; u sesiji povezivanja broj se ipak povezuje, a last_error sesije navodi zašto URL nije primijenjen.

Node.js: Meta's handshake and the path secret
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
});

Zašto se Metin potpis ne može provjeriti i što ga zamjenjuje?

Meta potpisuje svaku isporuku zaglavljem X-Hub-Signature-256, HMAC-SHA256 nad payloadom s ključem App Secret primajuće aplikacije. Za brojeve vaših kupaca ta je aplikacija Tech Provider aplikacija usluge easyCoexistence, a njezina tajna se ne dijeli, pa se zaglavlje na vašoj strani ne može provjeriti. Vjerodajnica je umjesto toga dugi nasumični tajni niz u putanji URL-a: usporedite ga u konstantnom vremenu i odbijte sve ostalo. Kao drugi sloj dopustite samo rute iz popisa registriranih na Metinu AS32934 i osvježavajte taj popis, jer Meta povremeno mijenja svoje IP adrese.

Koji WhatsApp webhooki stižu na vaš URL?

Polja koja alternativni povratni URL može nositi: messages, za ono što kupci šalju i status onoga što vi šaljete; smb_message_echoes, za ono što poduzeće šalje iz aplikacije WhatsApp Business; i jednokratni uvoz history i smb_app_state_sync. Meta nikad ne šalje webhooke predložaka ni računske webhooke poput account_update na nadjačavanje. Oni stižu na povratni poziv usluge easyCoexistence, zbog čega se pregled predložaka čita upitima (polling), a odbijanje dolazi kao događaj statusa.

  • Odredište se postavlja na WhatsApp Business Account, pa dva broja u jednom računu dijele ga: usmjeravajte prema value.metadata.phone_number_id.
  • Medijski sadržaj stiže kao ID; datoteku dohvatite s platforme Meta pomoću tokena kupca iz poziva vjerodajnica.
  • Payloadi mogu doseći 3 MB, pa povećajte svako ograničenje veličine tijela postavljeno ispod toga.

Kako izgleda prosljeđeni događaj s društvene mreže?

POST zahtjev s Content-Type application/json i zaglavljem X-EC-Signature, a nosi četiri ključa: platform; account_id, ID kanala koji koristi Partner API; external_id, ID računa na mreži; i entry. Za Instagram i Facebook entry je Metin webhook entry nepromijenjen, s changes za komentare i spominjanja te messaging za DM-ove. Za TikTok sadrži događaj comment.update s raščlanjenim sadržajem te comment_id, video_id i parent_comment_id kao nizove znakova, pa 64-bitni ID-jevi nisu zaokruženi.

  • Instagram računi pretplaćeni su na comments, messages i mentions; Facebook stranice na feed, messages i mention; TikTok šalje comment.update.
  • easyCoexistence ne prima događaje komentara s YouTubea ni LinkedIna: njihov PUT odgovara 400 not_supported, a komentari se čitaju putem API-ja svake mreže s vjerodajnicama.
  • Prosljeđivanja ne nose zaglavlje X-EC-Event ni X-EC-Delivery, pa deduplicirajte na vlastitim ID-jevima mreže, poput ID-ja komentara ili poruke mid.
A forwarded Instagram comment
{
  "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>" }
        }
      }
    ]
  }
}

Kako provjeriti X-EC-Signature, korak po korak?

S signing_secret koji je vratio PUT /channels/{id}/webhook, prikazanim samo jednom i jedinstvenim za taj račun. Zaglavlje glasi t=<unix>,v1=<hex>. Zatim za svaku isporuku:

  • Pročitajte sirovo tijelo zahtjeva kao bajtove, prije ikakve JSON obrade.
  • Razdijelite zaglavlje po zarezima na t, Unix vrijeme u sekundama, i v1, heksadecimalni zapis.
  • Odbijte isporuku ako je t udaljen više od 5 minuta od vašeg sata.
  • Izračunajte HMAC-SHA256 nad t, točkom i sirovim tijelom, s tajnom tog računa, kao heksadecimalni zapis.
  • Usporedite ga s v1 u konstantnom vremenu, zatim odgovorite 2xx i stavite posao u red čekanja.
Node.js: verifying a forwarded event
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);
});

Što se događa kad nije postavljeno odredište?

Ništa vam ne stiže i ništa ne čeka da se kasnije pošalje. Broj bez webhook_url vraća se na povratni poziv usluge easyCoexistence, gdje se njegove poruke odbacuju bez pohrane, a ne dobiva uvoz povijesti razgovora, koji se traži tek kad odredište postoji. Društveni račun bez odredišta se ne prosljeđuje: njegovi događaji i dalje stižu u aplikaciju easyCoexistence, ali se nijedan ne zadržava za vas. Postavite svako odredište prije nego što vam zatreba promet.

Što se događa s odredištem kad se veza prekine ili ukloni?

Broj zadržava svoje odredište u evidenciji. Kad se prekinuti broj ponovno poveže, easyCoexistence ponovno postavlja vaš URL kod platforme Meta, što se događa i kad se suspendirani broj vrati. Uklanjanje društvenog računa briše njegovo odredište i tajnu, pa nakon ponovnog povezivanja ponovno pozovite PUT /channels/{id}/webhook i spremite novu tajnu. Taj PUT izdaje novu tajnu kad god se pozove s URL-om, a stara prestaje potpisivati odmah.

Kako ga postaviti

  1. 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.
  2. 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.
  3. Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
  4. 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.

Uobičajene pogreške

  • Provjera X-Hub-Signature-256 na isporukama WhatsApp poruka vaših kupaca. Meta ga računa App Secret aplikacijom easyCoexistence, koji se ne dijeli, pa provjera ne može proći; autentificirajte tajnom u putanji URL-a.
  • Provjera X-EC-Signature nad raščlanjenim JSON-om. HMAC pokriva sirovo tijelo bajt po bajt, a ponovna serijalizacija mijenja bajtove, pa provjerite prije raščlanjivanja.
  • Jedna tajna za sve kanale. Svaki društveni račun potpisuje vlastitom tajnom, a statusni događaji drugom, pa tajnu tražite po account_id.
  • Spora obrada prije odgovora na prosljeđeni događaj. Šalje se jednom, čeka 8 sekundi na vaš odgovor i nikad se ne ponavlja, pa prvo odgovorite 2xx, a obradu radite poslije.
Radite ovo uz EasyCoexistence

easyCoexistence usmjerava poruke svakog broja kupca s platforme Meta izravno na vaš poslužitelj, a komentare i DM-ove s Instagrama i Facebooka te komentare s TikToka prosljeđuje na vaš endpoint čim stignu, potpisane po računu, bez zadržane kopije i uz praćenje svake veze 24/7. Od US$ 9 do US$ 0,75 po vezi mjesečno, uz sniženje kako dodajete veze, s prvih 3 dana besplatnog probnog razdoblja.

Često postavljana pitanja

Mogu li provjeriti Metin potpis na porukama mojih kupaca na WhatsAppu?

Ne. Meta ih potpisuje tajnom aplikacije easyCoexistence Tech Provider, koja se ne dijeli. Autentificirajte se dugim nasumičnim tajnim nizom u putanji URL-a i, ako želite, rasponima IP adresa Mete.

Prosljeđuju li veze s YouTubeom i LinkedInom događaje komentara?

Ne. easyCoexistence ne prima događaje komentara ni s jednog, pa PUT /channels/{id}/webhook odgovara 400 not_supported. Komentare čitajte putem API-ja svake mreže s vjerodajnicama kanala.

Ponavljaju li se prosljeđeni društveni događaji ako je moj poslužitelj nedostupan?

Ne. Svaki se šalje jednom i ne čuva se kopija. Isporuke WhatsAppa razlikuju se jer ih sama Meta ponavlja do 7 dana.

Prolaze li poruke kroz easyCoexistence?

Na WhatsAppu ne: Meta isporučuje poruke broja izravno na webhook koji postavite. Komentari i DM-ovi s društvenih mreža prosljeđuju se na vaš endpoint čim stignu, potpisani po računu, bez zadržane kopije.

Nastavite čitati

Povežite svoj prvi kanal u dvije minute.

Bez čekanja na provjere platformi. Povežite WhatsApp, Instagram, TikTok ili drugi kanal, zatim zamolite svoju umjetnu inteligenciju da objavi, odgovori ili izradi izvješće i gledajte kako radi.

  • 3 dana besplatno
  • Otkažite bilo kada
  • Samo službeni API-ji
  • Nadzor 24/7

Provjereno na