Modulo didattico · Sviluppo Web / E-commerce

Creare applicazioni su Instagram Direct

Un percorso operativo pensato per chi si avvicina per la prima volta all'API di messaggistica di Instagram: dai concetti di base alla configurazione, fino a cinque casi d'uso reali con esempi di codice.

👤
Account Professional
Business o Creator
→
⚙️
App Meta + Instagram Login
Autenticazione diretta
→
🔑
Access Token
+ IG_ID
→
💬
graph.instagram.com
Invio/ricezione DM
01

Fondamenti

Instagram ha reso più semplice l'accesso diretto ai Direct Message: dal 2023 non serve più obbligatoriamente una Pagina Facebook collegata, grazie all'Instagram Login.

Requisito

Account Professional

Serve un account Instagram Business o Creator: gli account personali non possono usare l'API di messaggistica.

Autenticazione

Instagram Login vs Facebook Login

Due modalità: Instagram Login (diretta, moderna, senza Pagina Facebook) oppure Facebook Login (classica, tramite Pagina collegata). In questo modulo usiamo la prima, più semplice.

Sicurezza

Instagram User Access Token

Token inviato nell'header Authorization: Bearer: autentica ogni chiamata a graph.instagram.com.

Identificativi

IG_ID e IGSID

IG_ID identifica il tuo account professional; IGSID (Instagram-Scoped ID) identifica l'utente con cui stai parlando, ottenuto solo da un evento webhook reale.

Regola importante

Finestra di 24 ore

Come su Messenger, puoi rispondere liberamente entro 24 ore dall'ultimo messaggio. Il tag HUMAN_AGENT estende la finestra a 7 giorni quando interviene un operatore umano.

Manutenzione

Token Refresh

I token hanno una scadenza: vanno rinnovati periodicamente tramite l'endpoint di refresh, idealmente quando mancano meno di 7 giorni alla scadenza.

02

Setup operativo passo-passo

Segui questi quattro passaggi in ordine. Spunta ogni step man mano che lo completi.

01Trasforma il profilo in account Professional e crea l'app

Dalle impostazioni Instagram, passa a un account Business o Creator. Poi su developers.facebook.com crea un'app e aggiungi il prodotto Instagram con configurazione "Instagram API with Instagram Login".

02Autentica e ottieni token + IG_ID

Completa il flusso OAuth di Instagram Login richiedendo lo scope instagram_manage_messages: otterrai l'Instagram User Access Token e l'IG_ID del tuo account.

03Invia il tuo primo messaggio di prova

Scrivi tu stesso un DM al tuo account professional da un altro profilo, poi recupera il tuo IGSID dal webhook (o dallo strumento di test nella dashboard). Prova quindi:

cURL — invio messaggio di prova
curl -X POST "https://graph.instagram.com/v25.0/{IG_ID}/messages" \
  -H "Authorization: Bearer {INSTAGRAM_USER_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {"id": "{IGSID}"},
    "message": {"text": "Ciao! Questo è il mio primo messaggio via Instagram API."}
  }'
Segna come completato quando ricevi il messaggio nei tuoi DM

04Configura il webhook di ricezione

Nella sezione Webhook dell'app, sottoscrivi il campo messages per il tuo account, con un URL pubblico HTTPS (in fase di apprendimento puoi usare un tunnel come ngrok).

Errore comune: dimenticare di rinnovare il token prima della scadenza. Una buona pratica è controllare la scadenza ogni giorno e rinnovare quando mancano meno di 7 giorni.
03

Le cinque tipologie di applicazione

Clicca su ciascuna scheda per aprire scenario, esempio di codice e avvertenze.

🎧

Assistenza clienti su DM

Risposte automatiche a domande frequenti
▾
Scenario: un follower scrive in DM "Fate spedizioni in Sicilia?" e riceve subito una risposta automatica.
Node.js — risposta automatica dal webhook
app.post('/webhook', async (req, res) => {
  const evento = req.body.entry[0].messaging[0];
  if (evento.message?.text?.toLowerCase().includes('spedizion')) {
    await inviaMessaggio(evento.sender.id, 'Sì, spediamo in tutta Italia comprese le isole!');
  }
  res.sendStatus(200);
});
Cosa non fare: non gestire reclami delicati solo con risposte automatiche: prevedi sempre un passaggio a un operatore umano.
💬

Comment-to-DM

Automazione tipica di Instagram: dal commento al DM
▾
Scenario: un utente commenta un post con "info", e il bot gli invia automaticamente un DM con il listino prezzi.
Node.js — reazione a un commento
if (commento.text.toLowerCase().includes('info')) {
  await inviaMessaggio(commento.autore_igsid,
    'Ciao! Ecco il listino che hai richiesto: link.it/listino');
}
Cosa non fare: non usare questa tecnica per inviare contenuti non richiesti a chi commenta senza intento reale: rischia di essere percepito come spam.
🔔

Notifiche e aggiornamenti

Con Message Tag, fuori dalla finestra 24h
▾
Scenario: un cliente che ha scritto giorni fa riceve un aggiornamento importante grazie all'intervento di un operatore umano.
JSON — invio con tag HUMAN_AGENT
{
  "recipient": {"id": "{IGSID}"},
  "message": {"text": "Le confermiamo che il problema è stato risolto."},
  "tag": "HUMAN_AGENT"
}
Cosa non fare: non usare il tag HUMAN_AGENT se non c'è davvero un operatore umano coinvolto nella risposta: è una policy verificata da Meta.
🤖

Chatbot conversazionale

Quick reply per guidare l'utente
▾
Scenario: un bot propone opzioni tramite pulsanti invece di richiedere testo libero.
JSON — messaggio con quick reply
{
  "recipient": {"id": "{IGSID}"},
  "message": {
    "text": "Cosa ti interessa?",
    "quick_replies": [
      {"content_type":"text", "title":"Catalogo", "payload":"CATALOGO"},
      {"content_type":"text", "title":"Assistenza", "payload":"ASSISTENZA"}
    ]
  }
}
Cosa non fare: non costruire flussi senza via d'uscita verso un operatore umano.
🛍️

E-commerce e reazioni rapide

Schede prodotto e reazioni ai messaggi
▾
Scenario: un negozio invia un'immagine prodotto e reagisce con un cuoricino ai messaggi dei clienti più coinvolti.
cURL — invio immagine prodotto
curl -X POST "https://graph.instagram.com/v25.0/{IG_ID}/messages" \
  -H "Authorization: Bearer {TOKEN}" -H "Content-Type: application/json" \
  -d '{
    "recipient": {"id": "{IGSID}"},
    "message": {"attachment": {"type": "image", "payload": {"url": "{URL_IMMAGINE}"}}}
  }'
Cosa non fare: non dimenticare che le immagini devono essere raggiungibili pubblicamente via URL: link privati non funzionano.
04

Glossario interattivo

Clicca su un termine per rivelarne la definizione.

IG_ID clicca
Identificativo del tuo account Instagram professional, usato in ogni chiamata API.
IGSID clicca
Instagram-Scoped ID: identifica un utente specifico rispetto al tuo account, ottenuto solo da un evento webhook reale.
Instagram User Access Token clicca
Token inviato come Bearer nell'header Authorization, che autentica le chiamate a graph.instagram.com.
Instagram Login clicca
Modalità di autenticazione diretta che non richiede una Pagina Facebook collegata, introdotta nel 2023.
Finestra 24h clicca
Periodo entro cui puoi rispondere liberamente a un utente dopo il suo ultimo messaggio.
HUMAN_AGENT clicca
Tag che estende la finestra di risposta a 7 giorni, valido solo quando un operatore umano interviene realmente.
Comment-to-DM clicca
Automazione che invia un DM in risposta a un commento su un post, tipica delle strategie di marketing Instagram.
Token Refresh clicca
Operazione periodica per rinnovare l'access token prima della sua scadenza, evitando interruzioni del servizio.
05

Esercitazioni pratiche

Verifica quanto hai appreso con questo quiz di autovalutazione.

1. Che tipo di account Instagram serve per usare l'API di messaggistica?
2. Con Instagram Login, serve ancora una Pagina Facebook collegata?
3. Quando è corretto usare il tag HUMAN_AGENT?
4. Cos'è il Comment-to-DM?
06

Attestato di completamento

Completa tutti i passaggi della Sezione 2 per sbloccare il tuo attestato personale in PDF.

🔒
Attestato non ancora disponibile
Completa tutti e 4 i passaggi della Sezione 2 — Setup operativo.