Webhook dei messaggi Instagram: payload dei DM, echo e campi
Il campo messages del webhook Instagram consegna i DM di un account professionale appena arrivano: testo, allegati, condivisioni, risposte alle storie e menzioni, risposte inline ed eliminazioni. Ogni evento sta in un array messaging con l'ID con ambito Instagram del mittente, il destinatario, un timestamp e un oggetto message, e i messaggi inviati dall'account tornano sullo stesso campo con is_echo impostato su true.
easyCoexistence iscrive ogni account Instagram collegato a messages e inoltra i suoi DM, echo inclusi, al tuo endpoint HTTPS man mano che arrivano, firmati con il segreto di quell'account; l'inoltro non conserva copie e i DM non sono memorizzati per impostazione predefinita.
Impostato su true in un evento messages per un messaggio inviato dall'account stesso.
Finestra di messaggistica standard per la maggior parte delle azioni dell'utente, durante la quale l'app può rispondere alla persona.
Tipo di allegato per un post condiviso; il vecchio tipo share è stato supportato solo fino al 1° febbraio 2026.
Tipo di allegato dell'evento DM che Meta invia quando qualcuno menziona l'account nella sua storia.
Sottocodice di errore, sotto il codice 200, quando il titolare dell'account ha disattivato l'accesso ai messaggi diretti di Instagram.
Quando si attiva il campo messages?
Quando una persona invia un DM all'account professionale, e quando l'account ne invia uno. Gli esempi e i riferimenti di Meta elencano questi casi, ciascuno un evento messaging con un oggetto message:
- Testo, e contenuti multimediali come allegati: immagini, video, audio e file.
- Un post o un Reel condiviso, come allegato
ig_post,ig_reelo reel. - Una risposta alla storia dell'account, con
reply_to.story, e una storia che menziona l'account, come allegatostory_mention. - Una risposta inline a un messaggio precedente, con
reply_to.mid, e una risposta rapida, conquick_reply.payload. - Un messaggio eliminato dalla persona (
is_deleted), contenuti non supportati (is_unsupported) e un messaggio di chi ha cliccato su un ad Click-to-Direct (referral). - Un messaggio inviato dall'account, che torna con
is_echoimpostato su true.
Che aspetto ha una notifica di messaggio?
Una POST il cui JSON ha object impostato su instagram. A differenza di un commento, un messaggio sta in un array messaging dentro l'elemento entry dell'account, e ogni elemento contiene sender, recipient, timestamp e message. Una risposta alla storia dell'account ha questa forma:
{
"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>"
}
}
}
}
]
}
]
}Cosa significa ogni campo?
I campi che Meta documenta per un evento message con Instagram Login, dall'esterno verso l'interno:
- entry[].id: l'ID dell'account professionale. entry[].time: quando Meta ha inviato la notifica; nei campioni di messaggistica di Meta è in millisecondi.
- sender.id e recipient.id: in un DM in arrivo, l'ID con ambito Instagram della persona e l'ID dell'account; in un echo, gli stessi due invertiti.
- timestamp: quando il messaggio è stato inviato, in millisecondi nei campioni di Meta. Ordina i messaggi in base a questo campo, non all'ordine di arrivo.
- message.mid: l'ID del messaggio, per la deduplicazione, per reagire e per rispondere a quel messaggio con
reply_to.mid. - message.text: incluso quando il messaggio contiene testo.
- message.attachments[]: ciascuno con un type e un payload, di solito un url. Il payload di un
ig_postcondiviso aggiungeig_post_media_ide title, cioè la sua didascalia. - message.
reply_to: mid per una risposta inline, oppure story con l'url e l'id della storia per una risposta a una storia. - message.
quick_reply.payload e message.referral: la risposta rapida scelta, e il ref,ad_id, source, type eads_context_datadell'ad Click-to-Direct. - message.
is_deleted,is_echo,is_selfeis_unsupported: inclusi solo quando sono true. - message.
admin_textehandoff_reason: sulle app idonee, un avviso che un'applicazione Meta, come Meta Business Agent, ha trasferito la conversazione; può arrivare senza mid né testo.
Come funzionano gli echo?
Quando l'account invia un messaggio, Meta invia anche un evento messages per esso, con is_echo impostato su true. In questo caso sender.id è l'account e recipient.id è l'ID con ambito Instagram della persona, e un messaggio di prova che l'account invia a sé stesso porta anche is_self. Gli echo registrano ciò che ha detto l'account, di cui un registro delle conversazioni ha bisogno, ma un gestore che decide se rispondere deve ignorarli. Meta non invia alcun echo quando l'account reagisce a un messaggio o rimuove una reazione.
{
"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
}
}
]
}
]
}A quale ID si risponde?
A sender.id, l'ID con ambito Instagram della persona. Meta lo crea quando qualcuno scrive all'account o commenta i suoi contenuti, ed è specifico per quella persona e quell'account. POST /<IG_ID>/messages con recipient.id impostato su di esso invia la risposta. L'evento non contiene nome né username; GET /<IGSID> con campi come name e username li restituisce, perché una persona che ha scritto all'account ha dato il consenso che questa ricerca richiede.
Come un messaggio apre la finestra di 24 ore?
Un'app può scrivere a una persona solo dopo che questa le ha scritto, e solo entro la finestra di messaggistica standard aperta dalla sua azione. Per la maggior parte delle azioni dura 24 ore, e fino a 7 giorni dopo un primo messaggio inviato dopo aver cliccato su un ad Click-to-Direct. Un nuovo messaggio della persona apre una nuova finestra, quindi il timestamp più recente è quello da tracciare; un echo è un messaggio dell'account stesso e non estende nulla. Le risposte scritte da una persona possono usare la finestra Human Agent di 7 giorni di Meta, con tag human_agent.
Cosa non contiene un evento messages?
Alcune cose che un gestore potrebbe cercare mancano, secondo i riferimenti di messaggistica di Meta:
- Nome o username della persona: solo l'ID con ambito Instagram, che GET /<IGSID> risolve.
- Contenuti multimediali a visualizzazione unica: arrivano come allegato effimero senza URL.
- L'immagine esatta del carosello: una reazione o un inoltro di una sola immagine in un post carosello riporta la prima immagine.
- Reazioni, modifiche e conferme di lettura, che arrivano su campi propri.
- Un segno di lettura: un messaggio consegnato tramite webhook resta non letto nella casella Instagram finché non viene inviata una risposta.
Quali altri campi di messaggistica elenca Meta?
La lista di campi ed esempi di Meta per Instagram Login indica, oltre a messages, questi altri, ciascuno un evento di messaggistica a sé. easyCoexistence iscrive ogni account solo a messages, comments e mentions, quindi nessuno di essi fa parte di ciò che inoltra:
message_reactions: una persona reagisce a un messaggio o rimuove la reazione, con reaction.mid, action impostato su react o unreact, e la reaction ed emoji.message_edit: una persona modifica un messaggio, conmessage_edit.mid, il nuovo testo enum_edit.messaging_postbacks: una persona tocca un icebreaker o un pulsante di template, con postback.mid, title e payload.messaging_referral: una persona già in una conversazione apre un link ig.me con un parametro ref.messaging_seen: una persona legge un messaggio, con read.mid.messaging_optins,messaging_handovere standby: gli ultimi due per le app che condividono una conversazione secondo il protocollo di handover di Meta.
Cosa deve attivare l'account?
Consenti l'accesso ai messaggi. Meta richiede che un account professionale lo attivi prima che i suoi messaggi possano essere gestiti tramite l'API, nell'app Instagram alla voce Impostazioni, Messaggi e risposte alle storie, Controlli messaggi, Strumenti collegati. Finché è disattivato, gli invii falliscono con codice 200, sottocodice 2534041. Anche l'app richiede instagram_business_basic e instagram_business_manage_messages, con Advanced Access per servire account che non possiede né gestisce.
Come easyCoexistence inoltra un DM?
Come per un commento: ogni voce che Meta consegna per l'account viene inviata in POST al tuo endpoint HTTPS dentro una busta con platform, account_id, external_id ed entry, firmata in X-EC-Signature con il segreto dell'account, una sola volta e senza copia conservata. Gli echo vengono inoltrati insieme al resto, quindi controlla is_echo prima di rispondere. Per rispondere, chiama send_social_dm con account_id e il sender.id dell'evento come recipient_id, entro la finestra di 24 ore. Le automazioni che partono da un DM girano sugli stessi eventi.
{
"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>" } }
]
}
}
]
}
}Errori comuni
- Rispondere agli echo. Un evento con is_echo impostato è un messaggio dell'account stesso, e rispondere a esso fa entrare l'account in un ciclo con sé stesso.
- Dare per scontato che un messaggio abbia sempre testo. Allegati, condivisioni, menzioni nelle storie ed eliminazioni arrivano senza un campo text, quindi valuta ciò che contiene l'oggetto message.
- Ordinare i messaggi per ordine di arrivo. Meta può consegnare i messaggi fuori ordine dopo un guasto, quindi ordinali per timestamp.
- Leggere time e timestamp come secondi. Nei campioni di messaggistica di Meta entrambi sono in millisecondi, e letti come secondi diventano date lontane nel futuro.
send_social_dm risponde entro la finestra di 24 ore, e le automazioni possono rispondere da sole con un testo fisso o con l'AI. Da US$ 9 a US$ 0,75 per connessione al mese, che scende man mano che aggiungi connessioni, con i primi 3 giorni di prova gratuita.
Domande frequenti
I timestamp dei webhook di messaggi Instagram sono in secondi o in millisecondi?
In millisecondi, nei campioni di messaggistica di Meta, sia per timestamp sia per il tempo dell'elemento entry. Letti come secondi, diventano date lontane nel futuro.
Come ottengo lo username del mittente da un DM webhook di Instagram?
Chiama GET /<IGSID> con campi come name e username. L'evento contiene solo l'ID con ambito Instagram della persona.
Perché i miei webhook dei DM Instagram non arrivano?
Verifica che l'account abbia attivato Consenti accesso ai messaggi, che sia iscritto a messages tramite /subscribed_apps, e che l'app sia Live con Advanced Access per gli account che non possiede.
easyCoexistence inoltra le reazioni ai messaggi Instagram?
No. Le reazioni arrivano su message_reactions, e easyCoexistence iscrive gli account a messages, comments e mentions.
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