Instagram-storyn maininnat ja vastaukset webhookissa
Instagram toimittaa Story-maininnat ja Story-vastaukset DM-viesteinä messages-webhook-kentässä. Maininta saapuu viestinä, jonka attachments-kentässä on story_mention-tyyppinen liite ja payload.url-kentässä Storyn CDN-URL-osoite. Vastaus sisältää henkilön tekstin ja reply_to.story-kentän, jossa ovat Storyn url ja id. Jos Storyssa on linkkitarra, mukana on myös link_sticker_url.
easyCoexistence tilaa jokaisen yhdistetyn Instagram-tilin messages-kenttään, joten Story-maininnat ja Story-vastaukset saapuvat HTTPS-päätepisteeseesi muiden DM-viestien kanssa heti kun ne tulevat.
Liitteen tyyppi messages-tapahtumassa, jonka Meta lähettää, kun joku mainitsee tilin Storyssaan.
Kenttä reply_to.story-kohdassa, jonka Meta lisäsi 12. joulukuuta 2025, sisältää vastatun Storyn linkkitarran URL-osoitteen.
Kuinka kauan Story kestää: kun se vanhenee tai poistetaan, sen maininnan URL lakkaa näkymästä.
Tilit, joille Story-maininnat saapuvat: yksityisen tilin maininta saapuu vain, jos se seuraa ammattitiliä.
Story-vastaukset, joita webhook ei tue Metan Instagram Messaging -oppaan mukaan.
Miten Story-maininta saapuu?
DM-viestinä. Kun joku mainitsee ammattitilin Storyssaan, Instagram lisää tähän Storyyn viittaavan viestin tilin postilaatikkoon, ja Meta lähettää siitä messages-tapahtuman. sender.id on henkilön Instagram-kohtainen tunnus, ja message.attachments sisältää yhden story_mention-tyyppisen kohteen, jonka payload.url on Storyn CDN-URL. Metan esimerkeissä ei ole tekstiä, joten lue liite:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"attachments": [
{
"type": "story_mention",
"payload": { "url": "<CDN_URL>" }
}
]
}
}
]
}
]
}Miten Story-vastaus saapuu?
Myös DM-viestinä. Mukana on henkilön viesti ja reply_to-objekti, joka osoittaa tilin Storyyn. reply_to.story sisältää Storyn CDN-URL-osoitteen ja tunnuksen. Metan webhook-viite listaa siellä myös link_sticker_url-kentän, jonka Meta lisäsi joulukuussa 2025 vastauksiin Storyihin, joissa on linkkitarra. Meta ehdottaa kenttää automaatioiden reitittämiseen linkin mukaan. Vastaus aiempaan viestiin käyttää sen sijaan reply_to.mid-kenttää.
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL>",
"id": "<STORY_ID>"
}
}
}Mitä kukin kenttä tarkoittaa?
Metan näissä kahdessa tapahtumassa dokumentoimat kentät ulkoa sisäänpäin:
- entry[].id ja recipient.id: ammattitili. sender.id: henkilön Instagram-kohtainen tunnus, johon vastaus menee.
- timestamp: milloin viesti lähetettiin, Metan esimerkeissä millisekunteina. entry[].time on hetki, jolloin Meta lähetti ilmoituksen.
- message.mid: viestin tunnus, jonka avulla toistetut lähetykset tunnistetaan ja johon vastataan
reply_to.mid-kentällä. - attachments[].type
story_mentionja payload.url: maininta sekä sen Storyn CDN-URL, joka maininnan teki. reply_to.story.url jareply_to.story.id: tilin Story, johon henkilö vastasi.reply_to.story.link_sticker_url: Storyn linkkitarran URL-osoite.- message.text: vastauksen sanat, mukana kun viestissä on teksti.
Kuinka kauan Storyn URL toimii?
Yhtä kauan kuin Story itse. Story katoaa 24 tunnin kuluttua tai kun sen tekijä poistaa sen, ja Metan Story-mainintaoppaan mukaan URL lakkaa tämän jälkeen näkymästä. Yleiskatsauksessa lisätään, että Instagramin CDN-URL-osoitteet ovat yksityisyyttä huomioivia ja palauttavat tyhjän vastauksen poistetulle tai vanhentuneelle sisällölle. Sama opas sallii CDN-URL-osoitteen säilyttämisen, mutta ei mediaa: sovellus ei saa tallentaa tai välimuistittaa Storyn sisältöä palvelimilleen, ja sen pitäisi näyttää paikkamerkki, kun Story on poistunut.
Milloin kumpikaan tapahtuma ei laukea?
Metan oppaat nimeävät nämä tapaukset, joissa Story-tapahtumaa odottava käsittelijä ei saa mitään:
- Yksityisen tilin Story-maininta, joka ei seuraa ammattitiliä.
- Merkintä tavallisessa julkaisussa: Metan mukaan vain Story-maininnat laukaisevat messages-webhookin, ei julkaisuihin tehdyt merkinnät.
- Story-vastaus, joka on tehty GIF:llä tai tarralla. webhook ei tue sitä.
- Storyt mentions-rajapinnan kautta: GET /<
IG_ID>/tags ja POST /<IG_ID>/mentions eivät tue Storyjä, joten Story-maininta saapuu DM-viestinä.
Avaavatko Story-maininnat ja -vastaukset 24 tunnin viestiikkunan?
Vastaus on henkilön viesti, ja Meta listaa Story-maininnat niiden kanavien joukkoon, joiden kautta henkilö aloittaa keskustelun. Henkilön toiminnan avaama ikkuna on useimmille toimille 24 tuntia, joten tili voi vastata POST /<IG_ID>/messages -pyynnöllä, jossa recipient.id on tapahtuman sender.id, kun ikkuna on auki. Tilin vastaus palaa messages-kentässä echo-viestinä, jossa is_echo on true.
Miten easyCoexistence välittää ne?
messages-kentän kautta, johon jokainen yhdistetty tili on tilattu. Story-maininnat ja Story-vastaukset saapuvat päätepisteeseesi muiden DM-viestien mukana: jokainen entry on kääreessä, jossa ovat platform, account_id, external_id ja entry. Kääre on allekirjoitettu X-EC-Signature-otsakkeessa tilin salaisuudella, ja se lähetetään kerran eikä kopiota säilytetä. send_social_dm vastaa henkilölle tapahtuman sender.id-tunnuksella recipient_id-kentässä 24 tunnin ikkunan sisällä.
POST <YOUR_ENDPOINT>
Content-Type: application/json
X-EC-Signature: t=1793448001,v1=<HEX_HMAC_SHA256>
{
"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": "story_mention", "payload": { "url": "<CDN_URL>" } }
]
}
}
]
}
}Yleiset virheet
- Storyn median tallentaminen. Metan Story-mainintaopas sallii CDN-URL-osoitteen säilyttämisen, mutta ei sisällön, jota ei saa tallentaa tai välimuistittaa palvelimillesi.
- Pelkän message.text-kentän lukeminen. Story-maininta sisältää story_mention-tyyppisen liitteen, eikä Metan esimerkeissä ole tekstiä, joten pelkkään tekstiin perustuva käsittelijä näkee tyhjän viestin.
- Storyn URL:n näyttäminen päiviä myöhemmin. Se lakkaa toimimasta, kun Story vanhenee 24 tunnin kuluttua tai poistetaan, joten näytä siitä lähtien paikkamerkki.
- Story-maininnan etsiminen comments-kentästä tai mentions-rajapinnasta. Meta toimittaa ne DM-viesteinä messages-kentässä.
Kääre on allekirjoitettu tilin salaisuudella eikä kopiota säilytetä. send_social_dm vastaa henkilölle 24 tunnin ikkunan sisällä, Claudelta, ChatGPT:ltä tai omasta koodistasi. US$ 9:stä US$ 0.75:een per yhteys kuukaudessa, ja hinta laskee yhteyksiä lisätessä. Ensimmäiset 3 päivää ovat ilmaisessa kokeilussa.
Usein kysytyt kysymykset
Sisältääkö Instagram Story -maininnan tapahtuma tekstiä?
Ei Metan esimerkeissä. Story-maininnassa on story_mention-tyyppinen liite ja Storyn CDN-URL, joten käsittelijä, joka lukee vain message.text-kenttää, näkee tyhjän viestin.
Mitä on link_sticker_url Instagram Story -vastauksessa?
Se on vastatun Storyn linkkitarran URL-osoite, reply_to.story.link_sticker_url-kentässä. Meta lisäsi sen 12. joulukuuta 2025 ja ehdottaa sitä automaatioiden reitittämiseen linkin perusteella.
Laukaisevatko GIF- tai tarra-vastaukset Storyyn webhookin?
Ei. Metan Instagram Messaging -oppaan mukaan webhook ei tue Story-vastauksia, jotka on tehty GIF:llä tai tarralla.
Laukaisevatko yksityiset tilit Story-maininta-webhookit?
Vain jos yksityinen tili seuraa ammattitiliä. Julkisten tilien maininnat saapuvat heti, kun ne tapahtuvat.
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