Recupero dei contatti

Puoi leggere i contatti tramite webhook o lettura in blocco.

Prima di iniziare

Per leggere campi specifici delle inserzioni, come ad_id, campaign_id, avrai bisogno di:

Per leggere tutti i dati dei contatti e i dati a livello di inserzione, avrai bisogno di:

Nota: se l'amministratore di questa Pagina non ha mai personalizzato i contatti né fornito l'autorizzazione di accesso mediante lo strumento di gestione dell'accesso ai contatti, TUTTI gli amministratori della Pagina disporranno dell'autorizzazione relativa all'accesso ai contatti. Se tale autorizzazione è personalizzata dagli amministratori strumenti business, allora la sua disponibilità per un amministratore di base della Pagina dipenderà dalla configurazione scelta dall'amministratore strumenti business.

Rate limiting

Il rate limiting è 200 moltiplicato per 24 moltiplicato per il numero di contatti creati negli ultimi 90 giorni per una Pagina Facebook. Se effettui un numero superiore di chiamate in un periodo di 24 ore, la richiesta restituisce un errore.

Filtro per intervallo di date

Invia una richiesta GET all'endpoint /ads/lead_gen/export_csv/ dove i formati data sono indicazioni temporali POSIX o UNIX:

curl -i -X GET "https://www.facebook.com/ads/lead_gen/export_csv/
    ?id=<FORM_ID>
    &type=form
    &from_date=1482698431
    &to_date=1482784831"

Precisazioni

  • Se from_date non è impostato o è un valore inferiore all'ora di creazione del modulo, si utilizza l'ora di creazione del modulo.
  • Se to_date non è impostato o è un'ora successiva a quella presente, si utilizza l'ora corrente.

  • La presenza nel TSV di voci senza ID dell'inserzione o ID del gruppo di inserzioni può essere dovuta ai seguenti motivi:

    • Il contatto è generato dalla copertura organica. In questo caso, is_organic nel TSV viene visualizzato 1; altrimenti, il valore è 0.
    • Il contatto può essere inviato da un'anteprima dell'inserzione.
    • La persona che richiede i contatti non dispone di privilegi di inserzionista sull'account pubblicitario.

Webhook

Ottieni aggiornamenti in tempo reale per le inserzioni per acquisizione contatti.

Passaggio 1: come iniziare

Consulta la nostra guida introduttiva ai webhook per configurare il tuo endpoint e il tuo webhook.

Passaggio 2: ottenere un token d'accesso della Pagina di lunga durata

Genera un singolo token della Pagina di lunga durata per recuperare continuamente i dati senza doverti preoccupare della scadenza.

Passaggio 3: installare l'app sulla Pagina

Consulta la nostra guida ai webhook per le Pagine per scoprire come installare la tua app su una Pagina.

Risposta webhook

Alla creazione dell'acquisizione dei contatti, l'app riceve la seguente risposta webhook:

array(
  "object" => "page",
  "entry" => array(
    "0" => array(
      "id" => 153125381133,
      "time" => 1438292065,
      "changes" => array(
        "0" => array(
          "field" => "leadgen",
          "value" => array(
            "leadgen_id" => 123123123123,
            "page_id" => 123123123,
            "form_id" => 12312312312,
            "adgroup_id" => 12312312312,
            "ad_id" => 12312312312,
            "created_time" => 1440120384
          )
        ),
        "1" => array(
          "field" => "leadgen",
          "value" => array(
            "leadgen_id" => 123123123124,
            "page_id" => 123123123,
            "form_id" => 12312312312,
            "adgroup_id" => 12312312312,
            "ad_id" => 12312312312,
            "created_time" => 1440120384
          )
        )
      )
    )
  )
)

Puoi usare leadgen_id per recuperare i dati associati al contatto:

curl -X GET \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v21.0/{lead-id}/
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const Lead = bizSdk.Lead; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<LEAD_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { }; const sample_code = (new Lead(id)).get( fields, params ); logApiCallResult('sample_code api call complete.', sample_code);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\Lead; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<LEAD_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( ); echo json_encode((new Lead($id))->getSelf( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.lead import Lead from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<LEAD_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { } print Lead(id).get( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<LEAD_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new Lead(id, context).get() .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<LEAD_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end lead = FacebookAds::Lead.get(id ,'')

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

{
  "created_time": "2015-02-28T08:49:14+0000", 
  "id": "<LEAD_ID>", 
  "ad_id": "<AD_ID>",
  "form_id": "<FORM_ID>",
  "field_data": [{
    "name": "car_make",
    "values": [
      "Honda"
    ]
  }, 
  {
    "name": "full_name", 
    "values": [
      "Joe Example"
    ]
  }, 
  {
    "name": "email", 
    "values": [
      "joe@example.com"
    ]
  },
  {
    "name": "selected_dealer", 
    "values": [
      "99213450"
    ]
  }],
  ...
}

Ulteriori informazioni

Puoi vedere un esempio di questa implementazione nel nostro repository GitHub.

Lettura in blocco

Le app create dopo il 2 luglio 2018 sono obbligate a utilizzare l'autorizzazione leads_retrieval per leggere i contatti.

leads esiste sia sul nodo del gruppo di inserzioni sia su quello del modulo. Vengono restituiti tutti i dati associati ai rispettivi oggetti. Dato che un modulo può essere riutilizzato per più inserzioni, il tuo modulo può contenere molti più contatti di quelli utilizzati dall'inserzione.

Per effettuare la lettura in blocco per inserzione:

curl -X GET \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v21.0/{adgroup-id}/leads
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const Ad = bizSdk.Ad; const Lead = bizSdk.Lead; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_GROUP_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { }; const leadss = (new Ad(id)).getLeads( fields, params ); logApiCallResult('leadss api call complete.', leadss);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\Ad; use FacebookAds\Object\Lead; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_GROUP_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( ); echo json_encode((new Ad($id))->getLeads( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.ad import Ad from facebook_business.adobjects.lead import Lead from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_GROUP_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { } print Ad(id).get_leads( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_GROUP_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new Ad(id, context).getLeads() .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_GROUP_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad = FacebookAds::Ad.get(id) leadss = ad.leads({ fields: { }, })

Per effettuare la lettura per modulo:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'fields=created_time,id,ad_id,form_id,field_data' \
  https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads

Risposta:

{
  "data": [
    {
      "created_time": "2018-02-28T08:49:14+0000", 
      "id": "<LEAD_ID>", 
      "ad_id": "<AD_ID>",
      "form_id": "<FORM_ID>",
      "field_data": [
        {
          "name": "car_make",
          "values": [
            "Honda"
          ]
        }, 
        {
          "name": "full_name", 
          "values": [
            "Joe Example"
          ]
        }, 
        {
          "name": "email", 
          "values": [
            "joe@example.com"
          ]
        },
      ], 
      ...
    }
  ],
  "paging": {
    "cursors": {
      "before": "OTc2Nz3M8MTgyMzU1NDMy", 
      "after": "OTcxNjcyOTg8ANTI4NzE4"
    }
  }
}

Lettura del valore della domanda dello strumento di localizzazione dei punti vendita

La domanda dello strumento di localizzazione dei punti vendita non è diversa da qualsiasi altra domanda. Una domanda dello strumento di localizzazione dei punti vendita avrà anche un ID del campo che verrà mappato in base alle domande durante la creazione del modulo. L'invio avverrà in modo simile a quello delle altre domande. Il valore passato sarà ricavato dal numero del punto vendita del luogo selezionato.

Ad esempio, supponiamo di avere una domanda dello strumento di localizzazione dei punti vendita con selected_dealer come ID del campo. Per recuperare i contatti in gruppo puoi chiamare:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'fields=created_time,id,ad_id,form_id,field_data' \
  https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads

Risposta:

{
  "data": [
    {
      "created_time": "2018-02-28T08:49:14+0000", 
      "id": "<LEAD_ID>", 
      "ad_id": "<AD_ID>",
      "form_id": "<FORM_ID>",
      "field_data": [
        {
          "name": "car_make",
          "values": [
            "Honda"
          ]
        }, 
        {
          "name": "full_name", 
          "values": [
            "Joe Example"
          ]
        }, 
        {
          "name": "email", 
          "values": [
            "joe@example.com"
          ]
        },
        {
          "name": "selected_dealer", 
          "values": [
            "99213450"
          ]
        }
      ], 
      ...
    }
  ],
  "paging": {
    "cursors": {
      "before": "OTc2Nz3M8MTgyMzU1NDMy", 
      "after": "OTcxNjcyOTg8ANTI4NzE4"
    }
  }
}

Lettura delle risposte del disclaimer personalizzato

field_data non contiene le risposte per le caselle opzionali del disclaimer personalizzato che l'utente deve spuntare. Per recuperare le risposte, utilizza il campo custom_disclaimer_responses.

curl -X GET \
"https://graph.facebook.com/<API_VERSION>/<LEADGEN_ID>?
fields=custom_disclaimer_responses"

Risposta:

{
  "custom_disclaimer_responses": [
    {
      "checkbox_key": "optional_1",
      "is_checked": "1"
    },
    {
      "checkbox_key": "optional_2",
      "is_checked": ""
    }
  ],
  "id": "1231231231"
}

Come filtrare i contatti

Questo esempio filtra i contatti in base alle indicazioni temporali. Le indicazioni temporali devono essere in formato Unix.

curl -X GET \ -d 'filtering=[ { "field": "time_created", "operator": "GREATER_THAN", "value": 1731610726 } ]' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v21.0/{adgroup-id}/leads
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const Ad = bizSdk.Ad; const Lead = bizSdk.Lead; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_GROUP_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'filtering' : [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}], }; const leadss = (new Ad(id)).getLeads( fields, params ); logApiCallResult('leadss api call complete.', leadss);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\Ad; use FacebookAds\Object\Lead; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_GROUP_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'filtering' => array(array('field' => 'time_created','operator' => 'GREATER_THAN','value' => 1721709809)), ); echo json_encode((new Ad($id))->getLeads( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.ad import Ad from facebook_business.adobjects.lead import Lead from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_GROUP_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'filtering': [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}], } print Ad(id).get_leads( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_GROUP_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new Ad(id, context).getLeads() .setParam(\"filtering\", \"[{\\"field\\":\\"time_created\\",\\"operator\\":\\"GREATER_THAN\\",\\"value\\":1721709809}]\") .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_GROUP_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad = FacebookAds::Ad.get(id) leadss = ad.leads({ fields: { }, filtering: [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}], })

operator ha uno dei valori seguenti.

OperatoreSignificato

LESS_THAN

Filtri per valori inferiori all'indicazione temporale.

GREATER_THAN

Filtri per valori superiori all'indicazione temporale.

GREATER_THAN_OR_EQUAL

Filtri per valori superiori o uguali all'indicazione temporale.

Creazione di token

Se il modulo ha ID del campo personalizzati, i campi e i valori restituiti saranno campi e valori specifici.

Risorse