Moduli per l'acquisizione di contatti per le inserzioni

Questo documento descrive come usare l'API Marketing per creare inserzioni per la generazione di contatti usando l'API Graph.

Per creare e pubblicare un'inserzione per acquisizione contatti seguirai questi passaggi:

1. Creazione di una campagna pubblicitaria
2. Creazione di un gruppo di inserzioni collegato alla campagna pubblicitaria
3. Creazione di un modulo per l'acquisizione di contatti
4. Creazione di una creatività dell'inserzione con il modulo per l'acquisizione di contatti
5. Associazione della campagna e della creatività per la creazione di un'inserzione
6. Pubblicazione dell'inserzione

Prima di iniziare

Ecco di cosa avrai bisogno:

• L'autorizzazione ads_management
• L'autorizzazione pages_manage_ads
• L'autorizzazione pages_read_engagement
• L'autorizzazione pages_show_list
• Un token d'accesso della Pagina da una persona che può eseguire l'attività ADVERTISE sulla Pagina

Passaggio 1: creazione di una campagna

Per creare una campagna pubblicitaria per le inserzioni per la generazione di contatti, invia una richiesta POST all'endpoint /act_AD_ACCOUNT_ID/campaigns con i seguenti parametri:

• access_token impostato sul tuo token d'accesso della Pagina
• buying_type impostato su AUCTION
• name impostato sul nome della tua campagna
• objective impostato su OUTCOME_LEADS
• special_ad_categories impostato su NONE o sulla tua categoria speciale di inserzioni
• status impostato su PAUSED

Esempio di richiesta

curl -X POST "https://graph.facebook.com/v21.0/act_AD_ACCOUNT_ID/campaigns" \
     -H "Content-Type: application/json" \
     -d '{
           "access_token":"YOUR_PAGE_ACCESS_TOKEN",
           "buying_type":"AUCTION",
           "name":"YOUR_LEADADS_CAMPAIGN_NAME",
           "objective":"OUTCOME_LEADS",
           "special_ad_categories":["NONE"],
           "status":"PAUSED"
         }'

In caso di azione eseguita correttamente, l'app riceverà un oggetto JSON contenente l'ID per la tua campagna. Questo ID verrà usato durante la creazione di un gruppo di inserzioni nel passaggio successivo.

{
  "id": "YOUR_CAMPAIGN_ID"
}

Consulta il riferimento per le campagne pubblicitarie per maggiori informazioni.

Passaggio 2: creazione di un gruppo di inserzioni

Per creare un gruppo di inserzioni, invia una richiesta POST all'endpoint act_ad_account_id/adsets in cui ad_account_id corrisponda all'ID per l'account pubblicitario di Meta. La richiesta deve includere:

• access_token impostato sul tuo token d'accesso della Pagina
• bid_amount impostato sull'importo massimo che desideri pagare
• billing_event impostato su IMPRESSIONS
• campaign_id impostato sull'ID per la tua campagna pubblicitaria del passaggio 1
• daily_budget impostato sull'importo che desideri spendere al giorno
• name impostato sul nome del tuo gruppo di inserzioni
• optimization_goal impostato su LEAD_GENERATION o QUALITY_LEAD
• destination_type impostato su ON_AD
• promoted_object impostato sull'ID della pagina Facebook della tua azienda
• status impostato su PAUSED

Nota: se hai configurato un'origine dei dati del CRM e scelto QUALITY_LEAD come obiettivo di ottimizzazione, puoi aggiungere pixel_id a promoted_object per una maggiore ottimizzazione a livello di qualità. Non è necessario indicare una pixel_rule insieme al pixel_id.

Esempio di richiesta

curl -X POST "https://graph.facebook.com/v21.0/act_AD_ACCOUNT_ID/adsets"
     -H "Content-Type: application/json" 
     -d '{
           "access_token":"YOUR_PAGE_ACCESS_TOKEN",
           "bid_amount":"YOUR_BID_AMOUNT",
           "billing_event":"IMPRESSIONS",
           "campaign_id":"YOUR_CAMPAIGN_ID",
           "daily_budget":"YOUR_DAILY_BUDGET",
           "name:"YOUR_LEADADS_ADSET_NAME",
           "optimization_goal":"LEAD_GENERATION",
           "destination_type":"ON_AD",
           "promoted_object":"YOUR_PAGE_ID",
           "status":"PAUSED"
         }'

In caso di azione eseguita correttamente, l'app riceve la seguente risposta JSON con l'ID per il gruppo di inserzioni.

{
  "id": "YOUR_ADSET_ID"
}

Consulta il riferimento per i gruppi di inserzioni per maggiori informazioni.

Passaggio 3: creazione di un modulo per l'acquisizione di contatti

Per creare un modulo, invia una richiesta POST all'endpoint /page_id/leadgen_forms con i seguenti parametri:

• access_token impostato sul tuo token d'accesso della Pagina
• name impostato sul nome del tuo modulo
• questions impostato su un array di oggetti che definiscono il tipo di domande e l'ordine in cui saranno visualizzate nel modulo usando il parametro key

  • una domanda personalizzata con il parametro label
  • una domanda personalizzata con il parametro options con un menu a discesa di risposte

Esempio di richiesta

curl -X POST "https://graph.facebook.com/v21.0/PAGE_ID/leadgen_forms" \
     -H "Content-Type: application/json" \
     -d '{
           "access_token": "YOUR_PAGE_ACCESS_TOKEN",
           "name": "YOUR_LEADADS_FORM_NAME",
           "questions": "[
               {"type":"FULL_NAME", "key": "question1"},
               {"type":"EMAIL", "key": "question2"},
               {"type":"PHONE", "key": "question3"},
               {"type":"CUSTOM", "key": "question4" "label": "Do you like rainbows?"}
               {"type":"CUSTOM", "key": "question5" "label": "What is your favorite color?", 
                   "options": [
                       {value: "Red", key: "key1"},
                       {value: "Green", key: "key2"},
                       {value: "Blue", key: "key2"},
                   ]}
           ]"
         }'

Moduli per le conversazioni su Messenger

I moduli che desideri utilizzare in un'inserzione in una conversazione su Messenger devono contenere i seguenti elementi:

• Il parametro questions.type può essere impostato solo su uno dei seguenti valori:

  CUSTOM EMAIL

  FIRST_NAME FULL_NAME

  LAST_NAME PHONE

  Se il modulo ha questions.type impostato su un qualsiasi valore diverso da quelli elencati, il modulo non sarà idoneo.

• Il parametro block_display_for_non_targeted_viewer deve essere impostato su false. Questo contrassegna il modulo come Open Sharing.

Richiesta di esempio di moduli per l'acquisizione di contatti su Messenger idonei

curl -X POST "https://graph.facebook.com/v21.0/PAGE_ID/leadgen_forms" \
     -H "Content-Type: application/json" \
     -d '{
           "access_token": "YOUR_PAGE_ACCESS_TOKEN"
           "block_display_for_non_targeted_viewer": "false"
           "name": "LeadAds Form for Messenger Conversation Name"
           "questions": "[
               {"type":"FULL_NAME", "key": "question1"},
               {"type":"EMAIL", "key": "question2"},
               {"type":"PHONE", "key": "question3"},
               {"type":"CUSTOM", "key": "question4" "label": "Do you like rainbows?"}
               {"type":"CUSTOM", "key": "question5" "label": "What is your favorite color?", 
                   "options": [
                       {value: "Red", key: "key1"},
                       {value: "Green", key: "key2"},
                       {value: "Blue", key: "key2"},
                   ]}
           ]"
         }'

Altri tipi di domande

In aggiunta ai tipi di domande tipici mostrati nella [sezione Creazione di un modulo per l'acquisizione di contatti]{#create-a-lead-form}, puoi aggiungere altri tipi di domande specializzati per i seguenti casi d'uso:

• Programmazione degli appuntamenti: le domande relative alla programmazione degli appuntamenti generano uno strumento di selezione di data e ora con una selezione limitata dell'orario e un messaggio di conferma sotto la domanda.
• Documento di identità nazionale o ufficiale: le domande relative ai documenti di identità nazionali generano una domanda basata sul Paese della persona e convalidano il formato del documento di identità inserito.
• Strumento di localizzazione dei punti vendita: le domande relative allo strumento di localizzazione dei punti vendita generano uno strumento di selezione dei punti vendita basato sul CAP o sul codice postale inserito dalla persona.

Programmazione degli appuntamenti

Le domande relative alla programmazione degli appuntamenti generano uno strumento di selezione di data e ora con una selezione limitata dell'orario e un messaggio di conferma sotto la domanda.

Per aggiungere una domanda relativa alla programmazione degli appuntamenti, aggiungi un oggetto question con il parametro type impostato su DATE_TIME. Se lo desideri, puoi anche aggiungere un messaggio di conferma nel parametro inline_context che sarà visualizzato direttamente sotto il campo delle domande per maggiore contesto, se necessario.

...
           "questions": "[
               ...
               {"type": "DATE_TIME", 
                "label": "Appointment time", 
                "inline_context": "We will verify and call you to confirm your appointment."
               },
...

Documento di identità nazionale

Le domande relative ai documenti di identità nazionali generano una domanda basata sul Paese della persona e convalidano il formato dell'ID immesso. Questa domanda può essere generata per i seguenti Paesi:

• Argentina – {"type": "ID_AR_DNI"}
• Brasile – ID_CPF
• Cile – ID_CL_RUT
• Colombia – ID_CO_CC
• Ecuador – ID_EC_CI
• Perù – ID_PE_DNI

Per aggiungere una domanda relativa ai documenti di identità nazionali, aggiungi un oggetto question con il parametro type impostato sul tipo di Paese della persona.

Limitazioni

• Puoi chiedere un solo documento di identità nazionale per modulo e puoi targetizzare le persone solo nel loro Paese. Ad esempio, se richiedi DNI per il Perù, il pubblico targetizzato deve essere limitato al Perù. Solo le inserzioni che corrispondono a questo criterio vengono approvate.
• Il processo di convalida verifica la validità del formato, non verifica l'effettiva appartenenza del documento di identità a una persona reale.

...
           "questions": "[
               ...
               {"type": "ID_AR_DNI"
               },
...

Strumento di localizzazione dei punti vendita

Le domande relative allo strumento di localizzazione dei punti vendita generano uno strumento di selezione dei punti vendita basato sul CAP o codice postale inserito dalla persona.

Dovrai configurare una struttura di Pagine dei punti vendita per usare questa domanda. Scopri come in Configurazione di una struttura di Pagine dei punti vendita su Facebook - Centro assistenza per le aziende di Meta

Per aggiungere una domanda relativa allo strumento di localizzazione dei punti vendita, aggiungi un oggetto question con il parametro type impostato su STORE_LOOKUP e il parametro context_provider_type su LOCATION_MANAGER.

...
           "questions": "[
               ...
               {"type": "STORE_LOOKUP", 
                "label": "Which store do you want to visit?", 
                "context_provider_type": "LOCATION_MANAGER"
               },
...

Impostazioni avanzate del modulo

Ottieni contatti di qualità superiore aggiungendo una o più delle seguenti impostazioni del modulo:

• Monitoraggio delle prestazioni del modulo per monitorare l'origine dei contatti
• Moduli "Intenzione più elevata" per aggiungere un passaggio di controllo e conferma nel flusso dei moduli
• Applicazione di filtri ai contatti organici per escludere i contatti organici

Aggiunta del monitoraggio delle prestazioni

Per aiutarti a monitorare l'origine dei contatti, aggiungi al tuo modulo il campo tracking_parameters, impostato su una lista di coppie chiave-valore di parametri che desideri monitorare. Questi parametri non vengono visualizzati nella tua inserzione, ma consentono a Meta di fornirti metadati relativi ai contatti generati da un modulo.

Esempio di richiesta

...
           "name": "YOUR_LEADADS_FORM_NAME",
           "tracking_parameters": {"your_tracking_parameter_name":"your_tracking_parameter_value"},
           "questions": "[
...

Aggiunta dell'impostazione "Intenzione più elevata"

Per impostazione predefinita, le inserzioni per acquisizione contatti vengono ottimizzate per il volume di contatti; tuttavia, puoi creare moduli che portano a contatti del tipo "Intenzione più elevata". Questi tipi di contatti possono essere rivolti a persone che potrebbero essere interessate a un prodotto o servizio specifico, come la prenotazione di un test drive presso una concessionaria. Questa impostazione del modulo aggiunge un passaggio al flusso di invio del modulo in cui una persona controlla e conferma le sue risposte prima dell'invio del modulo da parte di tale persona.

Per aggiungere questo flusso di conferma al tuo modulo, aggiungi il parametro is_optimized_for_quality impostato su true durante la creazione del modulo.

Esempio di richiesta

...
           "name": "YOUR_LEADADS_FORM_NAME",
           "is_optimized_for_quality": "true",
           "questions": "[
...

Esclusione dei contatti organici

Per escludere i contatti organici, aggiungi il parametro block_display_for_non_targeted_viewer a true durante la creazione del modulo.

Esempio di richiesta

...
           "name": "YOUR_LEADADS_FORM_NAME",
           "block_display_for_non_targeted_viewer": "true",
           "questions": "[
...

Esempio di risposta

In caso di azione eseguita correttamente, l'app riceverà una risposta JSON contenente l'ID per il tuo modulo da utilizzare durante la creazione dell'inserzione.

{
  "id": "leadgen_form_id",
}

Passaggio 4: creazione di una creatività dell'inserzione

Per creare una creatività dell'inserzione con un'immagine e il tuo modulo, invia una richiesta POST all'endpoint /act_AD_ACCOUNT_ID/adcreatives con i seguenti parametri:

• access_token impostato sul tuo token d'accesso della Pagina
• object_story_spec che includa un oggetto link_data con i seguenti parametri:

  • call_to_action impostato su un oggetto contenente type e value impostato sull'ID del modulo per l'acquisizione di contatti
  • description impostato sulla descrizione per la tua creatività
  • image_hash impostato sull'hash per un'immagine per la tua creatività dell'inserzione
  • message impostato sul testo per la tua creatività dell'inserzione
• page_id impostato sull'ID della Pagina Facebook

Nota: durante la creazione di link_data, il valore associato al campo link può essere solo https//fb.me/.

Il parametro link_data.call_to_action deve essere impostato solo su uno dei seguenti valori:

• APPLY_NOW
• DOWNLOAD
• GET_QUOTE
• LEARN_MORE
• SIGN_UP
• SUBSCRIBE

Esempio di richiesta

curl -X POST "https://graph.facebook.com/LATEST-API-VERSION/act_AD_ACCOUNT_ID/adcreatives" \
     -H "Content-Type: application/json" \
     -d '{
           "access_token":"YOUR_PAGE_ACCESS_TOKEN",
           "object_story_spec":{ 
             "link_data": { 
               "call_to_action": {
                 "type":"SIGN_UP",
                 "value":{
                   "lead_gen_form_id":"YOUR_FORM_ID"
                 }
               }, 
               "description": "YOUR_AD_CREATIVE_DESCRIPTION", 
               "image_hash": "YOUR_IMAGE_HASH", 
               "link": "http:\/\/fb.me\/", 
               "message": "YOUR_AD_CREATIVE_MESSAGE" 
             }, 
           "page_id": "YOUR_PAGE_ID" 
         }'
  

Con un carosello

Puoi creare un'inserzione per acquisizione contatti carosello usando la stessa object_story_spec, ma con un campo lead_gen_form_id aggiuntivo definito nel parametro child_attachments.

curl \
  -F 'object_story_spec={ 
    "page_id": "<PAGE_ID>", 
    "link_data": { 
      "message": "My description", 
      "link": "http:\/\/www.google.com", 
      "caption": "WWW.EXAMPLE.COM", 
      "child_attachments": [ 
        { 
          "link": "http:\/\/www.google.com", 
          "image_hash": "<IMAGE_HASH>", 
          "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}} 
        }, 
        { 
          "link": "http:\/\/www.google.com", 
          "image_hash": "<IMAGE_HASH>", 
          "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}} 
        }, 
        { 
          "link": "http:\/\/www.google.com", 
          "image_hash": "<IMAGE_HASH>", 
          "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}} 
        }, 
        { 
          "link": "http:\/\/www.google.com", 
          "image_hash": "<IMAGE_HASH>", 
          "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}} 
        } 
      ], 
      "multi_share_optimized": true, 
      "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}} 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/LATEST-API-VERSION/act_<AD_ACCOUNT_ID>/adcreatives

Con un video

Puoi anche usare un video al posto di una foto nelle creatività dell'inserzione per acquisizione contatti. Come prima cosa, carica il video nella tua libreria dei video delle inserzioni, quindi usalo nel parametro object_story_spec:

curl -X POST \
  -F 'object_story_spec={
       "page_id": "<PAGE_ID>",
       "video_data": {
         "link_description": "try it out",
         "image_url": "<IMAGE_URL>",
         "video_id": "<VIDEO_ID>",
         "call_to_action": {
           "type": "SIGN_UP",
           "value": {
             "link": "http://fb.me/",
             "lead_gen_form_id": "<FORM_ID>"
           }
         }
       }
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/adcreatives

Esempio di risposta della creatività dell'inserzione

In caso di azione eseguita correttamente, l'app riceve la seguente risposta JSON con l'ID per la creatività dell'inserzione.

{
  "id": "YOUR_AD_CREATIVE_ID"
}
      

Passaggio 5: creazione dell'inserzione

Per creare l'inserzione devi associare la creatività dell'inserzione e il gruppo di inserzioni. Per creare l'inserzione, invia una richiesta POST all'endpoint /act_AD_ACCOUNT_ID/ads. La richiesta deve includere:

• access_token impostato sul tuo token d'accesso della Pagina
• adset_id (del Passaggio 2)
• creative_id (del Passaggio 4)
• nome
• stato

Esempio di richiesta dell'inserzione con creatività

curl -X POST "https://graph.facebook.com/v21.0/act_AD_ACCOUNT_ID/ads"
     -H "Content-Type: application/json" 
     -d '{
           "access_token"="YOUR_PAGE_ACCESS_TOKEN",
           "name":"YOUR_LEADADS_AD_NAME",
           "adset_id"="YOUR_AD_SET_ID",
           "creative"={ "creative_id": "YOUR_AD_CREATIVE_ID" },
           "status"="PAUSED"
         }'

In caso di azione eseguita correttamente, l'app riceve la seguente risposta JSON con l'ID dell'inserzione.

{
  "id": "YOUR_AD_ID"
}

Passaggio 6: pubblicazione dell'inserzione

Verifica che l'inserzione esista in Gestione inserzioni . Clicca sul pulsante Controlla e pubblica nell'angolo in alto a destra. Seleziona la campagna, il gruppo di inserzioni per la campagna e l'inserzione.

Puoi pubblicare l'inserzione da Gestione inserzioni o utilizzando l'API. Per pubblicare utilizzando l'API, ripeti il Passaggio 4 con il parametro status impostato su ACTIVE.

L'inserzione verrà controllata da Meta e lo stato sarà PENDING_REVIEW. Dopo l'approvazione, lo stato sarà ACTIVE e l'inserzione verrà pubblicata.

Gestione dei moduli

Ottieni una lista dei tuoi moduli, domande specifiche dei moduli e archivia i moduli precedenti.

Acquisizione di una lista di moduli

Per ottenere una lista dei tuoi moduli per la generazione di contatti, invia una richiesta GET all'endpoint /page_id/leadgen_forms con i seguenti parametri:

• access_token impostato sul tuo token d'accesso della Pagina
• fields (facoltativo) impostato su una lista di campi separati da virgole per ottenere informazioni specifiche come il nome e l'ID del modulo

Esempio di richiesta

curl -X GET "https://graph.facebook.com/v21.0/PAGE_ID/leadgen_forms
    ?fields=name,id
    &access_token": "YOUR_PAGE_ACCESS_TOKEN"

In caso di azione eseguita correttamente, l'app riceverà una risposta JSON contenente una lista dei tuoi moduli. Puoi usare un ID del modulo per ricevere le domande per quel modulo o archiviarlo.

Acquisizione di una lista di moduli idonei per Messenger

Solo i moduli contenenti requisiti specifici sono idonei per essere inviati in una conversazione su Messenger.

Per ottenere una lista di moduli per l'acquisizione di contatti idonei invia una richiesta GET all'endpoint /page_id/leadgen_forms con i seguenti parametri:

• access_token impostato sul tuo token d'accesso della Pagina
• fields impostato su is_eligible_for_in_thread_forms

Esempio di richiesta

curl -X GET "https://graph.facebook.com/v21.0/PAGE_ID/leadgen_forms
    ?fields=is_eligible_for_in_thread_forms
    &access_token": "YOUR_PAGE_ACCESS_TOKEN"

In caso di azione eseguita correttamente, l'app riceverà una risposta JSON contenente una lista di ID per i moduli idonei.

{
  "data": [
    {
      "id": "eligible_form_1_id"
    },
    {
      "id": "eligible_form_2_id"
    }
  ],
...
}

Acquisizione di una lista di domande

Per ottenere una lista di domande per uno specifico modulo per la generazione di contatti, invia una richiesta GET all'endpoint /page_id/leadgen_form_id con i seguenti parametri:

• access_token impostato sul tuo token d'accesso della Pagina
• fields impostato su questions

Esempio di richiesta

curl -X GET "https://graph.facebook.com/v21.0/page_id/leadgen_form_id
    ?fields=questions
    &access_token=page_access_token"

In caso di azione eseguita correttamente, l'app riceverà una risposta JSON contenente una lista di domande.

Archiviazione di un modulo

Puoi solo archiviare i moduli per l'acquisizione di contatti perché l'eliminazione non è supportata. Una volta archiviato il modulo:

• Il modulo non comparirà (per impostazione predefinita) nella raccolta di moduli.
• Non puoi usare un modulo archiviato in un'inserzione, qualsiasi tentativo di farlo può generare un errore tramite l'API.
• I moduli archiviati non saranno disponibili durante la creazione delle inserzioni in CF o PE.

Per archiviare uno specifico modulo per la generazione di contatti, invia una richiesta POST all'endpoint /page_id/leadgen_form_id con i seguenti parametri:

• access_token impostato sul tuo token d'accesso della Pagina
• status impostato su ARCHIVED

Esempio di richiesta

curl -X GET "https://graph.facebook.com/v21.0/page_id/leadgen_form_id
    ?status=ARCHIVED
    &access_token=page_access_token"

In caso di azione eseguita correttamente, l'app riceverà una risposta JSON contenente un oggetto con success impostato su true.

Un modulo archiviato può essere riattivato inviando una richiesta con status impostato su ACTIVE.

Altri contenuti da consultare

Consulta le nostre altre guide per maggiori informazioni sui componenti trattati in questo documento.

Documentazione per gli sviluppatori dell'API Marketing

• Componenti dell'SDK della finestra di dialogo dell'interfaccia utente per la generazione di contatti
• Riferimento della Pagina, moduli per la generazione di contatti
• Specifiche di monitoraggio e conversione, Specifiche di monitoraggio personalizzate

Centro assistenza per le aziende di Meta

• Articolo del Centro assistenza sui contatti organici
• Articolo del Centro assistenza sul pulsante Condividi
• Articolo del Centro assistenza sui tipi di moduli per l'acquisizione di contatti
• Articolo del Centro assistenza sui moduli per l'acquisizione di contatti nelle inserzioni Canvas