Allegati DM di Instagram nel webhook dei messaggi
Il webhook dei messaggi di Instagram trasporta i media dei DM in message.attachments: un array di oggetti, ciascuno con un type e un payload che di solito contiene un URL CDN. L'elenco di Meta per Instagram Login indica image, video, audio, file, ig_post, ig_reel, reel, story_mention, media, story, ig_story e il vecchio share, e i media a visualizzazione singola arrivano come allegato di tipo ephemeral senza URL.
easyCoexistence iscrive ogni account Instagram collegato a messages e inoltra i DM con i relativi allegati al tuo endpoint HTTPS così come Meta li invia, firmati con il segreto di quell'account e senza copia conservata, così il tuo agente o codice recupera i media che gli servono.
Tipo di allegato per un post condiviso; il suo payload aggiunge ig_post_media_id e title, la didascalia del post, accanto a url.
Quando il vecchio tipo di allegato share ha smesso di essere supportato per le condivisioni di post di Instagram.
Tipo di allegato per i media effimeri a visualizzazione singola, che arrivano senza URL.
Impostato su true in un evento di messaggio quando il messaggio contiene media non supportati.
Ciò che una notifica riporta quando qualcuno reagisce o inoltra una sola immagine di un post carosello.
Quali tipi di allegato può contenere un evento DM?
Gli esempi di Meta per Instagram Login elencano questi valori per message.attachments[].type, ciascuno con un oggetto payload. La maggior parte dei payload contiene un url verso il media nella CDN di Meta, e Meta documenta campi aggiuntivi del payload solo per ig_post, quindi leggi prima il tipo e poi il payload.
Che aspetto ha un DM con allegati?
Un evento di messaggio il cui oggetto message contiene attachments al posto del testo, o insieme ad esso. L'esempio di Meta invia due media in un solo messaggio, ciascuno con il proprio type e il proprio payload.url, quindi un gestore deve scorrere l'array invece di leggere solo il primo elemento:
{
"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>" } }
]
}
}
]
}
]
}Che aspetto ha un post condiviso?
Un allegato ig_post. Dal 3 novembre 2025 Meta ha inviato le condivisioni di post con sia un allegato share sia uno ig_post; share è rimasto supportato per i post fino al 1° febbraio 2026, e Meta afferma che le nuove integrazioni devono supportare ig_post. Il suo payload aggiunge l'ID del media del post e la didascalia come title:
"attachments": [
{
"type": "ig_post",
"payload": {
"ig_post_media_id": "<MEDIA_ID>",
"title": "<POST_CAPTION>",
"url": "<CDN_URL>"
}
}
]Che cosa significa ogni campo?
I campi degli allegati che Meta documenta per un evento DM, dall'array in giù:
- message.attachments[]: un oggetto per ogni elemento multimediale; l'esempio di Meta ne contiene due in un solo messaggio.
- type: di che elemento si tratta, dall'elenco sopra. Dirigi il codice in base a questo campo prima di leggere il payload.
- payload.url: un URL CDN per il media. La panoramica di Meta definisce questi URL attenti alla privacy: non restituiscono nulla una volta che il contenuto è stato eliminato o è scaduto.
- payload.
ig_post_media_ide payload.title: solo suig_post, l'ID del media del post condiviso e la sua didascalia. - message.text: presente solo quando il messaggio contiene anche testo.
- message.
is_unsupported: true quando il messaggio contiene media che il webhook non supporta.
Quanto durano gli URL degli allegati?
Meta li lega al contenuto. La panoramica afferma che gli URL della CDN di Instagram sono attenti alla privacy e smettono di restituire il media una volta che il contenuto è stato eliminato o è scaduto, e la guida alle menzioni nelle storie dice che l'URL di una storia smette di funzionare quando la storia scade o viene eliminata. Un'app che ha bisogno di un file dovrebbe scaricarlo all'arrivo dell'evento, nel rispetto delle regole di Meta: i media delle storie, per esempio, non devono essere memorizzati né messi in cache.
Quali media il webhook non include?
La guida ai messaggi di Instagram di Meta indica queste lacune, che un gestore deve prevedere invece di trattarle come errori:
- Media effimeri, a visualizzazione singola o con riproduzione consentita una volta: un allegato di tipo ephemeral, senza URL.
- Media non supportati: il messaggio arriva con
is_unsupportedimpostato su true. - GIF e sticker: quella guida dice che non attivano alcun webhook, mentre gli esempi di Meta per Instagram Login li elencano sotto image.
- La reazione o l'inoltro di una immagine di un carosello riporta la prima immagine.
- Condivisioni in generale: le guide di Meta sui messaggi dicono ancora che è incluso solo l'URL dei media condivisi, anche se
ig_postora aggiunge l'ID del media e la didascalia.
Come inoltra gli allegati easyCoexistence?
Invariato, dentro entry: un DM con media arriva al tuo endpoint con l'array attachments di Meta così come Meta lo ha inviato, in una busta con platform, account_id, external_id ed entry, firmata con X-EC-Signature. Gli allegati non vengono scaricati, e gli eventi non vengono memorizzati di default: un account con un'automazione attiva conserva per 7 giorni il testo di un DM, non i suoi media. Recupera dal payload.url i media che ti servono quando l'evento arriva e non memorizzare i media delle storie.
Errori comuni
- Leggere solo il primo allegato. message.attachments è un array e l'esempio di Meta contiene due elementi in un solo messaggio, quindi scorri tutto l'array.
- Continuare a cercare il tipo share per i post condivisi. Meta lo ha supportato per i post fino al 1° febbraio 2026; leggi ig_post, con ID del media e didascalia nel payload.
- Salvare payload.url per recuperarlo dopo. Smette di restituire il media una volta che il contenuto è eliminato o scaduto, quindi scarica ciò che ti serve all'arrivo, ad eccezione dei media delle storie, che non devono essere memorizzati.
- Leggere payload.url senza controllare il tipo. I media a visualizzazione singola arrivano come ephemeral senza URL, e i media non supportati impostano is_unsupported.
send_social_dm risponde entro la finestra di 24 ore. Da US$ 9 a US$ 0,75 per connessione al mese, in calo man mano che aggiungi connessioni, con i primi 3 giorni di prova gratuita.
Domande frequenti
Posso memorizzare i media di un allegato DM di Instagram?
Scarica ciò che ti serve quando l'evento arriva, perché payload.url smette di restituire il media una volta che il contenuto è eliminato o scaduto. Le storie fanno eccezione: le regole di Meta dicono che non devono essere memorizzate né messe in cache.
Perché un webhook dei DM di Instagram non ha un URL del media?
Di solito perché il media è a visualizzazione singola, che arriva come allegato ephemeral senza URL, oppure non supportato, che imposta is_unsupported su true.
GIF e sticker di Instagram attivano il webhook dei messaggi?
La documentazione di Meta non concorda: gli esempi per Instagram Login elencano GIF e sticker sotto image, mentre la guida ai messaggi di Instagram dice che non attivano alcun webhook. Prova con un account reale.
Un solo evento DM di Instagram può contenere più allegati?
Sì. message.attachments è un array e l'esempio di Meta mostra due elementi multimediali in un solo messaggio.
Continua a leggere
Collega il tuo primo canale in due minuti.
Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.
- 3 giorni gratis
- Disdici quando vuoi
- Solo API ufficiali
- Monitorato 24/7
Verificato il