Kirjaudu sisäänAloita ilmainen kokeilu
easyCoexistence Viralliset API:t

Instagram-viestien webhook: DM-payload, echot ja kentät

Instagramin messages-webhook-kenttä toimittaa ammatillisen tilin DM-viestit heti niiden saapuessa: tekstin, liitteet, jaot, Story-vastaukset ja maininnat, sisäiset vastaukset sekä poistot. Jokainen tapahtuma sijaitsee messaging-taulukossa, jossa ovat lähettäjän Instagram-kohtainen ID, vastaanottaja, aikaleima ja message-objekti. Tilin itse lähettämät viestit palautuvat samaan kenttään, ja niissä is_echo on true.

easyCoexistence tilaa jokaisen yhdistetyn Instagram-tilin messages-kenttään ja välittää sen DM-viestit, echot mukaan lukien, HTTPS-päätepisteeseesi heti niiden saapuessa.

is_echo

Saa arvon true viestitapahtumassa, kun tili on lähettänyt viestin itse.

24 hours

Tavallinen viestiikkuna useimmille käyttäjän toimille, jonka aikana sovellus voi vastata henkilölle.

ig_post

Liitetyyppi jaetulle julkaisulle; vanha jakotyyppi tuettiin vain 1. helmikuuta 2026 asti.

story_mention

Liitetyyppi DM-tapahtumalle, jonka Meta lähettää, kun joku mainitsee tilin Storyssaan.

2534041

Virhealikoodi koodin 200 alla, kun tilin omistaja on poistanut käytöstä pääsyn DM-viesteihin.

Milloin messages-kenttä laukeaa?

Kun henkilö lähettää ammatilliselle tilille DM-viestin ja kun tili itse lähettää sellaisen. Metan esimerkit ja viitteet listaavat nämä tapaukset, joista jokainen on messaging-tapahtuma message-objektilla:

  • Teksti ja media liitteinä: kuvat, video, ääni ja tiedostot.
  • Jaettu julkaisu tai Reel liitteenä ig_post-, ig_reel- tai reel-tyyppinä.
  • Vastaus tilin Storyyn reply_to.story-kentällä sekä Story, joka mainitsee tilin, story_mention-liitteenä.
  • Sisäinen vastaus aiempaan viestiin reply_to.mid-kentällä ja pikavastaus quick_reply.payload-kentällä.
  • Henkilön poistama viesti (is_deleted), tukematon media (is_unsupported) ja viesti henkilöltä, joka klikkasi Click-to-Direct-mainosta (referral).
  • Tilin lähettämä viesti, joka palautuu is_echo-arvolla true.

Miltä messages-ilmoitus näyttää?

POST-pyyntö, jonka JSON-sisällössä object on instagram. Toisin kuin kommentti, viesti sijaitsee tilin entry-osan sisällä messaging-taulukossa, ja jokainen alkio sisältää sender-, recipient-, timestamp- ja message-kentät. Vastaus tilin Storyyn näyttää tältä:

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

Mitä kukin kenttä tarkoittaa?

Kentät, jotka Meta dokumentoi messaging-tapahtumalle Instagram Loginin alla, ulkoa sisäänpäin:

  • entry[].id: ammatillisen tilin ID. entry[].time: milloin Meta lähetti ilmoituksen; Metan viestiesimerkeissä se on millisekunteina.
  • sender.id ja recipient.id: saapuvassa DM:ssä henkilön Instagram-kohtainen ID ja tilin ID; echossa sama kaksi toisinpäin.
  • timestamp: milloin viesti lähetettiin; Metan esimerkeissä millisekunteina. Järjestä viestit sen mukaan, älä saapumisjärjestyksen.
  • message.mid: viestin ID, jota käytetään deduplikointiin, reagointiin ja vastaamiseen reply_to.mid-kentällä.
  • message.text: mukana, kun viesti sisältää tekstiä.
  • message.attachments[]: jokaisella type ja payload, yleensä url. Jaetun julkaisun ig_post-payloadissa on lisäksi ig_post_media_id ja title, eli sen kuvateksti.
  • message.reply_to: mid sisäisessä vastauksessa tai story, jossa on Storyn url ja id Story-vastauksessa.
  • message.quick_reply.payload ja message.referral: valittu pikavastaus sekä Click-to-Direct-mainoksen ref, ad_id, source, type ja ads_context_data.
  • message.is_deleted, is_echo, is_self ja is_unsupported: mukana vain, kun arvo on true.
  • message.admin_text ja handoff_reason: hyväksytyissä sovelluksissa ilmoitus siitä, että Metan sovellus, kuten Meta Business Agent, on siirtänyt keskustelun; se voi tulla ilman mid- tai text-kenttää.

Miten echot toimivat?

Kun tili lähettää viestin, Meta lähettää siitä myös messages-tapahtuman, jossa is_echo on true. sender.id on silloin tili ja recipient.id henkilön Instagram-kohtainen ID, ja tilin itselleen lähettämässä testiviestissä on myös is_self. Echot kirjaavat sen, mitä tili sanoi, mitä keskusteluloki tarvitsee, mutta käsittelijän, joka päättää vastaamisesta, on ohitettava ne. Meta ei lähetä echoa, kun tili reagoi viestiin tai poistaa reaktion.

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

Mihin ID:hen vastaat?

sender.id, henkilön Instagram-kohtainen ID. Meta luo sen, kun joku lähettää tilille viestin tai kommentoi sen mediaa, ja se on yksilöllinen kyseiselle henkilölle ja tilille. POST /<IG_ID>/messages, jonka recipient.id on tämä ID, lähettää vastauksen. Tapahtumassa ei ole nimeä eikä käyttäjänimeä; GET /<IGSID> kentillä name ja username palauttaa ne, koska henkilö, joka on lähettänyt viestin tilille, on antanut suostumuksen, jota haku vaatii.

Miten viesti avaa 24 tunnin ikkunan?

Sovellus voi viestiä henkilölle vain, kun tämä on viestinyt tilille, ja vain sen toiminnon avaamassa tavallisessa viestiikkunassa. Useimmille toiminnoille ikkuna kestää 24 tuntia, ja enintään 7 päivää, kun ensimmäinen viesti lähetetään Click-to-Direct-mainoksen klikkauksen jälkeen. Henkilön uusi viesti avaa uuden ikkunan, joten seurattava on hänen viimeisin aikaleimansa; echo on tilin oma viesti eikä pidennä mitään. Henkilön kirjoittamiin vastauksiin voi käyttää Metan erillistä 7 päivän Human Agent -ikkunaa, merkittynä human_agent-tagilla.

Mitä messages-tapahtuma ei sisällä?

Metan viestiviitteiden mukaan muutama asia, jota käsittelijä voisi etsiä, puuttuu:

  • Henkilön nimi tai käyttäjänimi: vain Instagram-kohtainen ID, jonka GET /<IGSID> selvittää.
  • Kerran katseltava media: se saapuu tilapäisenä liitteenä ilman URL-osoitetta.
  • Tarkka karusellikuva: reaktio tai edelleenlähetys yhteen kuvaan karusellijulkaisussa raportoi ensimmäisen kuvan.
  • Reaktiot, muokkaukset ja lukukuittaukset, jotka tulevat omilla kentillään.
  • Lukumerkintä: webhookin toimittama viesti pysyy lukemattomana Instagram-postilaatikossa, kunnes vastaus lähetetään.

Mitkä muut viestikentät Meta listaa?

Metan kenttälista ja esimerkit Instagram Loginille nimeävät nämä messagesin lisäksi, kukin omana messaging-tapahtumanaan. easyCoexistence tilaa jokaisen tilin vain messages-, comments- ja mentions-kenttiin, joten mikään niistä ei kuulu siihen, mitä se välittää:

  • message_reactions: henkilö reagoi viestiin tai poistaa reaktion, reaction.mid-kentällä, action-kentän arvolla react tai unreact sekä reaction- ja emoji-kentillä.
  • message_edit: henkilö muokkaa viestiä, message_edit.mid-, uusi teksti ja num_edit -kentillä.
  • messaging_postbacks: henkilö napauttaa icebreaker- tai mallipainiketta, postback.mid-, title- ja payload-kentillä.
  • messaging_referral: keskustelussa jo oleva henkilö avaa ig.me-linkin ref-parametrilla.
  • messaging_seen: henkilö lukee viestin, read.mid-kentällä.
  • messaging_optins, messaging_handover ja standby: kaksi viimeistä sovelluksille, jotka jakavat keskustelun Metan handover-protokollan mukaisesti.

Mitä tilin on sallittava?

Salli pääsy viesteihin. Meta edellyttää, että ammatillinen tili kytkee sen päälle ennen kuin sen viestejä voi hallita rajapinnan kautta: Instagram-sovelluksessa kohdassa Asetukset, Viestit ja Story-vastaukset, Viestien hallinta, Yhdistetyt työkalut. Kun se on pois päältä, lähetykset epäonnistuvat koodilla 200, alikoodilla 2534041. Sovellus tarvitsee myös instagram_business_basic- ja instagram_business_manage_messages-oikeudet sekä Advanced Accessin, jotta se voi palvella tilejä, joita se ei omista tai hallinnoi.

Miten easyCoexistence välittää DM:n?

Kuten kommentti: jokainen Metan tilille toimittama entry lähetetään POST-pyyntönä HTTPS-päätepisteeseesi kääreessä, jossa ovat platform, account_id, external_id ja entry. Se allekirjoitetaan X-EC-Signature-otsikossa tilin salaisuudella, kerran, eikä kopiota säilytetä. Echot välitetään muiden mukana, joten tarkista is_echo ennen vastaamista. Vastataksesi kutsu send_social_dm-työkalua account_id:llä ja tapahtuman sender.id:llä recipient_id:ksi 24 tunnin ikkunan sisällä. DM:ään käynnistyvät automaatiot toimivat samoilla tapahtumilla.

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

Yleiset virheet

  • Echoihin vastaaminen. Tapahtuma, jossa is_echo on asetettu, on tilin oma viesti, ja vastaus siihen lähettää tilin silmukkaan itsensä kanssa.
  • Olettaminen, että viestissä on aina teksti. Liitteet, jaot, Story-maininnat ja poistot saapuvat ilman text-kenttää, joten haarauta sen mukaan, mitä message-objekti sisältää.
  • Viestien järjestäminen saapumisjärjestyksen mukaan. Meta voi toimittaa viestejä epäjärjestyksessä virheen jälkeen, joten lajittele ne aikaleiman mukaan.
  • Aikojen käsitteleminen sekunteina timestamp- ja time-kentissä. Metan viestiesimerkit antavat molemmat millisekunteina, ja sekunteina luettuna ne muuttuvat päivämääriksi kaukana tulevaisuudessa.
Näin teet tämän EasyCoexistencen avulla

Tili allekirjoittaa ne omalla salaisuudellaan; välittäminen ei säilytä kopiota, eikä DM-viestejä tallenneta oletuksena. send_social_dm vastaa 24 tunnin ikkunan sisällä, ja automaatiot voivat vastata itsenäisesti kiinteällä tekstillä tai tekoälyllä. Hinta laskee US$ 9:stä US$ 0,75:een per yhteys kuukaudessa yhteyksien määrän kasvaessa, ja ensimmäiset 3 päivää ovat ilmaisia.

Usein kysytyt kysymykset

Ovatko Instagram-viestien webhook-aikaleimat sekunteja vai millisekunteja?

Millisekunteja, Metan viestiesimerkeissä sekä timestamp- että entry-ajalle. Sekunteina luettuna ne muuttuvat päivämääriksi kaukana tulevaisuudessa.

Miten saan lähettäjän käyttäjänimen Instagram-DM-webhookista?

Kutsu GET /<IGSID> kentillä name ja username. Tapahtuma sisältää vain henkilön Instagram-kohtaisen ID:n.

Miksi Instagram-DM-webhookit eivät saavu?

Tarkista, että tili on kytkenyt päälle Salli pääsy viesteihin, että se on tilattu messages-kenttään /subscribed_apps-rajapinnan kautta, ja että sovellus on Live-tilassa Advanced Accessilla tileille, joita se ei omista.

Välittääkö easyCoexistence Instagram-viestireaktiot?

Ei. Reaktiot tulevat message_reactions-kentässä, ja easyCoexistence tilaa tilit messages-, comments- ja mentions-kenttiin.

Lue lisää

Yhdistä ensimmäinen kanavasi kahdessa minuutissa.

Ei alustojen tarkastuksia odotettavana. Yhdistä WhatsApp, Instagram, TikTok tai jokin muu kanava, pyydä sitten tekoälyäsi julkaisemaan, vastaamaan tai raportoimaan ja seuraa, kun se hoitaa homman.

  • 3 päivää ilmaiseksi
  • Peruuta milloin tahansa
  • Vain viralliset API:t
  • Valvottu 24/7

Vahvistettu