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

Webhook Messengera na Facebooku: wiadomości i zdarzenia wzmianek

Pole messages w webhookach stron na Facebooku uruchamia się, gdy osoba wysyła stronie wiadomość w Messengerze. Dostarcza tablicę messaging z identyfikatorem nadawcy ograniczonym do strony, identyfikatorem strony, znacznikiem czasu oraz mid wiadomości z jej tekstem lub załącznikami. Pole mention zgłasza nowe wzmianki o stronie w postach i komentarzach. Meta podpisuje oba typy nagłówkiem X-Hub-Signature-256.

easyCoexistence przekazuje wiadomości Messengera i wzmianki każdej połączonej strony na Twój endpoint HTTPS w miarę ich nadejścia, podpisane sekretem dla tej strony i bez zachowywania kopii, a send_social_dm wysyła odpowiedzi w ramach 24-godzinnego okna.

5 seconds

Jak szybko Meta oczekuje od endpointu webhooka Messengera odpowiedzi 200 OK na każde powiadomienie.

1 hour

Po tak długim czasie nieudanych dostarczeń Meta wypisuje aplikację z webhooków strony, dopóki ta ich ponownie nie zasubskrybuje.

PSID

Identyfikator nadawcy ograniczony do strony w zdarzeniu messages, unikalny dla każdej pary osoby i strony.

Workplace only

Jak dokumentacja firmy Meta opisuje pole sender w zdarzeniu mention.

No history

Minionych powiadomień webhooków nie da się pobrać później, więc odbiorca musi zapisać to, czego potrzebuje.

Co wysyła pole messages?

Powiadomienie, gdy osoba wysyła stronie wiadomość w Messengerze. Meta przesyła wiadomości tekstowe oraz wiadomości z załącznikami, którymi mogą być m.in. obrazy, nagrania audio, wideo, pliki lub naklejki, a udostępniony link może dotrzeć jako załącznik zastępczy. Odpowiedź na wcześniejszą wiadomość zawiera reply_to z jej mid, a szybka odpowiedź zawiera swój payload.

Jak wygląda zdarzenie messages?

W przeciwieństwie do zmian w feedzie wiadomość trafia do tablicy messaging wewnątrz entry strony. Każde zdarzenie ma sender, czyli identyfikator nadawcy ograniczony do strony; recipient, czyli strona; timestamp; oraz message z jego mid i tekstem albo attachments z typem i adresem URL payloadu:

A messages event, as Meta sends it
{
  "object": "page",
  "entry": [
    {
      "id": "<PAGE_ID>",
      "time": 1458692752478,
      "messaging": [
        {
          "sender": { "id": "<PSID>" },
          "recipient": { "id": "<PAGE_ID>" },
          "timestamp": 1458692752478,
          "message": {
            "mid": "<MESSAGE_ID>",
            "text": "hello, world!"
          }
        }
      ]
    }
  ]
}

Co wysyła pole mention?

Zmianę z polem mention, gdy strona zostanie wspomniana w poście lub komentarzu. Zawiera post_id lub comment_id, treść wiadomości, ewentualny link, zdjęcie lub wideo oraz item i verb. Meta ostrzega, że części tych identyfikatorów postów i komentarzy nie da się pobrać z powodu braku uprawnień lub względów prywatności, a jej dokumentacja oznacza pole sender wyłącznie dla Workplace, więc wzmianka może dotrzeć bez autora.

Które pola Messengera nie są przekazywane?

easyCoexistence subskrybuje strony na messages, a nie na message_echoes, messaging_postbacks, message_reads ani message_deliveries, więc wiadomości wysłane przez stronę, kliknięcia przycisków oraz potwierdzenia odczytania i dostarczenia nie są przekazywane. Odpowiedź wysłana przez send_social_dm zwraca natomiast własny identyfikator wiadomości.

Jak zdarzenia docierają do Twojego endpointu?

Meta dostarcza webhooki stron do aplikacji, którą strona zainstalowała, przez jeden adres callback dla całej aplikacji. easyCoexistence sprawdza podpis X-Hub-Signature-256 przy każdym dostarczeniu, od razu odpowiada firmie Meta i przekazuje każdy wpis dotyczący połączonej strony na endpoint HTTPS, który dla niej podajesz, podpisany sekretem tej strony. Ustaw go poleceniem set_social_webhook_destination z poziomu Claude lub ChatGPT albo przez PUT /channels/:id/webhook w Partner API. Sekret jest pokazywany jednorazowo, ponowne ustawienie generuje nowy, a wartość null dla adresu URL wyłącza przekazywanie.

Jak wygląda przekazane zdarzenie?

Żądanie POST zawierające platform, account_id, który zwraca list_social_accounts dla połączenia strony, identyfikator strony jako external_id oraz entry: wpis firmy Meta dla strony, bez zmian. sender.id to recipient_id, którego używa send_social_dm przy odpowiedzi w ramach 24-godzinnego okna:

A forwarded messages event
{
  "platform": "facebook",
  "account_id": "<ACCOUNT_ID>",
  "external_id": "<PAGE_ID>",
  "entry": {
    "id": "<PAGE_ID>",
    "time": 1793318400000,
    "messaging": [
      {
        "sender": { "id": "<PSID>" },
        "recipient": { "id": "<PAGE_ID>" },
        "timestamp": 1793318399000,
        "message": { "mid": "<MESSAGE_ID>", "text": "<MESSAGE_TEXT>" }
      }
    ]
  }
}

Jak zweryfikować przekazane zdarzenie?

Każde przekazane żądanie POST zawiera nagłówek X-EC-Signature w postaci t=<unix>,v1=<hex>, gdzie v1 to HMAC-SHA256 liczony z połączenia znacznika czasu, kropki i surowego ciała, z kluczem będącym sekretem podpisu strony. Oblicz go na ciele dokładnie w takiej postaci, w jakiej przyszło, porównaj w stałym czasie i odrzuć znacznik czasu starszy niż 5 minut.

Node.js: verifying X-EC-Signature
import crypto from "node:crypto";

// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
  const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  if (!sig.t || !sig.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(sig.t + "." + rawBody)
    .digest("hex");
  return expected.length === sig.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}

Czy dostarczenie jest ponawiane?

Nie przez easyCoexistence. Każdy wpis jest przekazywany jednokrotnie, w pamięci, bez kopii, z której można by ponowić próbę; przekazanie czeka 8 sekund na odpowiedź, nie podąża za przekierowaniami i trafia wyłącznie na adres HTTPS rozwiązujący się do publicznego IP. Meta zauważa, że minionych powiadomień nie da się pobrać później, więc zapisuj to, czego potrzebujesz, w momencie jego nadejścia. Po stronie firmy Meta nieudane dostarczenie jest ponawiane kilka razy od razu, więc ta sama wiadomość może sporadycznie dotrzeć dwukrotnie: deduplikuj ją po jej mid.

Typowe błędy

  • Wykonywanie pracy przed odpowiedzią. Przekazywanie nie ponawia prób, więc zwróć od razu 2xx i przetwarzaj zdarzenie później.
  • Weryfikowanie podpisu na sparsowanym JSON. Oblicz HMAC na surowym ciele dokładnie w takim kształcie, w jakim przyszło.
  • Zakładanie, że wiadomość zawsze ma tekst. Naklejka, obraz lub udostępniony link przychodzi jako attachments, bez pola text.
  • Pominięcie deduplikacji. Meta może ponownie dostarczyć zdarzenie po awarii, więc przed działaniem kluczuj je po mid wiadomości.
Z EasyCoexistence zrobisz to

Przekazywanie włączysz poleceniem set_social_webhook_destination lub przez Partner API. Od US$ 9 do US$ 0.75 za połączenie miesięcznie, spadając wraz z dodawaniem połączeń, z 3-dniowym bezpłatnym okresem próbnym.

Najczęściej zadawane pytania

Które pola webhooków easyCoexistence subskrybuje dla strony?

messages dla Messengera i mention dla wzmianek, obok feed dla postów i komentarzy strony.

Czy naklejka lub obraz z Messengera ma tekst?

Nie. Naklejka, obraz lub udostępniony link przychodzi w attachments, każdy z typem i adresem URL payloadu, a wiadomość nie zawiera pola text.

Jak szybko endpoint webhooka Messengera musi odpowiedzieć?

Odpowiedzią 200 OK w ciągu 5 sekund. Po 1 godzinie nieudanych dostarczeń Meta wypisuje aplikację z webhooków strony.

Jak odpowiedzieć na przekazaną wiadomość?

Wywołaj send_social_dm, podając sender.id ze zdarzenia jako recipient_id, w ciągu 24 godzin od wiadomości osoby.

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