Conectați-văÎncepeți perioada de probă gratuită
easyCoexistence API-uri oficiale

Webhook-ul de mesaje Instagram: payload-ul DM, echo-urile și câmpurile

Câmpul messages din webhook-ul Instagram livrează DM-urile unui cont profesional pe măsură ce sosesc: text, atașamente, distribuiri, mențiuni și răspunsuri la Story, răspunsuri inline și ștergeri. Fiecare eveniment se află într-un array-ul messaging, cu ID-ul specific Instagram al expeditorului, destinatarul, un timestamp-ul și obiectul message, iar mesajele trimise de contul însuși revin pe același câmp cu is_echo setat la true.

easyCoexistence abonează fiecare cont Instagram conectat la messages și transmite DM-urile sale, inclusiv echo-urile, către endpoint-ul dumneavoastră HTTPS pe măsură ce sosesc, semnate cu secretul acelui cont; redirecționarea nu păstrează nicio copie, iar DM-urile nu sunt stocate implicit.

is_echo

Setat la true pe un eveniment de mesaj pentru un mesaj trimis chiar de cont.

24 hours

Fereastra standard de mesagerie pentru majoritatea acțiunilor utilizatorului, în care aplicația poate răspunde persoanei.

ig_post

Tipul de atașament pentru o postare distribuită; vechiul tip de distribuire a fost acceptat doar până la 1 februarie 2026.

story_mention

Tipul de atașament al evenimentului DM pe care Meta îl trimite când cineva menționează contul în Story-ul său.

2534041

Subcodul de eroare, sub codul 200, când titularul contului a dezactivat accesul la mesajele directe Instagram.

Când se declanșează câmpul messages?

Când o persoană trimite un DM contului profesional și când contul trimite unul. Exemplele și referințele Meta enumeră aceste cazuri, fiecare fiind un eveniment de mesagerie cu un obiect message:

  • Text și media ca atașamente: imagini, video, audio și fișiere.
  • O postare sau un Reel distribuit, ca atașament ig_post, ig_reel sau reel.
  • Un răspuns la Story-ul contului, cu reply_to.story, și un Story care menționează contul, ca atașament story_mention.
  • Un răspuns inline la un mesaj anterior, cu reply_to.mid, și un răspuns rapid, cu quick_reply.payload.
  • Un mesaj șters de persoană (is_deleted), un conținut media neacceptat (is_unsupported) și un mesaj de la cineva care a dat clic pe o reclamă Click-to-Direct (referral).
  • Un mesaj trimis de cont, care revine cu is_echo setat la true.

Cum arată o notificare de mesaje?

Un POST al cărui JSON are object setat la instagram. Spre deosebire de un comentariu, un mesaj se află într-un array messaging în interiorul intrării contului, iar fiecare element conține sender, recipient, timestamp și message. Un răspuns la Story-ul contului arată astfel:

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>"
              }
            }
          }
        }
      ]
    }
  ]
}

Ce înseamnă fiecare câmp?

Câmpurile pe care Meta le documentează pentru un eveniment de mesaj sub Instagram Login, de la exterior spre interior:

  • entry[].id: ID-ul contului profesional. entry[].time: momentul în care Meta a trimis notificarea; exemplele de mesagerie ale Meta îl dau în milisecunde.
  • sender.id și recipient.id: la un DM primit, ID-ul Instagram specific al persoanei și ID-ul contului; la un echo, aceleași două valori inversate.
  • timestamp: momentul în care a fost trimis mesajul, în milisecunde în exemplele Meta. Ordonați mesajele după el, nu după ordinea sosirii.
  • message.mid: ID-ul mesajului, pentru deduplicare, reacții și pentru a răspunde la acel mesaj cu reply_to.mid.
  • message.text: inclus atunci când mesajul conține text.
  • message.attachments[]: fiecare cu un type și un payload, de obicei un url. Payload-ul ig_post al unei postări distribuite adaugă ig_post_media_id și title, adică legenda sa.
  • message.reply_to: mid pentru un răspuns inline sau story, cu url-ul și id-ul Story-ului pentru un răspuns la Story.
  • message.quick_reply.payload și message.referral: răspunsul rapid ales și ref, ad_id, source, type și ads_context_data ale reclamei Click-to-Direct.
  • message.is_deleted, is_echo, is_self și is_unsupported: incluse doar atunci când au valoarea true.
  • message.admin_text și handoff_reason: la aplicațiile eligibile, o notificare că o aplicație Meta, precum Meta Business Agent, a preluat conversația; poate sosi fără mid sau text.

Cum funcționează echo-urile?

Când contul trimite un mesaj, Meta trimite și un eveniment de mesaje pentru el, cu is_echo setat la true. sender.id este atunci contul, iar recipient.id ID-ul Instagram specific al persoanei, iar un mesaj de test pe care contul îl trimite către sine poartă și is_self. Echo-urile consemnează ce a spus contul, lucru de care are nevoie un jurnal de conversație, dar handler-ul care decide dacă răspunde trebuie să le ignore. Meta nu trimite niciun echo când contul reacționează la un mesaj sau elimină o reacție.

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
          }
        }
      ]
    }
  ]
}

Ce ID folosiți pentru răspuns?

sender.id, ID-ul Instagram specific persoanei. Meta îl creează când cineva trimite un mesaj contului sau comentează la conținutul acestuia, iar el este specific acelei persoane și acelui cont. POST /<IG_ID>/messages cu recipient.id setat la el trimite răspunsul. Evenimentul nu conține nume sau numele de utilizator; GET /<IGSID> cu câmpuri precum name și username le returnează, deoarece o persoană care a scris contului a dat consimțământul pe care îl cere această interogare.

Cum deschide un mesaj fereastra de 24 de ore?

O aplicație poate trimite un mesaj unei persoane doar după ce aceasta a scris contului și doar în fereastra standard de mesagerie deschisă de acțiunea ei. Pentru majoritatea acțiunilor, ea durează 24 de ore și până la 7 zile de la un prim mesaj trimis după ce s-a dat clic pe o reclamă Click-to-Direct. Un nou mesaj de la persoană deschide o nouă fereastră, deci cel care trebuie urmărit este timestamp-ul cel mai recent; un echo este mesajul contului însuși și nu prelungește nimic. Răspunsurile scrise de o persoană pot folosi fereastra separată de 7 zile Human Agent a Meta, etichetată human_agent.

Ce nu conține un eveniment de mesaje?

Câteva lucruri pe care un handler le-ar putea căuta lipsesc, potrivit referințelor Meta pentru mesagerie:

  • Numele sau numele de utilizator al persoanei: doar ID-ul Instagram specific, pe care GET /<IGSID> îl rezolvă.
  • Conținutul media vizualizabil o singură dată: sosește ca atașament efemer, fără URL.
  • Imaginea exactă din carusel: o reacție la o imagine dintr-o postare carusel, sau o redirecționare a acesteia, raportează prima imagine.
  • Reacțiile, editările și confirmările de citire, care vin pe câmpuri proprii.
  • Un marcaj de citit: un mesaj livrat prin webhook rămâne necitit în inbox-ul Instagram până când se trimite un răspuns.

Ce alte câmpuri de mesagerie enumeră Meta?

Lista de câmpuri și exemplele Meta pentru Instagram Login le numesc pe lângă messages, fiecare fiind un eveniment de mesagerie propriu. easyCoexistence abonează fiecare cont doar la messages, comments și mentions, așa că niciunul dintre ele nu face parte din ce transmite:

  • message_reactions: o persoană reacționează la un mesaj sau elimină reacția, cu reaction.mid, action setat la react sau unreact, și reaction și emoji.
  • message_edit: o persoană editează un mesaj, cu message_edit.mid, textul nou și num_edit.
  • messaging_postbacks: o persoană apasă pe un icebreaker sau pe un buton de șablon, cu postback.mid, title și payload.
  • messaging_referral: o persoană deja într-o conversație deschide un link ig.me cu un parametru ref.
  • messaging_seen: o persoană citește un mesaj, cu read.mid.
  • messaging_optins, messaging_handover și standby: ultimele două pentru aplicațiile care împart o conversație conform protocolului de predare al Meta.

Ce trebuie să activeze contul?

Permiterea accesului la mesaje este obligatorie: „Permite accesul la mesaje”. Meta cere ca un cont profesional să o activeze înainte ca mesajele sale să poată fi gestionate prin API, în aplicația Instagram, la Setări, apoi „Mesaje și răspunsuri la Story”, „Controale pentru mesaje”, „Instrumente conectate”. Cât timp este dezactivată, trimiterile eșuează cu codul 200, subcodul 2534041. Aplicația are nevoie și de instagram_business_basic și instagram_business_manage_messages, cu Advanced Access pentru a servi conturi pe care nu le deține sau nu le administrează.

Cum transmite easyCoexistence un DM?

Ca un comentariu: fiecare intrare pe care Meta o livrează pentru cont este trimisă prin POST la endpoint-ul HTTPS al dumneavoastră, într-un plic cu platform, account_id, external_id și entry, semnat în X-EC-Signature cu secretul contului, o singură dată și fără copie păstrată. Echo-urile sunt transmise împreună cu restul, deci verificați is_echo înainte de a răspunde. Pentru a răspunde, apelați send_social_dm cu account_id și sender.id din eveniment ca recipient_id, în fereastra de 24 de ore. Automatizările care pornesc de la un DM rulează pe aceleași evenimente.

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>" } }
          ]
        }
      }
    ]
  }
}

Greșeli frecvente

  • Răspunsul la echo-uri. Un eveniment cu is_echo setat este mesajul contului însuși, iar un răspuns la el trimite contul într-o buclă cu el însuși.
  • Presupunerea că un mesaj are întotdeauna text. Atașamentele, distribuirile, mențiunile în Story și ștergerile sosesc fără câmp de text, deci ramificați pe ce conține obiectul message.
  • Ordonarea mesajelor după sosire. Meta poate livra mesajele în dezordine după o eroare, așa că sortați-le după timestamp.
  • Interpretarea câmpurilor time și timestamp ca secunde. Exemplele de mesagerie ale Meta le dau pe ambele în milisecunde, iar citite ca secunde devin date îndepărtate în viitor.
Faceți acest lucru cu EasyCoexistence

send_social_dm răspunde în fereastra de 24 de ore, iar automatizările pot răspunde singure cu un text fix sau cu AI. De la US$ 9 până la US$ 0.75 pe conexiune pe lună, cu cât adăugați mai multe conexiuni, cu o perioadă de probă gratuită de 3 zile.

Întrebări frecvente

Timestamp-urile webhook-urilor de mesaje Instagram sunt în secunde sau în milisecunde?

În milisecunde, în exemplele de mesagerie ale Meta, atât pentru timestamp, cât și pentru momentul intrării. Citite ca secunde, devin date îndepărtate în viitor.

Cum obțin numele de utilizator al expeditorului dintr-un webhook de DM Instagram?

Apelați GET /<IGSID> cu câmpuri precum name și username. Evenimentul conține doar ID-ul Instagram specific persoanei.

De ce nu sosesc webhook-urile mele de DM Instagram?

Verificați dacă, în contul Instagram, este activată „Permite accesul la mesaje”, dacă este abonat la messages prin /subscribed_apps și dacă aplicația este în modul Live, cu Advanced Access pentru conturile pe care nu le deține.

Transmite easyCoexistence reacțiile la mesajele Instagram?

Nu. Reacțiile vin pe message_reactions, iar easyCoexistence abonează conturile la messages, comments și mentions.

Continuați să citiți

Conectați primul canal în două minute.

Fără recenzii de platformă de așteptat. Conectați WhatsApp, Instagram, TikTok sau alt canal, apoi cereți AI-ului să publice, să răspundă sau să raporteze și urmăriți-l cum lucrează.

  • 3 zile gratuit
  • Anulați oricând
  • Doar API-uri oficiale
  • Monitorizat 24/7

Verificat la