Webhook wiadomości Instagrama: payload DM, echa i pola
Pole messages w webhooku Instagrama dostarcza wiadomości prywatne konta profesjonalnego w miarę ich nadejścia: tekst, załączniki, udostępnienia, odpowiedzi na relacje i wzmianki, odpowiedzi wewnątrz wiadomości oraz usunięcia. Każde zdarzenie znajduje się w tablicy messaging z identyfikatorem nadawcy w zakresie Instagrama, odbiorcą, znacznikiem czasu i obiektem message. Wiadomości wysłane przez samo konto wracają w tym samym polu z ustawionym is_echo na true.
easyCoexistence subskrybuje każde połączone konto Instagram do wiadomości i przekazuje jego DM-y, łącznie z echami, na Twój endpoint HTTPS w miarę ich nadejścia, podpisane sekretem tego konta; przekazywanie nie zachowuje kopii, a DM-y nie są domyślnie przechowywane.
Ustawiane na true w zdarzeniu wiadomości dla wiadomości wysłanej przez samo konto.
Standardowe okno wiadomości dla większości działań użytkownika, w którym aplikacja może odpowiedzieć tej osobie.
Typ załącznika udostępnionego posta; stary typ udostępnienia obsługiwano tylko do 1 lutego 2026 roku.
Typ załącznika zdarzenia DM, które Meta wysyła, gdy ktoś wspomni konto w swojej relacji.
Podkod błędu w ramach kodu 200, gdy właściciel konta wyłączył dostęp do wiadomości prywatnych Instagrama.
Kiedy uruchamia się pole messages?
Gdy osoba wyśle koncie profesjonalnemu DM, a także gdy konto wyśle wiadomość. Przykłady i dokumentacja Meta wymieniają te przypadki; każdy to zdarzenie messaging z obiektem message:
- Tekst oraz media jako załączniki: obrazy, wideo, audio i pliki.
- Udostępniony post lub Reel jako załącznik
ig_post,ig_reellub reel. - Odpowiedź na relację konta, z
reply_to.story, oraz relacja, w której konto zostało wspomniane, jako załącznikstory_mention. - Odpowiedź wewnątrz wcześniejszej wiadomości, z
reply_to.mid, oraz szybka odpowiedź, zquick_reply.payload. - Wiadomość usunięta przez osobę (
is_deleted), nieobsługiwane media (is_unsupported) i wiadomość od kogoś, kto kliknął reklamę Click-to-Direct (referral). - Wiadomość wysłana przez konto, która wraca z ustawionym
is_echona true.
Jak wygląda powiadomienie o wiadomościach?
POST, którego JSON ma object ustawiony na instagram. W odróżnieniu od komentarza wiadomość znajduje się w tablicy messaging wewnątrz wpisu konta, a każdy element zawiera sender, recipient, timestamp i message. Odpowiedź na relację konta wygląda tak:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL_FOR_THE_STORY>",
"id": "<STORY_ID>"
}
}
}
}
]
}
]
}Co oznacza każde pole?
Pola, które Meta dokumentuje dla zdarzenia wiadomości w Instagram Login, od zewnątrz do środka:
- entry[].id: identyfikator konta profesjonalnego. entry[].time: moment, w którym Meta wysłała powiadomienie; przykłady Meta podają go w milisekundach.
- sender.id i recipient.id: w przychodzącym DM identyfikator osoby w zakresie Instagrama oraz identyfikator konta; w echu te same dwa, ale w odwrotnej kolejności.
- timestamp: moment wysłania wiadomości, w milisekundach w przykładach Meta. Sortuj wiadomości według niego, a nie według kolejności nadejścia.
- message.mid: identyfikator wiadomości, do deduplikacji, reakcji i odpowiedzi na nią przez
reply_to.mid. - message.text: obecne, gdy wiadomość zawiera tekst.
- message.attachments[]: każdy z typem i payloadem, zwykle z url. Payload
ig_postudostępnionego posta dodajeig_post_media_idoraz title, czyli jego podpis. - message.
reply_to: mid dla odpowiedzi wewnątrz wiadomości albo story z url i id relacji dla odpowiedzi na relację. - message.
quick_reply.payload i message.referral: wybrana szybka odpowiedź oraz ref,ad_id, source, type iads_context_datareklamy Click-to-Direct. - message.
is_deleted,is_echo,is_selfiis_unsupported: obecne tylko wtedy, gdy mają wartość true. - message.
admin_textihandoff_reason: w kwalifikujących się aplikacjach powiadomienie, że aplikacja Meta, np. Meta Business Agent, przekazała rozmowę dalej; może przyjść bez mid i tekstu.
Jak działają echa?
Gdy konto wysyła wiadomość, Meta wysyła dla niej także zdarzenie messages, z ustawionym is_echo na true. Wtedy sender.id to konto, a recipient.id identyfikator osoby w zakresie Instagrama. Wiadomość testowa, którą konto wysyła do siebie, niesie też is_self. Echa zapisują to, co powiedziało konto, czego potrzebuje dziennik rozmów, ale handler decydujący, czy odpowiedzieć, musi je pomijać. Meta nie wysyła echa, gdy konto reaguje na wiadomość albo usuwa reakcję.
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448061203,
"messaging": [
{
"sender": { "id": "<IG_ID>" },
"recipient": { "id": "<IGSID>" },
"timestamp": 1793448060950,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<REPLY_TEXT>",
"is_echo": true
}
}
]
}
]
}Na który identyfikator odpowiadasz?
Na sender.id, czyli identyfikator osoby w zakresie Instagrama. Meta tworzy go, gdy ktoś napisze do konta albo skomentuje jego media, i jest on specyficzny dla tej osoby i tego konta. POST /<IG_ID>/messages z recipient.id ustawionym na ten identyfikator wysyła odpowiedź. Zdarzenie nie zawiera imienia ani nazwy użytkownika; GET /<IGSID> z polami takimi jak name i username je zwraca, ponieważ osoba, która napisała do konta, wyraziła zgodę wymaganą przez to wyszukiwanie.
Jak wiadomość otwiera 24-godzinne okno?
Aplikacja może napisać do osoby dopiero po tym, jak ona napisała do konta, i tylko w standardowym oknie wiadomości, które otwiera jej działanie. Dla większości działań trwa ono 24 godziny, a w przypadku pierwszej wiadomości po kliknięciu reklamy Click-to-Direct nawet do 7 dni. Nowa wiadomość od osoby otwiera nowe okno, więc śledź jej najnowszy znacznik czasu; echo to wiadomość konta i nie wydłuża niczego. Odpowiedzi pisane przez osobę mogą korzystać z osobnego 7-dniowego okna Human Agent Meta, oznaczonego jako human_agent.
Czego zdarzenie wiadomości nie zawiera?
Kilka rzeczy, których mógłby szukać handler, nie występuje, według referencji Meta dotyczących wiadomości:
- Imienia lub nazwy użytkownika osoby: jest tylko identyfikator w zakresie Instagrama, który rozwiązuje GET /<IGSID>.
- Media jednorazowego wyświetlenia: przychodzą jako ulotny załącznik bez URL.
- Dokładnego zdjęcia z karuzeli: reakcja na jedno zdjęcie w karuzeli albo jego przekazanie raportuje pierwsze zdjęcie.
- Reakcji, edycji i potwierdzeń odczytu, które przychodzą w osobnych polach.
- Znacznika przeczytania: wiadomość dostarczona przez webhook pozostaje nieprzeczytana w skrzynce Instagrama, aż zostanie wysłana odpowiedź.
Jakie inne pola wiadomości wymienia Meta?
Lista pól i przykłady Meta dla Instagram Login wymieniają oprócz wiadomości te, każde jako osobne zdarzenie messaging. easyCoexistence subskrybuje każde konto tylko do wiadomości, komentarzy i wzmianek, więc żadne z nich nie jest przekazywane:
message_reactions: osoba reaguje na wiadomość albo usuwa reakcję, z reaction.mid, action ustawionym na react lub unreact, oraz reaction i emoji.message_edit: osoba edytuje wiadomość, zmessage_edit.mid, nowym tekstem inum_edit.messaging_postbacks: osoba dotyka icebreakera albo przycisku szablonu, z postback.mid, title i payload.messaging_referral: osoba już w rozmowie otwiera link ig.me z parametrem ref.messaging_seen: osoba czyta wiadomość, z read.mid.messaging_optins,messaging_handoveri standby: dwa ostatnie dla aplikacji współdzielących rozmowę w ramach protokołu przekazania Meta.
Co konto musi włączyć?
Zezwól na dostęp do wiadomości. Meta wymaga, by konto profesjonalne to włączyło, zanim jego wiadomości będzie można zarządzać przez API. W aplikacji Instagram, w Ustawieniach, w sekcji „Wiadomości i odpowiedzi na relacje”, w kontrolkach wiadomości, w połączonych narzędziach. Dopóki jest wyłączone, wysyłki kończą się błędem o kodzie 200 i podkodzie 2534041. Aplikacja potrzebuje też instagram_business_basic i instagram_business_manage_messages, a do obsługi kont, których nie posiada ani nimi nie zarządza, dostępu Advanced Access.
Jak easyCoexistence przekazuje DM?
Tak jak komentarz: każdy wpis, który Meta dostarcza dla konta, jest wysyłany metodą POST na twój endpoint HTTPS w kopercie z polami platform, account_id, external_id i entry, podpisany w X-EC-Signature sekretem konta, raz i bez zachowywania kopii. Echa są przekazywane razem z resztą, więc sprawdź is_echo przed odpowiedzią. Aby odpowiedzieć, wywołaj send_social_dm z account_id i sender.id zdarzenia jako recipient_id, w ramach 24-godzinnego okna. Automatyzacje startujące od DM działają na tych samych zdarzeniach.
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<IG_ID>",
"entry": {
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"attachments": [
{ "type": "image", "payload": { "url": "<URL_FOR_THE_MEDIA>" } }
]
}
}
]
}
}Typowe błędy
- Odpowiadanie na echa. Zdarzenie z ustawionym is_echo to wiadomość konta, a odpowiedź na nie wprowadza konto w pętlę z samym sobą.
- Zakładanie, że wiadomość zawsze ma tekst. Załączniki, udostępnienia, wzmianki w relacjach i usunięcia nadchodzą bez pola text, więc rozgałęziaj według tego, co zawiera obiekt message.
- Sortowanie wiadomości według kolejności nadejścia. Meta może po awarii dostarczyć wiadomości w złej kolejności, więc sortuj je według timestamp.
- Traktowanie time i timestamp jako sekund. Przykłady Meta podają oba w milisekundach, a odczytane jako sekundy stają się datami daleko w przyszłości.
send_social_dm odpowiada w ramach 24-godzinnego okna, a automatyzacje mogą odpowiadać samodzielnie stałym tekstem lub AI. Od US$ 9 do US$ 0.75 za połączenie miesięcznie, z każdym kolejnym taniej, z pierwszymi 3 dniami bezpłatnego okresu próbnego.
Najczęściej zadawane pytania
Czy znaczniki czasu webhooków wiadomości Instagrama są w sekundach czy milisekundach?
W milisekundach, według przykładów Meta, zarówno dla timestamp, jak i czasu wpisu. Odczytane jako sekundy, stają się datami daleko w przyszłości.
Jak pobrać nazwę użytkownika nadawcy z webhooka DM Instagrama?
Wywołaj GET /<IGSID> z polami takimi jak name i username. Zdarzenie zawiera tylko identyfikator osoby w zakresie Instagrama.
Dlaczego moje webhooki DM Instagrama nie przychodzą?
Sprawdź, czy konto włączyło Zezwól na dostęp do wiadomości, czy jest subskrybowane do wiadomości przez /subscribed_apps i czy aplikacja jest w trybie Live z Advanced Access dla kont, których nie posiada.
Czy easyCoexistence przekazuje reakcje na wiadomości Instagrama?
Nie. Reakcje przychodzą w message_reactions, a easyCoexistence subskrybuje konta do wiadomości, komentarzy i wzmianek.
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