API Conversions per la messaggistica aziendale

L'API Conversions consente agli inserzionisti di inviare eventi web, nell'app, nei punti vendita fisici e relativi alla messaggistica aziendale a Meta attraverso un unico endpoint anziché attraverso più origini. Questo consolidamento può semplificare lo stack tecnologico degli inserzionisti e creare una visione più completa in Gestione eventi di Meta usando i dataset.

Questa documentazione fornisce indicazioni per integrare gli eventi di messaggistica aziendale nell'API Conversions. I vantaggi dell'utilizzo dell'API Conversions per la messaggistica aziendale includono (ma non sono limitati a):

Risultati visibili direttamente nei report di Gestione inserzioni: gli inserzionisti possono facilmente comprendere i risultati delle campagne che rimandano ai messaggi sulla base dei risultati pertinenti direttamente sulle piattaforme di Meta, ad esempio, il numero di acquisti e il costo per acquisto, invece delle conversazioni iniziate.
Semplificazione dell'integrazione dei dati: un'API per inserire e condividere i dati attraverso più piattaforme di messaggistica (Messenger, WhatsApp) e canali (sito web, app, negozi, messaggistica).
Miglioramento della misurazione dei partner: abilita l'attribuzione delle campagne che rimandano ai messaggi direttamente sulle dashboard dei partner tramite l'API Ads Insights.

Prerequisiti

Dataset

Gli eventi di messaggistica aziendale inviati attraverso l'API Conversions devono essere associati a un dataset.

I dataset consentono agli inserzionisti di connettere e gestire i dati degli eventi da origini web, app, negozio e messaggistica aziendale all'API Conversions. I dataset potrebbero mostrare i dati sugli eventi provenienti da tutte le seguenti integrazioni che decidi di configurare:

Pixel di Meta (eventi del sito web)
API App Events (eventi nell'app, inclusi SDK di Facebook per iOS o Android, Mobile Measurement Partner (MMP))
API Offline Conversions (API legacy di Meta per gli eventi offline)

I dataset consentono di visualizzare tutte le attività dei clienti da un'unica interfaccia. Consentono inoltre di ridurre l'impegno necessario per creare e gestire diverse integrazioni API.

In Gestione eventi, gli inserzionisti hanno diverse opzioni per creare un dataset in base al loro punto di partenza. In alternativa, puoi creare un nuovo dataset in Gestione eventi collegando le informazioni durante la creazione di insiemi di eventi offline o attraverso un'app mobile esistente o durante la creazione dell'insieme di eventi di messaggistica. Il collegamento di un dataset a un'app è necessario prima di inviare eventi nell'app mobile all'API Conversions ed è possibile collegare a un dataset solo un'app. Per consultare altri dettagli e istruzioni, vedi qui.

Autorizzazioni

Per implementare un'integrazione diretta come inserzionista, segui le istruzioni riportate qui per prerequisiti e autorizzazioni.
Per implementare un'integrazione piattaforma partner, è necessario avere:
- accesso avanzato alle autorizzazioni ads_read, ads_management, pages_messaging, whatsapp_business_messagingpages_show_list e instagram_manage_messages;
- funzione Accesso standard a Gestione inserzioni;
- in base ai tipi di eventi, devi avere l'accesso avanzato all'autorizzazione page_events per gli eventi Messenger o WhatsApp o instagram_manage_events per Instagram Direct.

Registrazione dei partner

Se implementi un'integrazione di partner come piattaforma, puoi usare i metodi di registrazione Facebook Login for Business (consigliato) oppure l'estensione Meta Business.

Consulta le Guide sull'API Conversions per la messaggistica aziendale, contenenti guide all'integrazione con istruzioni dettagliate.

API Dataset per messaggistica e WhatsApp

L'API Dataset viene utilizzata per recuperare il dataset_id associato a una pagina specifica. Questo dataset_id viene utilizzato in seguito nell'API Conversions. Per utilizzare l'API Dataset, alla tua app deve essere concessa dal tuo cliente l'autorizzazione page_events per gli eventi Messenger o WhatsApp attraverso Facebook Login for Business o l'estensione Meta Business.

Per recuperare il dataset_id, devi effettuare una chiamata GET all'API Dataset con page_id e access_token. Consulta l'esempio di chiamata di seguito:

https://graph.facebook.com/v16.0/{PAGE_ID}/dataset?access_token={TOKEN}

La risposta sarà un ID, che rappresenta il dataset_id. Utilizzando questo e il token d'accesso ricevuto in precedenza, puoi ora chiamare l'API Conversions per inviare eventi di messaggistica a Meta.

API Dataset per Instagram

L'API Dataset viene utilizzata per recuperare il dataset_id associato a una pagina specifica. Questo dataset_id viene utilizzato in seguito nell'API Conversions. Per poter utilizzare l'API Dataset, il tuo cliente dovrà concedere l'autorizzazione instagram_manage_events alla tua app attraverso Facebook Login for Business o l'estensione Meta Business.

Per recuperare il dataset_id, dovrai effettuare una chiamata GET all'API Dataset con ig_user_id e access_token. Ecco un esempio di chiamata:

https://graph.facebook.com/v16.0/{IG_USER_ID}/dataset?access_token={TOKEN}

La risposta sarà un ID, che rappresenta il dataset_id. Utilizzando questo e il token d'accesso ricevuto in precedenza, ora puoi chiamare l'API Conversions per inviare eventi di messaggistica a Meta.

Configurazione

Configurazione dei parametri degli eventi di messaggistica aziendale

Puoi fare riferimento qui per l'insieme attuale dei parametri che possono essere inviati attraverso l'API Conversions. Per inviare eventi di messaggistica aziendale, i campi seguenti possono essere condivisi nel payload dei dati dell'utente per diverse piattaforme di messaggistica:

Piattaforma	Parametro	Descrizione
Messenger	`page_id`	Obbligatorio per Messenger ID della Pagina Facebook associata all'azienda.
Messenger	`page_scoped_user_id`	Obbligatorio per Messenger Gli utenti che interagiscono con le Pagine sono identificati da ID utente della singola Pagina (PSID). Il PSID può essere ottenuto da questo webhook.
WhatsApp	`page_id`	Obbligatorio per WhatsApp ID della Pagina Facebook associata all'azienda WhatsApp.
WhatsApp	`ctwa_clid`	Obbligatorio per WhatsApp `ctwa_clid` è disponibile solo dall'oggetto di reindirizzamento nel webhook messaggi sull'API Business versioni 2.45.1 e successive (On Premise) o dall'API Cloud.
Instagram	`ig_account_id`	Obbligatorio per Instagram ID account Instagram associato all'azienda.
Instagram	`ig_sid`	Obbligatorio per Instagram Gli utenti che interagiscono con Instagram vengono identificati da ID utente per Instagram (IGSID). L'IGSID può essere ottenuto da questo webhook.

Invio di eventi

Per inviare nuovi eventi, fai una richiesta POST all'API Conversions da questo percorso:

https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}

Quando pubblichi su questo segmento, Meta crea nuovi eventi di messaggistica aziendale. Per maggiori dettagli, consulta il seguente documento per gli sviluppatori.

Di seguito è riportata una panoramica di come si inseriscono i parametri nello schema complessivo del payload.

Per eventi di Messenger:

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "messenger",
      "user_data": {
        "page_id": <PAGE_ID>,
        "page_scoped_user_id": <PSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

Per eventi di WhatsApp:

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "whatsapp",
      "user_data": {
        "page_id": <PAGE_ID>,
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a", // <CLICK_TO_WHATSAPP_CLICK_ID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

Per eventi di Instagram:

Esempio di richiesta CTD CAPI

POST /{dataset_id}/events

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "instagram",
      "user_data": {
        "ig_account_id": <IG_ACCOUNT_ID>,
        "ig_sid": <IGSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

Risoluzione dei problemi

Usa lo strumento Testa gli eventi in Gestione eventi per i test:

Vai a Gestione eventi, seleziona un dataset collegato alla Pagina.
Clicca sulla scheda Testa gli eventi.
Seleziona il canale di marketing e il canale di messaggistica.
Clicca sul pulsante Tool di esplorazione per la API Graph.
Il Tool di esplorazione per la API Graph sarà popolato con il payload precompilato.
Clicca sul pulsante Invia.

Guida video

Guarda questo video per una spiegazione dettagliata di come implementare un'integrazione.

Si è verificato un errore

Stiamo riscontrando problemi con la riproduzione di questo video.

Scopri di più

Domande frequenti

Quali tipi di eventi di messaggistica sono supportati dall'API Conversions per la messaggistica aziendale?

R: l'API Conversions per la messaggistica aziendale attualmente supporta solo contatti inviati ed eventi di acquisto per la messaggistica aziendale. Gli eventi di messaggistica dovrebbero rappresentare solo le interazioni del cliente che si verificano nella conversazione, non le conversioni che si verificano su altri canali come i siti web. Puoi distinguere facilmente gli eventi scegliendo l'origine delle azioni corrispondente durante la procedura di integrazione.

Ci sono indicazioni di Meta relative al mantenimento delle stesse app o all'uso di app differenti per integrazioni diverse dell'API Conversions?

R: come best practice, è consigliabile che un partner utilizzi una sola app, in modo che Meta possa identificare tutti gli eventi inviati dal partner. Se sei un partner che ha già diverse app, assicurati che il partner_agent sia impostato sul nome dell'agente partner assegnato a te. In caso di dubbi, rivolgiti al tuo rappresentante di Meta.

Se una conversione avviene fuori dalla conversazione (ad esempio, sul mio sito web o sulla mia app), in che modo gli eventi vengono passati a Meta?

R: se una conversione avviene fuori dalla conversazione, dovresti comunque inviare quell'evento a Meta utilizzando il prodotto API Conversions appropriato. Ad esempio, se una conversione avviene sul tuo sito web, usa l'API Conversions per il web. Se la conversione avviene nell'app, usa l'API Conversions per gli eventi nell'app. L'evento sarà ancora attribuito all'ID clic per l'API Conversions per il web. La lista completa dei parametri è riportata qui.

L'API Conversions abilita l'ottimizzazione per le inserzioni che rimandano ai messaggi?

R: l'API Conversions abilita l'accesso all'ottimizzazione degli acquisti solo per le inserzioni che rimandano a Messenger, ma al momento non è disponibile per l'ottimizzazione delle inserzioni su WhatsApp. Per le inserzioni che rimandano a WhatsApp, puoi ottimizzare le tue campagne pubblicitarie per aumentare le conversazioni.

Posso riutilizzare il dataset esistente per l'API Conversions per la messaggistica aziendale?

R: sì, supportiamo il collegamento con dataset esistenti; consulta le opzioni disponibili per scegliere l'opzione giusta per la tua azienda.

Se oggi utilizzo l'API Conversions per il sito web, l'aggiunta della messaggistica aziendale alla stessa integrazione interferirebbe con la mia integrazione esistente?

R: non ci sono rischi nell'aggiungere la messaggistica aziendale all'integrazione CAPI esistente. L'attribuzione è basata sull'ID pagina/dataset e non è correlata all'ID app.

Quanti dataset possono essere collegati a una Pagina?

R: a una Pagina è possibile collegare solo un dataset.

Devo deduplicare gli eventi prima di inviarli attraverso l'API Conversions per la messaggistica aziendale?

R: Meta non fornisce supporto nella deduplicazione degli eventi per l'API Conversions per la messaggistica aziendale, quindi raccomandiamo fortemente agli inserzionisti di eseguire la deduplicazione prima di inviare gli eventi attraverso l'API Conversions per la messaggistica aziendale.

Altri contenuti da consultare

Panoramica dell'API Conversions
Utilizzo dell'API Conversions
Parametri dell'API Conversions
Best practice
Piattaforma WhatsApp Business (API On Premise o API Cloud) con le versioni dell'API Business 2.45.1 e successive
API Instagram Messaging