Prijavite seZapočnite besplatni probni period
easyCoexistence Zvanični API-ji

Kako primati WhatsApp poruke i društvene komentare vaših klijenata putem webhook-a

Svaka veza dobija sopstveni webhook za poruke vaših klijenata na WhatsApp-u ili komentare na društvenim mrežama, preko Partner API-ja platforme easyCoexistence. WhatsApp poruke stižu sa platforme Meta direktno na taj URL, potpisane tajnom aplikacije Tech Provider, a ne tajnom koju vi držite, pa dugačak nasumični tajni niz u putanji URL-a služi kao autentikacija. Komentari i DM poruke sa Instagrama i Facebook-a, kao i TikTok komentari, prosleđuju se čim stignu i potpisani su za svaki nalog posebno pomoću X-EC-Signature.

200 characters

Maksimalna dužina koju Meta dozvoljava za alternativni callback URL, koji šalje poruke broja na vaš endpoint.

7 days

Koliko dugo Meta ponavlja WhatsApp webhook koji vaš endpoint nije prihvatio, sa sve manjom učestalošću, što može dovesti do duplikata.

AS32934

Meta mreža; whois pretrage ruta za nju navode adrese sa kojih stižu WhatsApp webhookovi, a Meta ih povremeno menja.

3 MB

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

5 minutes

Vreme posle kog se prosleđeni događaj sa potpisanim vremenskim žigom odbija, uz HMAC poređen u konstantnom vremenu.

Kako svaka veza dobija sopstveno odredište?

Kroz jedan poziv po resursu. Broj na WhatsApp-u koristi PUT /connections/{id}/webhook sa url i verify_token, ili isti par kao webhook_url i webhook_verify_token u sesiji za povezivanje, tako da broj ka vama usmerava saobraćaj od prvog minuta. Društveni nalog koristi PUT /channels/{id}/webhook kada se jednom poveže. URL null na bilo kom od njih isključuje isporuku. Dve putanje se razlikuju po tome ko isporučuje i kako se autentikujete:

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 poruke jednog broja usmeriti na vaš endpoint?

Navedite HTTPS URL čija putanja sadrži dugačak nasumični tajni niz, plus verify token: webhook_verify_token u sesiji za povezivanje, dužine 8 do 200 karaktera, ili verify_token u PUT zahtevu. Meta odmah proverava URL GET zahtevom sa hub.mode=subscribe, hub.verify_token i hub.challenge, a vaš endpoint mora da odgovori vrednošću hub.challenge kada se token poklapa. Ako ova provera ne uspe, PUT vraća 502 meta_rejected sa porukom koju je vratila Meta; u sesiji za povezivanje broj se i dalje povezuje, a last_error sesije kaže zašto URL nije primenjen.

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 ne možete proveriti potpis Meta i šta ga zamenjuje?

Meta potpisuje svaku isporuku zaglavljem X-Hub-Signature-256, HMAC-SHA256 nad payloadom, ključem App Secret primajuće aplikacije. Za brojeve vaših klijenata ta aplikacija je Tech Provider aplikacija platforme easyCoexistence, a njena tajna se nikada ne deli, pa zaglavlje na vašoj strani ne može da se proveri. Umesto njega, kredencijal je dugačak nasumični tajni niz u putanji URL-a: uporedite ga u konstantnom vremenu i odbijte sve drugo. Kao drugi sloj, dozvolite samo rute registrovane na Meta AS32934 i osvežavajte listu, jer Meta povremeno menja IP adrese.

Koji WhatsApp webhookovi stižu na vaš URL?

Polja koja alternativni callback URL može da nosi: messages, za ono što šalju klijenti i status onoga što vi šaljete; smb_message_echoes, za ono što firma šalje iz aplikacije WhatsApp Business; i jednokratni uvoz history i smb_app_state_sync. Meta nikada ne šalje template webhookove, ni account webhookove poput account_update, na zamenski URL. Oni stižu na callback platforme easyCoexistence, zato se pregled šablona očitava periodičnim upitima, a odbijanje dolazi kao događaj statusa.

  • Odredište se postavlja na WhatsApp Business nalogu, pa dva broja u jednom nalogu dele isto; usmeravajte prema value.metadata.phone_number_id.
  • Mediji stižu kao ID; preuzmite fajl sa platforme Meta uz token klijenta iz poziva za kredencijale.
  • Payloadi mogu dostići 3 MB, zato podignite svako ograničenje veličine tela ispod te vrednosti.

Kako izgleda prosleđen događaj sa društvene mreže?

POST sa Content-Type application/json i zaglavljem X-EC-Signature, koji nosi četiri ključa: platform; account_id, ID kanala koji koristi Partner API; external_id, ID naloga na mreži; i entry. Za Instagram i Facebook, entry je Meta webhook entry nepromenjen, sa changes za komentare i pominjanja i messaging za DM. Za TikTok sadrži događaj comment.update sa parsiranim sadržajem, i comment_id, video_id i parent_comment_id kao stringove, tako da 64-bitni ID-jevi nisu zaokruženi.

  • Instagram nalozi su pretplaćeni na komentare, poruke i pominjanja; Facebook stranice na feed, messages i mention; TikTok šalje comment.update.
  • easyCoexistence ne prima događaje komentara sa YouTube-a ni LinkedIn-a: njihov PUT odgovara 400 not_supported, a komentari se čitaju preko API-ja svake mreže sa kredencijalima.
  • Prosleđivanja ne nose zaglavlje X-EC-Event ni X-EC-Delivery, pa deduplicirajte po ID-jevima same mreže, kao što su ID komentara ili mid poruke.
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 proveriti X-EC-Signature, korak po korak?

Pomoću signing_secret koji je vratio PUT /channels/{id}/webhook, prikazan samo jednom i jedinstven za taj nalog. Zaglavlje glasi t=<unix>,v1=<hex>. Zatim, za svaku isporuku:

  • Pročitajte sirovo telo zahteva kao bajtove, pre bilo kakvog JSON parsiranja.
  • Razdvojite zaglavlje po zarezima na t, Unix vreme u sekundama, i v1, heksadecimalni digest.
  • Odbijte isporuku ako je t udaljen više od 5 minuta od vašeg sata.
  • Izračunajte HMAC-SHA256 nad t, tačkom i sirovim telom, ključem tajne tog naloga, kao heks.
  • Uporedite sa v1 u konstantnom vremenu, zatim odgovorite 2xx i stavite posao u red.
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);
});

Šta se dešava kada odredište nije postavljeno?

Ništa ne stiže do vas, i ništa ne čeka da se kasnije pošalje. Broj bez webhook_url prelazi na callback platforme easyCoexistence, gde se njegove poruke odbacuju bez čuvanja, i ne dobija uvoz istorije četa, koji se traži tek kad postoji odredište. Društveni nalog bez odredišta se ne prosleđuje: njegovi događaji i dalje stižu do aplikacije easyCoexistence, ali se ni jedan ne zadržava za vas. Postavite svako odredište pre nego što vam zatreba saobraćaj.

Šta se dešava sa odredištem kada veza padne ili se ukloni?

Broj zadržava svoje odredište u evidenciji. Kada se prekinuti broj ponovo poveže, easyCoexistence ponovo postavlja vaš URL kod platforme Meta, isto se dešava kada suspendovani broj ponovo bude aktivan. Uklanjanje društvenog naloga briše njegovo odredište i tajnu, pa nakon ponovnog povezivanja pozovite PUT /channels/{id}/webhook ponovo i sačuvajte novu tajnu. Taj PUT izdaje novu tajnu kad god se pozove sa URL-om, a stara prestaje odmah da potpisuje.

Kako da podesite

  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.

Česte greške

  • Proveravanje X-Hub-Signature-256 na isporukama WhatsApp poruka vaših klijenata. Meta ga računa tajnom aplikacije easyCoexistence, koja se nikada ne deli, pa provera ne može da prođe; autentikujte se tajnim nizom u putanji URL-a.
  • Proveravanje X-EC-Signature nad parsiranim JSON-om. HMAC pokriva sirovo telo bajt po bajt, a ponovna serijalizacija menja bajtove, zato proverite pre parsiranja.
  • Korišćenje jedne tajne za sve kanale. Svaki društveni nalog potpisuje sopstvenom tajnom, a statusni događaji drugom, zato tajnu tražite po account_id.
  • Obavljanje sporog posla pre odgovora na prosleđeni događaj. Šalje se jednom, čeka 8 sekundi na vaš odgovor i nikada se ne ponavlja, zato prvo odgovorite 2xx, pa obrađujte.
Ovo radite uz EasyCoexistence

easyCoexistence usmerava poruke svakog broja klijenta sa Meta direktno na vaš server, a Instagram i Facebook komentare i DM poruke, kao i TikTok komentare, prosleđuje vašem endpointu čim stignu, potpisane za svaki nalog posebno, bez zadržane kopije i uz nadzor svake veze 24/7. Od US$ 9 do US$ 0.75 po vezi mesečno, sa padanjem kako dodajete veze, uz besplatni probni period od 3 dana.

Često postavljana pitanja

Mogu li da proverim Meta potpis na porukama WhatsApp vaših klijenata?

Ne. Meta ih potpisuje tajnom aplikacije Tech Provider platforme easyCoexistence, koja se nikada ne deli. Autentikujte se dugačkim nasumičnim tajnim nizom u putanji URL-a i, ako želite, IP opsezima Meta.

Da li veze sa YouTube-om i LinkedIn-om prosleđuju događaje komentara?

Ne. easyCoexistence ne prima događaje komentara ni sa jedne od njih, pa PUT /channels/{id}/webhook odgovara 400 not_supported. Komentare čitajte preko API-ja svake mreže sa kredencijalima kanala.

Da li se prosleđeni događaji sa društvenih mreža ponavljaju ako je moj server pao?

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

Da li poruke prolaze kroz easyCoexistence?

Na WhatsApp-u ne: Meta isporučuje poruke broja direktno na webhook koji postavite. Komentari i DM poruke sa društvenih mreža prosleđuju se vašem endpointu čim stignu, potpisani za svaki nalog posebno, bez zadržane kopije.

Nastavite sa čitanjem

Povežite prvi kanal za dva minuta.

Bez čekanja na odobrenja platformi. Povežite WhatsApp, Instagram, TikTok ili drugi kanal, zatim zamolite svoj AI da objavi, odgovori ili napravi izveštaj, i gledajte kako radi.

  • 3 dana besplatno
  • Otkažite bilo kada
  • Samo zvanični API-ji
  • Nadzor 24/7

Provereno na