Zaloguj sięRozpocznij bezpłatny okres próbny
easyCoexistence Oficjalne API

Jak odbierać przez webhook wiadomości WhatsApp i komentarze z mediów społecznościowych klientów

Każde połączenie otrzymuje własny webhook dla wiadomości WhatsApp klientów lub komentarzy w mediach społecznościowych, przez Partner API easyCoexistence. Wiadomości WhatsApp trafiają od Meta prosto na ten adres URL i są podpisane sekretem aplikacji Tech Provider, a nie Twoim własnym, dlatego do ich uwierzytelnienia służy długi losowy sekret w ścieżce URL. Komentarze oraz wiadomości prywatne z Instagrama i Facebooka, a także komentarze z TikToka, są przekazywane w momencie nadejścia i podpisywane osobno dla każdego konta za pomocą nagłówka X-EC-Signature.

200 characters

Maksymalna długość, jaką Meta dopuszcza dla alternatywnego adresu URL callbacku, który kieruje wiadomości numeru do Twojego endpointu.

7 days

Jak długo Meta ponawia webhook WhatsApp, którego Twój endpoint nie przyjął, z coraz rzadszymi próbami, co może powodować duplikaty.

AS32934

Sieć Meta; zapytania whois o trasy do niej zawierają adresy, z których przychodzą webhooki WhatsApp, a Meta zmienia je okresowo.

3 MB

Największy możliwy rozmiar treści webhooka WhatsApp według Meta.

5 minutes

Wiek, po którym przekazane zdarzenie z podpisanym znacznikiem czasu powinno zostać odrzucone, przy porównaniu HMAC w stałym czasie.

Jak każde połączenie otrzymuje własny adres docelowy?

Przez jedno wywołanie na zasób. Numer WhatsApp przyjmuje PUT /connections/{id}/webhook z parametrami url i verify_token albo tą samą parą jako webhook_url i webhook_verify_token w sesji połączenia, dzięki czemu numer kieruje ruch do Ciebie od pierwszej minuty. Konto w mediach społecznościowych przyjmuje PUT /channels/{id}/webhook po połączeniu. Wartość url równa null w obu przypadkach wyłącza dostarczanie. Te dwie ścieżki różnią się tym, kto dostarcza dane i jak się uwierzytelniasz:

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

Jak skierować wiadomości numeru do Twojego endpointu?

Podaj adres HTTPS, którego ścieżka zawiera długi losowy sekret, oraz token weryfikacyjny: webhook_verify_token w sesji połączenia, od 8 do 200 znaków, albo verify_token w PUT. Meta sprawdza adres od razu żądaniem GET z hub.mode=subscribe, hub.verify_token i hub.challenge, a Twój endpoint musi odpowiedzieć wartością hub.challenge, gdy token się zgadza. Jeśli to sprawdzenie się nie powiedzie, PUT zwraca 502 meta_rejected z komunikatem samej Meta; w sesji połączenia numer nadal się łączy, a pole last_error sesji podaje, dlaczego adres nie został zastosowany.

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

Dlaczego nie można sprawdzić podpisu Meta i czym go zastąpić?

Meta podpisuje każdą dostawę nagłówkiem X-Hub-Signature-256, czyli HMAC-SHA256 treści, wyliczonym kluczem App Secret odbierającej aplikacji. W przypadku numerów Twoich klientów tą aplikacją jest aplikacja Tech Provider easyCoexistence, a jej sekret nigdy nie jest udostępniany, dlatego nagłówka nie da się zweryfikować po Twojej stronie. Zamiast tego poświadczeniem jest długi losowy sekret w ścieżce URL: porównaj go w stałym czasie i odrzuć wszystko inne. Jako drugą warstwę dopuść na liście tylko trasy zarejestrowane przez Meta w AS32934 i odświeżaj tę listę, bo Meta okresowo zmienia swoje adresy IP.

Które webhooki WhatsApp docierają do Twojego adresu URL?

Pola, które alternatywny adres URL callbacku Meta może przenosić: messages, czyli wiadomości od klientów i status wysłanych przez Ciebie; smb_message_echoes, czyli wiadomości wysłane przez firmę z aplikacji WhatsApp Business; oraz historia i smb_app_state_sync z jednorazowego importu. Meta nigdy nie wysyła na ten adres webhooków szablonów ani webhooków konta, takich jak account_update. Trafiają one zamiast tego do callbacku easyCoexistence, dlatego sprawdzanie statusu szablonów odbywa się przez odpytywanie, a odrzucenie szablonu dociera do Ciebie jako zdarzenie statusu.

  • Adres docelowy ustawia się na koncie WhatsApp Business, więc dwa numery w jednym koncie dzielą go: kieruj ruch według value.metadata.phone_number_id.
  • Multimedia przychodzą jako ID; pobierz plik z Meta tokenem klienta z wywołania poświadczeń.
  • Ładunki mogą mieć do 3 MB, więc podnieś każdy limit rozmiaru treści ustawiony poniżej tej wartości.

Jak wygląda przekazane zdarzenie z mediów społecznościowych?

Żądanie POST z Content-Type application/json i nagłówkiem X-EC-Signature, zawierające cztery klucze: platform; account_id, czyli ID kanału używane przez Partner API; external_id, czyli ID konta w sieci; oraz entry. Dla Instagrama i Facebooka entry to niezmieniony wpis webhooka Meta, z changes dla komentarzy i wzmianek oraz messaging dla wiadomości prywatnych. Dla TikToka zawiera zdarzenie comment.update z przetworzoną treścią oraz comment_id, video_id i parent_comment_id jako ciągi znaków, dzięki czemu 64-bitowe ID nie zostaną zaokrąglone.

  • Konta Instagram są zapisane na komentarze, wiadomości i wzmianki; strony Facebook na feed, wiadomości i wzmianki; TikTok wysyła comment.update.
  • easyCoexistence nie otrzymuje zdarzeń komentarzy z YouTube ani LinkedIn: ich PUT zwraca 400 not_supported, a komentarze odczytujesz przez API każdej sieci z poświadczeniami.
  • Przekazania nie zawierają nagłówków X-EC-Event ani X-EC-Delivery, więc deduplikuj na podstawie identyfikatorów samej sieci, na przykład ID komentarza albo mid wiadomości.
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>" }
        }
      }
    ]
  }
}

Jak krok po kroku zweryfikować X-EC-Signature?

Użyj signing_secret zwróconego przez PUT /channels/{id}/webhook; jest pokazywany tylko raz i jest unikalny dla danego konta. Nagłówek ma postać t=<unix>,v1=<hex>. Następnie, dla każdej dostawy:

  • Odczytaj surowe ciało żądania jako bajty, przed jakimkolwiek parsowaniem JSON.
  • Podziel nagłówek po przecinkach na t, czas Unix w sekundach, oraz v1, skrót w formacie hex.
  • Odrzuć dostawę, jeśli t różni się od Twojego zegara o więcej niż 5 minut.
  • Oblicz HMAC-SHA256 dla ciągu: t, kropka i surowe ciało, kluczem sekretu danego konta, w formacie hex.
  • Porównaj wynik z v1 w stałym czasie, potem odpowiedz 2xx i dodaj zadanie do kolejki.
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);
});

Co się dzieje, gdy nie ustawiono adresu docelowego?

Nic do Ciebie nie dociera i nic nie czeka na późniejsze wysłanie. Numer bez webhook_url przechodzi na callback easyCoexistence, gdzie jego wiadomości są pomijane bez zapisu, a import historii czatu nie jest wykonywany, bo jest zlecany dopiero po utworzeniu adresu docelowego. Konto w mediach społecznościowych bez adresu nie jest przekazywane: jego zdarzenia nadal trafiają do aplikacji easyCoexistence, ale żadne nie jest przechowywane dla Ciebie. Ustaw każdy adres docelowy, zanim będziesz potrzebować ruchu.

Co się dzieje z adresem docelowym, gdy połączenie zostanie przerwane lub usunięte?

Numer zachowuje swój adres docelowy w rejestrze. Gdy przerwany numer połączy się ponownie, easyCoexistence ustawia Twój URL w Meta na nowo; tak samo dzieje się, gdy zawieszony numer wraca. Usunięcie konta w mediach społecznościowych czyści jego adres docelowy i sekret, więc po ponownym połączeniu wywołaj PUT /channels/{id}/webhook jeszcze raz i zapisz nowy sekret. Ten PUT wystawia nowy sekret za każdym razem, gdy zostanie wywołany z adresem URL, a stary przestaje podpisywać od razu.

Jak to skonfigurować

  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.

Typowe błędy

  • Sprawdzanie X-Hub-Signature-256 w dostawach WhatsApp od Twoich klientów. Meta liczy go kluczem App Secret easyCoexistence, który nigdy nie jest udostępniany, więc sprawdzenie nie może się udać; uwierzytelniaj sekretem w ścieżce URL.
  • Weryfikowanie X-EC-Signature po sparsowaniu JSON. HMAC obejmuje surowe ciało bajt po bajcie, a ponowna serializacja zmienia bajty, więc weryfikuj przed parsowaniem.
  • Używanie jednego sekretu dla wszystkich kanałów. Każde konto w mediach społecznościowych podpisuje własnym sekretem, a zdarzenia statusu innym, więc wyszukuj sekret po account_id.
  • Wykonywanie wolnej pracy przed odpowiedzią na przekazane zdarzenie. Jest ono wysyłane raz, czeka 8 sekund na Twoją odpowiedź i nigdy nie jest ponawiane, więc najpierw odpowiedz 2xx, a dopiero potem przetwarzaj.
Z EasyCoexistence zrobisz to

easyCoexistence kieruje wiadomości każdego numeru klienta z Meta prosto na Twój serwer i przekazuje komentarze oraz wiadomości prywatne z Instagrama i Facebooka, a także komentarze z TikToka, na Twój endpoint w momencie ich nadejścia, podpisane osobno dla każdego konta, bez zachowywania kopii i z monitorowaniem każdego połączenia 24/7. Od US$ 9 do US$ 0.75 za połączenie miesięcznie, spadając wraz z dodawaniem połączeń, z pierwszymi 3 dniami bezpłatnie.

Najczęściej zadawane pytania

Czy mogę zweryfikować podpis Meta w wiadomościach WhatsApp moich klientów?

Nie. Meta podpisuje je sekretem aplikacji Tech Provider easyCoexistence, który nigdy nie jest udostępniany. Uwierzytelniaj długim losowym sekretem w ścieżce URL, a opcjonalnie zakresami adresów IP Meta.

Czy połączenia z YouTube i LinkedIn przekazują zdarzenia komentarzy?

Nie. easyCoexistence nie otrzymuje zdarzeń komentarzy z żadnej z tych sieci, więc PUT /channels/{id}/webhook zwraca 400 not_supported. Komentarze odczytuj przez API każdej sieci z poświadczeniami kanału.

Czy przekazane zdarzenia z mediów społecznościowych są ponawiane, gdy mój serwer nie działa?

Nie. Każde jest wysyłane raz i nie zachowuje się żadnej kopii. Dostawy WhatsApp są inne, ponieważ Meta sama ponawia je przez maksymalnie 7 dni.

Czy wiadomości przechodzą przez easyCoexistence?

Nie w przypadku WhatsApp: Meta dostarcza wiadomości numeru prosto na webhook, który ustawisz. Komentarze i wiadomości prywatne z sieci społecznościowych są przekazywane na Twój endpoint w momencie nadejścia, podpisane osobno dla każdego konta, bez zachowywania kopii.

Czytaj dalej

Połącz pierwszy kanał w dwie minuty.

Bez czekania na weryfikację przez platformy. Połącz WhatsApp, Instagram, TikTok lub inny kanał, a potem poproś swoją AI o opublikowanie posta, odpowiedź lub raport i zobacz, jak działa.

  • 3 dni za darmo
  • Rezygnacja w każdej chwili
  • Tylko oficjalne API
  • Monitorowanie 24/7

Zweryfikowano w