Conectați-văÎncepeți perioada de probă gratuită
easyCoexistence API-uri oficiale

Cum primiți mesajele WhatsApp ale clienților și comentariile din rețelele sociale printr-un webhook

Fiecare conexiune primește propriul webhook pentru mesajele WhatsApp ale clienților sau pentru comentariile din rețelele sociale, prin Partner API-ul easyCoexistence. Mesajele WhatsApp ajung de la Meta direct la acel URL, semnate cu secretul aplicației Tech Provider și nu cu unul pe care îl dețineți dumneavoastră, astfel că un secret lung și aleatoriu din calea URL-ului le autentifică. Comentariile și DM-urile de pe Instagram și Facebook, precum și comentariile de pe TikTok, sunt transmise pe măsură ce sosesc, semnate pentru fiecare cont în parte cu X-EC-Signature.

200 characters

Lungimea maximă permisă de Meta pentru URL-ul alternativ de callback, care trimite mesajele unui număr către endpoint-ul dumneavoastră.

7 days

Cât timp reîncearcă Meta un webhook WhatsApp pe care endpoint-ul dumneavoastră nu l-a acceptat, cu frecvență tot mai mică, ceea ce poate produce duplicate.

AS32934

Rețeaua Meta; interogările whois de rute pentru aceasta listează adresele de la care vin webhook-urile WhatsApp, pe care Meta le schimbă periodic.

3 MB

Dimensiunea maximă a unui payload de webhook WhatsApp, potrivit Meta.

5 minutes

Vârsta după care un timestamp semnat al unui eveniment transmis trebuie respins, HMAC fiind comparat în timp constant.

Cum primește fiecare conexiune propria destinație?

Printr-un singur apel pentru fiecare resursă. Un număr WhatsApp folosește PUT /connections/{id}/webhook cu un url și un verify_token, sau aceeași pereche ca webhook_url și webhook_verify_token în sesiunea de conectare, astfel încât numărul vă transmite evenimentele încă din primul minut. Un cont social folosește PUT /channels/{id}/webhook cu un url, odată ce s-a conectat. Un url cu valoarea null, pentru oricare dintre ele, dezactivează livrarea. Cele două căi diferă prin cine livrează și prin modul în care autentificați:

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

Cum îndreptați mesajele unui număr către endpoint-ul dumneavoastră?

Indicați un URL HTTPS a cărui cale conține un secret lung și aleatoriu, plus un token de verificare: webhook_verify_token pentru o sesiune de conectare, între 8 și 200 de caractere, sau verify_token în PUT. Meta verifică URL-ul imediat, printr-un GET cu hub.mode=subscribe, hub.verify_token și hub.challenge, iar endpoint-ul trebuie să răspundă cu valoarea hub.challenge dacă token-ul corespunde. Dacă această verificare inițială eșuează, PUT returnează 502 meta_rejected cu mesajul propriu al Meta; la o sesiune de conectare, numărul se conectează totuși, iar last_error din sesiune arată de ce URL-ul nu a fost aplicat.

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
});

De ce nu puteți verifica semnătura Meta și ce o înlocuiește?

Meta semnează fiecare livrare cu X-Hub-Signature-256, un HMAC-SHA256 al payload-ului, cheia fiind App Secret-ul aplicației destinatare. Pentru numerele clienților dumneavoastră, aplicația respectivă este aplicația Tech Provider a easyCoexistence, iar secretul ei nu este împărtășit niciodată, așa că antetul nu poate fi verificat de partea dumneavoastră. Secretul lung și aleatoriu din calea URL-ului este în schimb credențialul: comparați-l în timp constant și refuzați orice altceva. Ca al doilea nivel, puneți pe lista de permise rutele înregistrate la Meta sub AS32934 și reîmprospătați lista, deoarece Meta își schimbă periodic adresele IP.

Ce webhook-uri WhatsApp ajung la URL-ul dumneavoastră?

Câmpurile pe care Meta le permite unui URL alternativ de callback: messages, pentru ce trimit clienții și starea a ceea ce trimiteți; smb_message_echoes, pentru ce trimite afacerea din aplicația WhatsApp Business; și istoricul importului unic, împreună cu smb_app_state_sync. Meta nu trimite niciodată șabloanele sau webhook-urile de cont, precum account_update, către o suprascriere. Ele ajung în schimb la callback-ul easyCoexistence, de aceea verificarea șabloanelor se face prin interogare, iar o respingere vă ajunge ca eveniment de stare.

  • Destinația se setează pe contul WhatsApp Business, deci două numere din același cont o împart: rutați după value.metadata.phone_number_id.
  • Media sosește ca ID; descărcați fișierul de la Meta cu token-ul clientului din apelul de credențiale.
  • Payload-urile pot ajunge la 3 MB, deci ridicați orice limită de dimensiune a corpului setată sub această valoare.

Cum arată un eveniment social transmis?

Un POST cu Content-Type application/json și un antet X-EC-Signature, care conține patru chei: platform; account_id, ID-ul canalului folosit de Partner API; external_id, ID-ul contului în rețea; și entry. Pentru Instagram și Facebook, entry este intrarea webhook a Meta nemodificată, cu changes pentru comentarii și mențiuni și messaging pentru DM-uri. Pentru TikTok conține evenimentul comment.update cu conținutul său analizat, iar comment_id, video_id și parent_comment_id sunt șiruri de caractere, astfel că ID-urile pe 64 de biți nu sunt rotunjite.

  • Conturile de Instagram sunt abonate la comentarii, mesaje și mențiuni; Paginile de Facebook la feed, mesaje și mențiuni; TikTok trimite comment.update.
  • easyCoexistence nu primește evenimente de comentarii de la YouTube sau LinkedIn: PUT-ul lor răspunde 400 not_supported, iar comentariile se citesc prin API-ul fiecărei rețele, cu credențialele.
  • Transmiterile nu poartă antetul X-EC-Event sau X-EC-Delivery, deci deduplicați după ID-urile proprii ale rețelei, cum ar fi un ID de comentariu sau un mid de mesaj.
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>" }
        }
      }
    ]
  }
}

Cum verificați X-EC-Signature, pas cu pas?

Cu signing_secret returnat de PUT /channels/{id}/webhook, afișat o singură dată și unic pentru acel cont. Antetul arată astfel: t=<unix>,v1=<hex>. Apoi, pentru fiecare livrare:

  • Citiți corpul brut al cererii ca octeți, înainte de orice parsare JSON.
  • Împărțiți antetul după virgule în t, o oră Unix în secunde, și v1, un digest hexazecimal.
  • Respingeți livrarea dacă t se află la mai mult de 5 minute față de ceasul dumneavoastră.
  • Calculați HMAC-SHA256 peste t, un punct și corpul brut, cu cheia secretului acelui cont, în format hexazecimal.
  • Comparați-l cu v1 în timp constant, apoi răspundeți cu 2xx și puneți munca în coadă.
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);
});

Ce se întâmplă când nu este setată nicio destinație?

Nu vă ajunge nimic, și nimic nu așteaptă să fie trimis mai târziu. Un număr fără webhook_url revine la callback-ul easyCoexistence, unde mesajele sale sunt eliminate fără a fi stocate, și nu primește import de istoric de chat, care se cere doar după ce există o destinație. Un cont social fără destinație nu este transmis: evenimentele sale ajung tot la aplicația easyCoexistence, dar niciunul nu este păstrat pentru dumneavoastră. Setați fiecare destinație înainte de a avea nevoie de trafic.

Ce se întâmplă cu o destinație când o conexiune cade sau este ștearsă?

Un număr își păstrează destinația în evidență. Când un număr căzut se reconectează, easyCoexistence vă setează din nou URL-ul la Meta, la fel ca atunci când un număr suspendat revine. Ștergerea unui cont social șterge destinația și secretul său, așa că după reconectare apelați din nou PUT /channels/{id}/webhook și stocați noul secret. Acest PUT emite un secret nou ori de câte ori este apelat cu un URL, iar cel vechi încetează imediat să mai semneze.

Cum să îl configurați

  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.

Greșeli frecvente

  • Verificarea X-Hub-Signature-256 la livrările WhatsApp ale clienților dumneavoastră. Meta îl calculează cu secretul aplicației easyCoexistence, care nu este împărtășit niciodată, deci verificarea nu poate trece; autentificați-vă cu secretul din calea URL-ului.
  • Verificarea X-EC-Signature peste JSON-ul parsat. HMAC acoperă corpul brut octet cu octet, iar reserializarea schimbă octeții, deci verificați înainte de parsare.
  • Folosirea unui singur secret pentru toate canalele. Fiecare cont social semnează cu propriul secret, iar evenimentele de stare cu altul, așa că aveți nevoie să căutați secretul după account_id.
  • Munca lentă înainte de a răspunde unui eveniment transmis. Acesta este trimis o singură dată, așteaptă 8 secunde răspunsul dumneavoastră și nu este reîncercat niciodată, așa că răspundeți mai întâi cu 2xx și procesați după.
Faceți acest lucru cu EasyCoexistence

easyCoexistence direcționează mesajele fiecărui număr de client de la Meta direct către serverul dumneavoastră și transmite comentariile și DM-urile de pe Instagram și Facebook, precum și comentariile de pe TikTok, către endpoint-ul dumneavoastră pe măsură ce sosesc, semnate pentru fiecare cont, fără nicio copie păstrată și cu fiecare conexiune monitorizată 24/7. De la US$ 9 până la US$ 0.75 pe conexiune pe lună, pe măsură ce adăugați conexiuni, cu perioadă de probă gratuită de 3 zile.

Întrebări frecvente

Pot verifica semnătura Meta la mesajele WhatsApp ale clienților mei?

Nu. Meta le semnează cu secretul aplicației Tech Provider a easyCoexistence, care nu este împărtășit niciodată. Autentificați-vă cu secretul lung și aleatoriu din calea URL-ului și, opțional, cu intervalele IP ale Meta.

Conexiunile YouTube și LinkedIn transmit evenimentele de comentarii?

Nu. easyCoexistence nu primește evenimente de comentarii de la niciuna dintre ele, așa că PUT /channels/{id}/webhook răspunde 400 not_supported. Citiți comentariile lor prin API-ul fiecărei rețele, cu credențialele canalului.

Evenimentele sociale transmise sunt reîncercate dacă serverul meu este oprit?

Nu. Fiecare este trimis o singură dată, iar nicio copie nu este păstrată. Livrările WhatsApp diferă, deoarece Meta însăși le reîncearcă timp de până la 7 zile.

Mesajele trec prin easyCoexistence?

Pe WhatsApp nu: Meta livrează mesajele unui număr direct la webhook-ul pe care îl setați. Comentariile și DM-urile din rețelele sociale sunt transmise către endpoint-ul dumneavoastră pe măsură ce sosesc, semnate pentru fiecare cont, fără nicio copie păstrată.

Continuați să citiți

Conectați primul canal în două minute.

Fără recenzii de platformă de așteptat. Conectați WhatsApp, Instagram, TikTok sau alt canal, apoi cereți AI-ului să publice, să răspundă sau să raporteze și urmăriți-l cum lucrează.

  • 3 zile gratuit
  • Anulați oricând
  • Doar API-uri oficiale
  • Monitorizat 24/7

Verificat la