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:

Se le autorizzazioni dell'app non hanno l'accesso avanzato, l'app non riceve notifiche webhook.

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.
I reel non sono supportati.
Per ricevere notifiche webhook per i campi comments e live_comments, l'app deve aver completato correttamente l'analisi dell'app (accesso avanzato).

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

Campo	Descrizione	Autorizzazioni richieste
`comments`	Commenti su un contenuto multimediale di IG di proprietà dell'utente Instagram della tua app. `ad_id` e `ad_title` saranno restituiti nell'oggetto multimediale quando una persona commenta un post di Instagram in evidenza o un post di inserzioni di Instagram e ciò potrebbe determinare notifiche webhook duplicate.	instagram_manage_comments pages_manage_metadata pages_read_engagemento pages_show_list
`live_comments`	Commenti su un contenuto multimediale di IG in diretta di proprietà dell'utente Instagram della tua app.	instagram_manage_comments pages_manage_metadata pages_read_engagemento pages_show_list
`mentions`	@menzioni dell'utente Instagram della tua app in un commento.	instagram_manage_comments pages_manage_metadata pages_read_engagemento pages_show_list
`story_insights`	Metriche che descrivono le interazioni su una storia. Inviate 1 ora dopo la scadenza della storia.	instagram_manage_insights pages_manage_metadata pages_read_engagemento pages_show_list

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

Segnaposto del valore	Descrizione del valore
`{page_id}`	ID della Pagina collegata all'account dell'utente dell'app.
`{access_token}`	Token d'accesso della Pagina dell'utente dell'app.
`{fields}`	Un campo della Pagina (ad esempio `feed`).

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/v19.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"
}

Analisi del payload e risposta

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"
}

Analisi del payload e risposta

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"
}