Configurazione di webhook per Instagram

I webhook per Instagram consentono di ricevere notifiche in tempo reale ogni volta che qualcuno commenta gli oggetti multimediali degli utenti dell'app, @menziona gli utenti dell'app o quando le storie degli utenti dell'app scadono.

Ricevi notifiche webhook in tempo reale

Per ricevere notifiche webhook in tempo reale, devono essere soddisfatte le condizioni seguenti:

• Nell'app devono essere configurati i webhook per Instagram e deve essere attivata l'iscrizione per i campi appropriati nella Dashboard gestione app.
• Le app di tipo consumatore devono essere in modalità live.
• Le app di tipo business devono avere le autorizzazioni con un livello di accesso avanzato. Puoi richiedere l'accesso avanzato per le autorizzazioni come indicato di seguito:

• L'utente dell'app deve aver concesso le autorizzazioni appropriate (instagram_manage_insights per le storie, instagram_manage_comments per commenti e @menzioni).
• La Pagina collegata all'account dell'utente dell'app deve avere le iscrizioni alla Pagina abilitate.
• L'azienda collegata alla Pagina dell'utente dell'app deve essere verificata.
• L'account del creatore dell'oggetto multimediale su cui appare il commento o la @menzione non deve essere configurato come privato.

Limitazioni

• Le notifiche webhook per i commenti sugli album non includono l'ID album. Per ottenere l'ID album, interroga l'ID commento nel webhook e richiedi il suo campo media.
• Le app non ricevono notifiche webhook se il contenuto multimediale su cui appare il commento o la @menzione è stato creato da un account privato.
• Le metriche degli insight sulle Storie con numeri inferiori a 5 vengono restituite come -1.
• Le app ricevono notifiche webhook solo per commenti a contenuti multimediali di IG live, se il contenuto multimediale è in diretta.
• Reels non è supportato.
• Per ricevere notifiche webhook per i campi comments e live_comments, l'app deve aver completato correttamente l'analisi dell'app (accesso avanzato).
• Se il contenuto multimediale è usato per le inserzioni dinamiche, l'ID dell'inserzione non verrà restituito.

Passaggio 1: creazione di un endpoint

Crea un endpoint che accetti ed elabori i webhook. Durante la configurazione, seleziona l'oggetto API Instagram Graph, clicca su Configura e attiva l'iscrizione a uno o più campi di Instagram.

Campi di Instagram

Passaggio 2: abilitazione delle iscrizioni alla Pagina

L'app deve abilitare le iscrizioni alla Pagina collegata all'account dell'utente dell'app inviando una richiesta POST al segmento Page Subscribed Apps e attivando l'iscrizione a un qualsiasi campo della Pagina.

Requisiti dell'endpoint

• Token d'accesso della Pagina dell'utente dell'app
• pages_manage_metadata

Sintassi della richiesta

POST /{page-id}/subscribed_apps
  ?access_token={access-token}
  &subscribed_fields={fields}

Parametri della richiesta

La tua app non riceve notifiche di modifiche a un campo a meno che tu non configuri le iscrizioni alla Pagina nella Dashboard gestione app e attivi l'iscrizione al campo.

Esempio di richiesta

curl -i -X POST \
  "https://graph.facebook.com/v21.0/1755847768034402/subscribed_apps?subscribed_fields=feed&access_token=EAAFB..."

Esempio di risposta

{
  "success": true
}

Utilizzi comuni

Acquisizione di insight sulle storie

Se attivi l'iscrizione al campo story_insights, inviamo al tuo endpoint una notifica webhook contenente le metriche di interazione degli utenti su una Storia dopo che è scaduta.

Esempio di payload degli insight sulle storie

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "story_insights",
            "value": {
              "media_id": "18023345989012587",
              "exits": 1,
              "replies": 0,
              "reach": 17,
              "taps_forward": 12,
              "taps_back": 0,
              "impressions": 28
            }
          }
        ],
        "id": "17841405309211844",  // Instagram Business or Creator Account ID
        "time": 1547687043
      }
    ],
    "object": "instagram"
  }
]

Risposta a @menzioni nei commenti

Se attivi l'iscrizione al campo mentions, inviamo al tuo endpoint una notifica webhook ogni volta che un utente Instagram @menziona un account Instagram business o creator in un commento o una didascalia.

Ecco un esempio di payload di notifica webhook dei commenti inviato per un account Instagram business (17841405726653026):

Esempio di payload di @menzioni in un commento

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "comment_id": "17894227972186120",
              "media_id": "17918195224117851"
            }
          }
        ],
        "id": "17841405726653026",
        "time": 1520622968
      }
    ],
    "object": "instagram"
  }
]

Come ottenere il contenuto del commento

Per ottenere il contenuto del commento, usa la proprietà comment_id per interrogare il segmento GET /{ig-user-id}/mentioned_comment:

Esempio di query

GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_comment.comment_id(17894227972186120) 

Esempio di risposta

{
  "mentioned_comment": {
    "timestamp": "2018-03-20T00:05:29+0000",
    "text": "@bluebottle challenge?",
    "id": "17894227972186120"
  },
  "id": "17841405726653026"
}

Analizza il payload e rispondi

Quando ottieni la risposta, analizza il payload per la proprietà text per determinare se rispondere al commento. Per rispondere, utilizza i valori delle proprietà caption_id e media_id del payload di notifica webhook per interrogare l'endpoint POST /{ig-user-id}/mentions:

Esempio di query

curl -i -X POST \
  -d "comment_id=17894227972186120" \
  -d "media_id=17918195224117851" \
  -d "message=Challenge%20accepted!" \
  -d "access_token={access-token}" \
  "https://graph.facebook.com/17841405726653026/mentions"

Esempio di risposta

{
  "id": "17911496353086895"
}

Risposta a @menzioni nelle didascalie

Se attivi l'iscrizione al campo mentions, inviamo al tuo endpoint una notifica webhook ogni volta che un utente @menziona un account Instagram business o creator in un commento o una didascalia su un oggetto multimediale non di proprietà di uno di tali account.

Ecco un esempio di notifica webhook di una @menzione in una didascalia inviata per un account Instagram business (17841405726653026):

Esempio di notifica webhook di una @menzione in una didascalia

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "media_id": "17918195224117851"
            }
          }
        ],
        "id": "17841405726653026",
        "time": 1520622968
      }
    ],
    "object": "instagram"
  }
]

Come ottenere il contenuto della didascalia

Per ottenere il contenuto della didascalia, usa la proprietà media_id per interrogare il segmento GET /{ig-user-id}/mentioned_media:

Esempio di query

GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_media.media_id(17918195224117851){caption,media_type} 

Esempio di risposta

{
  "mentioned_media": {
    "caption": "@bluebottle There can be only one!",
    "media_type": "IMAGE",
    "id": "17918195224117851"
  },
  "id": "17841405726653026"
}

Analizza il payload e rispondi

Quando ottieni la risposta, analizza il payload per la proprietà caption per determinare se rispondere al commento. Per rispondere, utilizza la proprietà media_id del webhook per interrogare il segmento POST /{ig-user-id}/mentions:

Esempio di query

curl -i -X POST \
  -d "media_id=17918195224117851" \
  -d "message=MacLeod%20agrees!" \
  -d "access_token={access-token}" \
  "https://graph.facebook.com/17841405726653026/mentions"

Esempio di risposta

{
  "id": "17911496353086895"
}