Załączniki Instagram DM w webhooku wiadomości
Webhook wiadomości Instagrama przenosi media z DM w message.attachments: tablicę obiektów, z których każdy ma type i payload, zwykle zawierający URL CDN. Lista Meta dla Instagram Login wymienia image, video, audio, file, ig_post, ig_reel, reel, story_mention, media, story, ig_story oraz przestarzały share, a media jednorazowego wyświetlenia przychodzą jako efemeryczny załącznik bez URL.
easyCoexistence subskrybuje każde połączone konto Instagrama do messages i przekazuje DM z załącznikami na Twój endpoint HTTPS takie, jakie wysyła je Meta, podpisane sekretem tego konta i bez zachowanej kopii, więc Twój agent lub kod pobiera potrzebne media samodzielnie.
Typ załącznika dla udostępnionego posta; jego payload dodaje ig_post_media_id i title, czyli podpis posta, obok url.
Kiedy przestarzały typ załącznika share przestał być obsługiwany dla udostępnień postów na Instagramie.
Typ załącznika dla znikających mediów jednorazowego wyświetlenia, które przychodzą bez URL.
Ustawiane na true w zdarzeniu message, gdy wiadomość zawiera nieobsługiwane media.
Co powiadomienie zgłasza, gdy ktoś zareaguje na jeden obraz z karuzeli posta lub go prześle dalej.
Jakie typy załączników może nieść zdarzenie DM?
Przykłady Meta dla Instagram Login wymieniają te wartości message.attachments[].type, każda z obiektem payload. Większość payloadów zawiera url do mediów w CDN Meta, a dodatkowe pola payloadu Meta opisuje tylko dla ig_post, więc sprawdź najpierw typ, a dopiero potem payload.
Jak wygląda DM z załącznikami?
Zdarzenie messages, którego obiekt message zawiera attachments zamiast tekstu lub obok niego. Przykład Meta wysyła dwa media w jednej wiadomości, każde z własnym type i payload.url, więc handler musi przejść po tablicy, a nie czytać jej pierwszego elementu:
{
"object": "instagram",
"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": "<CDN_URL>" } },
{ "type": "video", "payload": { "url": "<CDN_URL>" } }
]
}
}
]
}
]
}Jak wygląda udostępniony post?
Załącznik ig_post. Od 3 listopada 2025 Meta wysyłała udostępnienia postów z oboma załącznikami: share i ig_post; share był obsługiwany dla postów do 1 lutego 2026, a Meta podaje, że nowe integracje muszą obsługiwać ig_post. Jego payload dodaje identyfikator mediów posta i jego podpis jako title:
"attachments": [
{
"type": "ig_post",
"payload": {
"ig_post_media_id": "<MEDIA_ID>",
"title": "<POST_CAPTION>",
"url": "<CDN_URL>"
}
}
]Co oznacza każde pole?
Pola załączników, które Meta dokumentuje dla zdarzenia DM, od tablicy w dół:
- message.attachments[]: jeden obiekt na element multimedialny; przykład Meta zawiera dwa w jednej wiadomości.
- type: czym jest element, z listy powyżej. Rozgałęź na jego podstawie, zanim odczytasz payload.
- payload.url: adres URL CDN dla mediów. Przegląd Meta nazywa te adresy uwzględniające prywatność: nie zwracają niczego, gdy treść zostanie usunięta lub wygaśnie.
- payload.
ig_post_media_idi payload.title: tylko przyig_post, identyfikator mediów udostępnionego posta i jego podpis. - message.text: obecne tylko wtedy, gdy wiadomość zawiera również tekst.
- message.
is_unsupported: true, gdy wiadomość zawiera media, których webhook nie obsługuje.
Jak długo działają adresy URL załączników?
Meta wiąże je z treścią. Przegląd Meta mówi, że adresy CDN Instagrama uwzględniające prywatność przestają zwracać media, gdy treść zostanie usunięta lub wygaśnie, a przewodnik po wzmiankach w Story mówi, że adres Story przestaje się wyświetlać, gdy Story wygaśnie lub zostanie usunięte. Aplikacja, która potrzebuje pliku, powinna pobrać go w chwili nadejścia zdarzenia, w granicach zasad Meta: media Story, na przykład, nie mogą być przechowywane ani buforowane.
Których mediów webhook nie obejmuje?
Przewodnik po wiadomościach Instagrama Meta wymienia te luki, których handler powinien się spodziewać, a nie traktować ich jako błędów:
- Media znikające: jednorazowego wyświetlenia lub z zezwoleniem na odtworzenie: załącznik typu ephemeral, bez URL.
- Media nieobsługiwane: wiadomość przychodzi z
is_unsupportedustawionym na true. - GIF-y i naklejki: przewodnik mówi, że nie wywołują webhooka, podczas gdy przykłady Meta dla Instagram Login wymieniają je pod image.
- Konkretny obraz karuzeli: reakcja na jeden obraz w poście karuzeli lub jego przekazanie zgłasza pierwszy obraz.
- Udostępnienia w ogóle: przewodniki Meta nadal mówią, że zawiera się tylko URL udostępnionych mediów, choć
ig_postdodaje teraz identyfikator mediów i podpis.
Jak easyCoexistence przekazuje załączniki?
Bez zmian, wewnątrz wpisu: DM z multimediami trafia do Twojego endpointu z tablicą attachments od Meta w takiej postaci, w jakiej wysłała ją Meta, w kopercie z platform, account_id, external_id i entry, podpisanej nagłówkiem X-EC-Signature. Załączniki nie są pobierane, a zdarzenia nie są domyślnie przechowywane: konto z włączoną automatyzacją zachowuje treść DM, a nie jego multimedia, przez 7 dni. Pobierz potrzebne multimedia z payload.url w chwili nadejścia zdarzenia i nie przechowuj mediów Story.
Typowe błędy
- Czytanie tylko pierwszego załącznika. message.attachments jest tablicą, a przykład Meta zawiera dwa elementy w jednej wiadomości, więc przejdź po całej tablicy.
- Nadal dopasowywanie typu share dla udostępnionych postów. Meta obsługiwała go dla postów do 1 lutego 2026; czytaj ig_post, z identyfikatorem mediów i podpisem w payloadzie.
- Zapisywanie payload.url do późniejszego pobrania. Przestaje zwracać media, gdy treść zostanie usunięta lub wygaśnie, więc pobierz, czego potrzebujesz, w chwili nadejścia, z wyjątkiem mediów Story.
- Czytanie payload.url bez sprawdzenia typu. Media jednorazowego wyświetlenia przychodzą jako ephemeral bez URL, a nieobsługiwane media ustawiają is_unsupported.
send_social_dm odpowiada w ramach 24-godzinnego okna. Od US$ 9 do US$ 0.75 za połączenie miesięcznie, spadając w miarę dodawania połączeń, z bezpłatnym okresem próbnym przez pierwsze 3 dni.
Najczęściej zadawane pytania
Czy mogę przechowywać media z załącznika DM na Instagramie?
Pobierz, czego potrzebujesz, w chwili nadejścia zdarzenia, ponieważ payload.url przestaje zwracać media, gdy treść zostanie usunięta lub wygaśnie. Wyjątkiem są media Story: zgodnie z zasadami Meta nie mogą być przechowywane ani buforowane.
Dlaczego webhook wiadomości DM na Instagramie nie ma adresu URL mediów?
Zwykle dlatego, że media są jednorazowego wyświetlenia i przychodzą jako ephemeral bez URL, albo są nieobsługiwane, co ustawia is_unsupported na true.
Czy GIF-y i naklejki z Instagrama wywołują webhook wiadomości?
Dokumentacja Meta jest niezgodna: przykłady Meta dla Instagram Login wymieniają GIF-y i naklejki pod image, a przewodnik po wiadomościach Instagrama mówi, że nie wywołują webhooka. Przetestuj na prawdziwym koncie.
Czy jedno zdarzenie DM z Instagrama może nieść kilka załączników?
Tak. message.attachments jest tablicą, a przykład Meta pokazuje dwa elementy multimedialne w jednej wiadomości.
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