Primi passi

Questo documento spiega come effettuare correttamente una chiamata API Messenger con supporto per Instagram (anche nota come API Instagram Messaging nelle nostre Normative per gli sviluppatori) con la tua app e come ricevere messaggi da account Instagram per professionisti. Presuppone che tu abbia familiarità con l'API Graph e Facebook Login.

Prima di iniziare

Dovrai avere accesso a quanto segue:

• Un account Instagram per professionisti
• Una Pagina Facebook collegata a quello specifico account
• Un account sviluppatore di Meta in grado di eseguire MODERATEattività su quella Pagina
• Un'app di Meta creata con il caso d'uso di Facebook Login e le impostazioni di base configurate

Sviluppatori che hanno iniziato a utilizzare la piattaforma Messenger da poco

• Segui la guida dettagliata descritta di seguito su come generare il token d'accesso della Pagina, configurazione dei webhook.
• Scopri le diverse funzioni della piattaforma e adotta quelle che si adattano alle tue esigenze.

Sviluppatori con precedente esperienza relativa alla Piattaforma Messenger

• I concetti di token d'accesso e webhook sono simili. L'API Messenger con supporto per Instagram richiederà instagram_manage_messages nel token d'accesso della Pagina e l'iscrizione ai webhook dell'argomento Instagram.
• La maggior parte delle funzioni è simile all'API Messenger. Consulta i dettagli nella lista delle funzioni e adotta quelle che si adattano alle tue esigenze.

Flusso di accesso

Puoi usare Facebook Login o Business Login per Instagram per chiedere agli utenti della tua app le autorizzazioni necessarie.

Il flusso Business Login per Instagram consente a una persona di completare le seguenti operazioni durante il flusso di accesso:

• Convertire il proprio account Instagram in un account Instagram per professionisti
• Creare una Pagina Facebook per la propria azienda
• Collegare quella Pagina al proprio account Instagram per professionisti

Per implementare Business Login per Instagram, consulta la nostra guida Business Login per Instagram , poi torna a questa guida.

1. Acquisizione di un token d'accesso dell'utente

Assicurati di aver effettuato l'accesso al tuo account sviluppatore di Facebook, quindi accedi alla tua app e attiva la finestra modale di Facebook Login. Ricorda: il tuo account sviluppatore di Facebook deve essere in grado di eseguire attività sulla Pagina Facebook collegata all'account Instagram che desideri interrogare con accesso almeno di livello "Moderato".

Dopo aver attivato la finestra modale, clicca su OK per concedere alla tua app le autorizzazioni instagram_basic, instagram_manage_messages e pages_manage_metadata.

L'API dovrebbe restituire un token d'accesso dell'utente. Acquisisci il token in modo che la tua app possa usarlo nelle query successive. Se stai utilizzando il Tool di esplorazione per la API Graph, verrà acquisito automaticamente e visualizzato nel campo Token d'accesso come riferimento:

2. Acquisizione delle Pagine dell'utente

Interroga l'endpoint GET /me/accounts (si traduce in GET /{user-id}/accounts, che esegue un GET sul nodo User di Facebook, in base al tuo token d'accesso).

curl -i -X GET \
 "https://graph.facebook.com/v9.0/me/accounts?access_token={access-token}"

Questa operazione dovrebbe restituire una raccolta di Pagine Facebook su cui l'utente attuale può eseguire le attività MANAGE, CREATE_CONTENT, MODERATE o ADVERTISE:

{
  "data": [
    {
      "access_token": "EAAJjmJ...",
      "category": "App Page",
      "category_list": [
        {
          "id": "2301",
          "name": "App Page"
        }
      ],
      "name": "Metricsaurus",
      "id": "134895793791914",  // capture the Page ID
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    }
  ]
}

Acquisisci l'ID della Pagina Facebook collegata all'account Instagram che desideri interrogare. Tieni presente che gli utenti della tua app potrebbero essere in grado di eseguire attività su più Pagine, quindi più avanti dovrai introdurre una logica in grado di determinare l'ID della Pagina corretto da acquisire (o ideare un'interfaccia utente in cui gli utenti possano indicare la Pagina corretta).

3. Acquisizione del token d'accesso della Pagina

Per eseguire varie chiamate API Instagram Messaging, dovrai utilizzare il token d'accesso della Pagina (PAT) associato dell'account Instagram pertinente che è stato precedentemente autorizzato tramite Facebook Login.

Invia una richiesta GET all'endpoint /{page-id} utilizzando il token d'accesso dell'utente. Ad esempio:

curl -i -X GET "https://graph.facebook.com/{page-id}?
  fields=access_token&
  access_token={user-access-token}"  

In caso di azione eseguita correttamente, l'app riceve questa risposta:

{
  "access_token":"{page-access-token}",
  "id":"{page-id}"              
}  

• Se hai utilizzato un token d'accesso dell'utente di breve durata, il token d'accesso della Pagina è valido solo per 1 ora.
• Se hai utilizzato un token d'accesso dell'utente di lunga durata, il token d'accesso della Pagina non ha scadenza.

Per generare un token d'accesso della Pagina di lunga durata, puoi seguire la guida che trovi qui.

3a. Acquisizione del token d'accesso della Pagina tramite lo strumento Dashboard per gli sviluppatori di Instagram

Facoltativamente, se possiedi le risorse (account Instagram e Pagina Facebook) che desideri incorporare in Messenger API con supporto per Instagram, puoi sfruttare lo strumento di configurazione di Instagram nella Dashboard gestione app per sviluppatori per configurare facilmente token d'accesso della Pagina e webhook. Lo strumento è disponibile in Dashboard gestione app per sviluppatori → Messenger → Impostazioni di Instagram. La procedura attuale di configurazione di token e webhook continuerà a funzionare, ma questo strumento ti consentirà di configurare l'ambiente con maggiore facilità.

4. Abilitazione delle impostazioni degli strumenti collegati per il controllo dei messaggi

Per gestire i messaggi di Instagram tramite l'API, gli account Instagram per professionisti dovranno abilitare gli strumenti collegati nelle impostazioni di controllo dei messaggi.

5. Acquisizione degli oggetti della posta dell'account Instagram per professionisti

Utilizza l'ID della Pagina acquisito e il token d'accesso della Pagina (PAT) per interrogare l'endpoint GET /{page-id}/conversations?platform=instagram:

curl -i -X GET \
 "https://graph.facebook.com/v9.0/17841405822304914/conversations?platform=instagram&access_token={access-token}"  

Questa operazione dovrebbe restituire gli ID di tutti gli oggetti della conversazione sull'utente Instagram:

{
  "data": [
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTM2MDk5MDc1MzYyOTgx"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTYzMzQ2MzE5NjM1NDcy"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTk3MTY0NjI2NzAyMjMw"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MzkzNDI5MDYzMzkyNjU0"
    }
}

Se riesci a eseguire correttamente questa query finale, dovresti essere in grado di eseguire query utilizzando uno qualsiasi degli endpoint di Messenger API con supporto per Instagram: consulta le nostre guide e i vari riferimenti per sapere cosa può fare ogni endpoint e quali autorizzazioni richiede.

Passaggi successivi

• Continua a sviluppare la tua app in modo che possa utilizzare correttamente qualsiasi altro endpoint di cui ha bisogno e tenere traccia delle autorizzazioni richieste da ciascun endpoint
• Completa la configurazione dei webhook in modo da poter ricevere notifiche in tempo reale ogni volta che l'utente invia un messaggio all'account Instagram per professionisti.
• Completa la procedura di analisi dell'app e richiedi l'approvazione per tutte le autorizzazioni di cui hai bisogno in modo che gli utenti possano concederle quando l'app è in produzione.