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

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.

is_echo

Ustawiane na true w zdarzeniu wiadomości dla wiadomości wysłanej przez samo konto.

24 hours

Standardowe okno wiadomości dla większości działań użytkownika, w którym aplikacja może odpowiedzieć tej osobie.

ig_post

Typ załącznika udostępnionego posta; stary typ udostępnienia obsługiwano tylko do 1 lutego 2026 roku.

story_mention

Typ załącznika zdarzenia DM, które Meta wysyła, gdy ktoś wspomni konto w swojej relacji.

2534041

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_reel lub reel.
  • Odpowiedź na relację konta, z reply_to.story, oraz relacja, w której konto zostało wspomniane, jako załącznik story_mention.
  • Odpowiedź wewnątrz wcześniejszej wiadomości, z reply_to.mid, oraz szybka odpowiedź, z quick_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_echo na 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:

A messages notification, as Meta sends it
{
  "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_post udostępnionego posta dodaje ig_post_media_id oraz 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 i ads_context_data reklamy Click-to-Direct.
  • message.is_deleted, is_echo, is_self i is_unsupported: obecne tylko wtedy, gdy mają wartość true.
  • message.admin_text i handoff_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ę.

An echo of a message the account sent
{
  "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ść, z message_edit.mid, nowym tekstem i num_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_handover i 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.

A forwarded DM with an image
{
  "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.
Z EasyCoexistence zrobisz to

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