Piattaforma Messenger

API Conversations per la Piattaforma Messenger

Questo documento spiega come ottenere informazioni sulle conversazioni su Messenger e tramite la messaggistica di Instagram. Puoi ottenere:

  • Una lista di conversazioni per la tua Pagina Facebook o il tuo account Instagram per professionisti
  • Una lista di messaggi all'interno di ogni conversazione
  • Dettagli su ogni messaggio, incluso l'orario di invio del messaggio e il mittente

Prima di iniziare

Questo tutorial presuppone che tu abbia letto la Panoramica della Piattaforma Messenger e la Panoramica dei messaggi di Instagram e abbia implementato i componenti necessari.

Ecco cosa ti servirà:

  • L'ID della tua Pagina Facebook per l'azienda o la Pagina Facebook collegata all'account Instagram per professionisti
  • Un token d'accesso della Pagina richiesto da una persona che può eseguire l'attività MESSAGING o MODERATE sulla Pagina
  • L'accesso avanzato è necessario per accedere alle conversazioni tra l'azienda e le persone che non dispongono di un ruolo nella tua app di messaggistica, nell'account Instagram per professionisti, nella Pagina Facebook o nell'azienda

Per le conversazioni su Messenger tra le persone e la Pagina, la tua app avrà bisogno di:

Per le conversazioni tramite la messaggistica di Instagram tra le persone e il tuo account Instagram per professionisti, la tua app avrà bisogno di:

  • Un token d'accesso della Pagina richiesto da una persona che può eseguire l'attività MESSAGING sulla Pagina collegata al tuo account Instagram Business
  • Le autorizzazioni instagram_basic, instagram_manage_messages e pages_manage_metadata
  • La tua app deve essere di proprietà di un'azienda verificata

Limitazioni

  • Solo l'URL dell'immagine o del video di una condivisione sarà incluso nei dati restituiti in una chiamata all'API o nella notifica webhook.
  • Se gli account sono collegati utilizzando chiavi private, come un'e-mail o un numero di telefono, non potrai recuperare le conversazioni tra questi account. Saranno disponibili solo le conversazioni tra un utente Facebook e un account Instagram. Questo problema verrà risolto quando all'app verrà concesso l'accesso avanzato. Se disponi di più account collegati nel Centro gestione account dell'app Instagram, potrai recuperare le conversazioni tra tutti gli account collegati.
  • Le conversazioni all'interno della cartella Richieste che non sono state attive per 30 giorni non verranno restituite nelle chiamate API.

Puoi utilizzare questa API per sincronizzare le conversazioni precedenti nella posta in caso di nuova connessione di un account Instagram Business alla tua app.

Acquisizione di una lista di conversazioni

Per ottenere una lista di conversazioni, invia una richiesta GET all'endpoint /PAGE-ID/conversations e includi il parametro platform impostato su instagram o messenger.

Esempio di richiesta

Formattato per una maggiore leggibilità
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

In caso di azione eseguita correttamente, la tua app riceverà un oggetto JSON con una lista di ID per le conversazioni tra te e una persona e l'orario di invio dell'ultimo messaggio.

{
  "data": 
    {
      "id": "CONVERSATION-ID-1",  
      "updated_time": "UNIX-TIMESTAMP"
    },
    {
      "id": "CONVERSATION-ID-2",   
      "updated_time": "UNIX-TIMESTAMP"
    }
    ...
  ]
}

Ricerca di una conversazione con un utente specifico

Per ottenere una conversazione tra il tuo account Instagram per professionisti o la tua Pagina Facebook e una persona specifica, invia una richiesta GET all'endpoint /PAGE-ID/conversations con il parametro platform e i parametri user_id impostati sull'ID assegnato di Instagram o sull'ID della singola Pagina per la determinata persona.

Esempio di richiesta

Formattato per una maggiore leggibilità
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &user_id=INSTAGRAM-OR-PAGE-SCOPED-ID
    &access_token=PAGE-ACCESS-TOKEN"

In caso di azione eseguita correttamente, la tua app riceverà l'ID della conversazione.


{
  "data": [
      {
        "id": "CONVERSATION-ID"
      },
  ]
}

Acquisizione di una lista di messaggi in una conversazione

Per ottenere una lista di messaggi in una conversazione, invia una richiesta GET all'endpoint /CONVERSATION-ID e includi il campo messages.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/CONVERSATION-ID
    ?fields=messages
    &access_token=PAGE-ACCESS-TOKEN"

In caso di azione eseguita correttamente, la tua app riceverà una lista di ID dei messaggi e l'orario di creazione di ogni messaggio.

{
  "messages": {
    "data": [
      {
        "id": "Message ID-1",      
        "created_time": "UNIX-TIMESTAMP-MOST-RECENT-MESSAGE"  
      },
      {
        "id": "Message ID-2",
        "created_time": "UNIX-TIMESTAMP"
      },
      {
        "id": "Message ID-3",
        "created_time": "UNIX-TIMESTAMP"
      },
...
    ]
  },
  "id": "Conversation ID", 
}

Acquisizione di informazioni su un messaggio

Per ottenere informazioni su un messaggio, come il mittente, il destinatario e il contenuto del messaggio, invia una richiesta GET all'endpoint /MESSAGE-ID con i campi che ti interessano.

I campi predefiniti sono id e created_time.

Nota: le richieste all'endpoint /CONVERSATION-ID restituiranno gli ID dei messaggi in una conversazione. Tuttavia, puoi visualizzare i dettagli solo sui 20 messaggi più recenti della conversazione. Se richiedi un messaggio precedente agli ultimi 20, visualizzerai un errore che indica l'eliminazione del messaggio. 

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/MESSAGE-ID
    ?fields=id,created_time,from,to,message
    &access_token=PAGE-ACCESS-TOKEN"

Se l'azione viene eseguita correttamente, l'app riceve la seguente risposta JSON: In questo esempio, un cliente ha inviato un semplice messaggio di testo al tuo account Instagram per professionisti.

{
  "id": "aWdGGiblWZ...",
  "created_time": "2022-07-12T19:11:07+0000",
  "to": {
    "data": [
      {
        "username": "INSTAGRAM-PROFESSIONAL-ACCOUNT-USERNAME",
        "id": "INSTAGRAM-PROFESSIONAL-ACCOUNT-ID"
      }
    ]
  },
  "from": {
    "username": "INSTAGRAM-USERNAME",
    "id": "INSTAGRAM-SCOPED-ID"
  },
  "message": "Hi Kitty!"
}

Per saperne di più

Visita il nostro riferimento per:

Assistenza per gli sviluppatori