Webhooks per i messaggi di Instagram

Webhooks ti consente di ricevere notifiche HTTP in tempo reale relative a modifiche a oggetti specifici nel social graph di Meta. Ad esempio, potremmo inviarti una notifica quando un cliente invia un messaggio al tuo account per professionisti Instagram. Le notifiche webhook ti consentono di monitorare le modifiche alla messaggistica ed evitare i rate limiting che si verificherebbero se eseguissi query sugli endpoint della Piattaforma Messenger per il monitoraggio delle modifiche.

Requisiti

Dovrai implementare i seguenti requisiti per ricevere notifiche Webhooks per i messaggi di Instagram.

Le autorizzazioni instagram_basic, instagram_manage_messages e pages_manage_metadata
Per ricevere notifiche webhook che includono dati di proprietà di o gestiti da persone che non hanno un ruolo nella tua app, la tua app deve disporre dell'accesso avanzato

Nota: dovrai attivare l'iscrizione ai webhook dei messaggi per tutte le app di messaggistica della tua azienda.

Modalità dell'app

Modalità sviluppo: i webhook vengono inviati solo se la persona che usa la tua app ha un ruolo al suo interno, anche se questa non dispone dell'accesso avanzato. Puoi accedere solo ai dati che possiedi o che gestisci.
Modalità live: i webhook vengono inviati in base al livello di accesso.
- Accesso standard: i webhook vengono inviati solo se la persona che usa la tua app ha un ruolo al suo interno. Puoi accedere solo ai dati che possiedi o che gestisci.
- Accesso avanzato: i webhook saranno inviati a ogni utilizzo della tua app, purché siano state concesse le autorizzazioni necessarie.

Scopri di più sui livelli di accesso , le modalità dell'app e i ruoli nell'app.

Limitazioni

Quando un cliente reagisce a o inoltre un'immagine di un carosello in un post di Instagram, la notifica includerà la prima immagine del carosello che potrebbe non essere l'immagine a cui il cliente ha reagito o che ha inoltrato.
Solo l'URL del contenuto multimediale o del post condiviso viene incluso nella notifica quando un cliente invia un messaggio con una condivisione.
I messaggi contenenti GIF e adesivi non sono supportati. Se una persona invia un messaggio con una GIF o un adesivo, non viene attivato alcun webhook né vengono inviate notifiche webhook.

Eventi del webhook

Campo del webhook	Descrizione
`message_reactions`	Viene inviata una notifica quando un cliente reagisce o annulla l'aggiunta di una reazione a un messaggio L'API Graph v12.0 e versioni successive supporta le reazioni `angry`, `sad`, `wow`, `love`, `like`, `laugh` e `other`.
`messages`	Viene inviata una notifica quando un cliente invia alla tua azienda: un messaggio contenente testo o contenuto multimediale (immagine/video/file/audio) una condivisione (condivisioni di contenuto multimediale/post) una risposta a una storia o una menzione in una storia. Solo le menzioni nelle storie attiveranno i webhook. I tag nei post normali non attiveranno alcun webhook. I webhook delle risposte alle storie al momento non supportano GIF o adesivi. una risposta a un messaggio in linea o un adesivo una risposta rapida o la selezione di un'opzione per rompere il ghiaccio o di un pulsante di modello generico un cliente cancella un messaggio un messaggio di un cliente non è supportato un cliente invia un messaggio dalla pagina dei dettagli di un prodotto di uno Shop di Instagram un cliente clicca su un'inserzione che rimanda a una conversazione nei messaggi di Instagram (Click To Direct, CTD) Viene inviata una notifica anche quando la tua azienda invia un messaggio a un cliente. Non viene inviata alcuna notifica quando la tua azienda reagisce o annulla l'aggiunta di una reazione al messaggio di un cliente. Questa callback si verifica in caso di invio di un messaggio dal tuo account Instagram. Il contrassegno `is_echo` sarà presente a indicare che il messaggio è stato inviato dall'account Instagram stesso. Nell'evento `message_reactions` non sarà consegnato alcun webhook echo
`messaging_postbacks`	Viene inviata una notifica quando un cliente clicca su un'opzione per rompere il ghiaccio o su un pulsante di modello generico Richiede la v8.0 o versioni successive. Richiede la v11.0 o versioni successive per l'inclusione del campo `mid`.
`messaging_seen`	Viene inviata una notifica ogni volta che un messaggio viene letto dal destinatario
`messaging_referral`	Viene inviata una notifica ogni volta che un cliente clicca su un link `ig.me` con un parametro di reindirizzamento in una conversazione esistente
`standby`	Quando il flusso di messaggi include più app, viene inviata una notifica quando un cliente invia un messaggio alla tua azienda, ma non è l'app a controllare la conversazione al momento dell'invio del messaggio.

Esempi di notifiche

Ecco alcuni esempi dei tipi di notifiche webhook che puoi ricevere.

Messaggi

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGID",  // ID of your Instagram Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": { "id": "IGSID" },    // Instagram-scoped ID for the customer who sent the message
          "recipient": { "id": "IGID" },  // ID of your Instagram Professional account
          "timestamp": 1569262485349,
          "message": {
            "mid": "MESSAGE-ID",   // ID of the message sent to your business
      
            "text": "MESSAGE-TEXT"     // Included when a customer sends a message containing text
      
            "attachments": [           // Included when a customer sends multiple media attachments or a URL for a story mention or share
              {
                "type":"image",             // Can be audio, file, image (image or sticker), share, story_mention, or video
                "payload":{ "url":"LINK" }  
              },
              {
                "type":"video",
                "payload":{ "url":"LINK" }
              }
            ]
      
            "is_deleted": true         // Included when a customer deletes a message
      
            "is_echo": true            // Included when your business sends a message to the customer

            "is_unsupported": true,    // Included when a customer sends a message with unsupported media
      
            "quick_reply": {           // Included when a customer clicks a quick reply
              "payload": "CUSTOMER-RESPONSE-PAYLOAD"   // The payload with the option selected by the customer
            },      
      
            "referral": {              // Included when a customer clicks an Instagram Shop product
              "product": {
                "id": "PRODUCT-ID"
            }      
      
            "referral": {                   // Included when a customer clicks an CTD ad
              "ref": "REF-DATA-IN-AD-IF-SPECIFIED"
              "ad_id": AD-ID,
              "source": "ADS",
              "type": "OPEN_THREAD",
              "ads_context_data": {
                "ad_title": TITLE-FOR-THE-AD,
                "photo_url": IMAGE-URL-THAT-WAS-CLICKED,
                "video_url": THUMBNAIL-URL-FOR-THE-AD-VIDEO,
              }
            }

            "reply_to":{               // Included when a customer sends an inline reply
              "mid":"MESSAGE-ID"
            } 
      
            "reply_to": {               // Included when a customer replies to a story
              "story": {
                "url":"CDN-URL",
                "id":"STORY-ID"       
              }
            }
          }
        }
      ]
    }
  ]
}

Reazioni ai messaggi

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGID",  // ID for your Instagram Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": {
            "id": "IGSID"  // Instagram-scoped ID for the customer who sent the message
          },
          "recipient": {
            "id": "IGID"  // ID for your Instagram Professional account
          },
          "timestamp": 1569262485349,
          "reaction" :{
            "mid" : "MESSAGE-ID",
            "action": "react",    // or unreact
            "reaction": "love", // optional, to unreact if there is no reaction field
            "emoji": "\u{2764}\u{FE0F}" // optional, to unreact if there is no emoji field
          } 
        }
      ]
    }
  ]
}

Postback dei messaggi

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGSID",  // ID of your Instagram Professional account
      "time": 1502905976963,
      "messaging": [
        {
          "sender": { "id": "IGSID" },    // Instagram-scoped ID for the customer who sent the message
          "recipient": { "id": "IGID" },  // ID of your Instagram Professional account
          "timestamp": 1502905976377,
          "postback": {
            "mid":"MESSAGE-ID",           // ID for the message sent to your business
            "title": "SELECTED-ICEBREAKER-REPLY-OR-CTA-BUTTON",
            "payload": "CUSTOMER-RESPONSE-PAYLOAD",  // The payload with the option selected by the customer
          }
        }
      ]
    }
  ]
}

Reindirizzamento dei messaggi

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGSID",  // ID of your Instagram Professional account  
      "time": 1502905976963,
      "messaging": [
        {
          "sender": {
            "id": "IGSID"  // Instagram-scoped ID for the customer who sent the message
          },
          "recipient": {
            "id": "IGID"  // ID of your Instagram Professional account
          },
          "timestamp": 1502905976377,
          "referral": {
                 "ref": "INFORMATION-INCLUDED-IN-REF-PARAMETER-OF-IGME-LINK"
                 "source": "IGME-SOURCE-LINK"  
                 "type":  "OPEN_THREAD"  // Only supported for existing conversations 
          }
        }
      ]
    }
  ]
}

Messaggi visti

{
   "object":"instagram",
   "entry":[
      {
         "id":"IGID",  // ID for your Instagram Professional account
         "time":1569262486134,
         "messaging":[
            {
               "sender":{
                  "id":"IGSID"  // Instagram-scoped ID for the customer who sent the message
               },
               "recipient":{
                  "id":"IGID"  // ID for your Instagram Professional account
               },
               "timestamp":1569262485349,
               "read":{
                  "mid":"MESSAGE-ID"
               }
            }
         ]
      }
   ]
}

Altri contenuti da consultare

Protocollo di consegna di Messenger - Se disponi di più di un'app che gestisce i messaggi, ad esempio un'app gestisce le risposte automatiche e un'altra le escalation a un operatore, dovrai implementare il protocollo di consegna per passare la conversazione da un'app all'altra.
Click To Direct, CTD - Visita il Centro assistenza per le aziende per scoprire di più sulla creazione di inserzioni che rimandano a Instagram Direct.

Assistenza per gli sviluppatori

Usa lo strumento relativo allo stato Meta per controllare lo stato e le interruzioni dei prodotti business di Meta.
Usa lo strumento di assistenza per gli sviluppatori Meta per segnalare bug e visionare quelli già segnalati, ottenere aiuto con Gestione inserzioni o Business Manager e altro ancora.
Consulta le Risorse di assistenza per la Piattaforma Messenger per conoscere ulteriori risorse per la Piattaforma Messenger.