Messaggi di marketing

Questo documento spiega come richiedere l'autorizzazione a una persona per l'invio di messaggi di marketing, fornisce informazioni sui requisiti specifici e le limitazioni per l'invio delle richieste e su come creare e inviare le richieste di autorizzazioni per i messaggi di marketing.

Panoramica

I messaggi di marketing consentono a una Pagina Facebook o a un account Instagram per professionisti di inviare messaggi al di fuori della finestra dei messaggi standard per le persone che ti hanno concesso l'autorizzazione. I messaggi di marketing ti consentono di instaurare relazioni con persone interessate a te o alla tua azienda.

Messaggi di marketing è una nuova funzione opzionale del piano Premium, che intendiamo offrire a pagamento in futuro. Attualmente alle aziende viene fatturata la funzione che consente di inviare messaggi tramite l'API WhatsApp Business, con un modello di prezzi definito tenendo conto del feedback dei clienti. Informeremo clienti e partner delle eventuali modifiche al periodo di accesso gratuito con ampio anticipo.

Requisiti

• Devi rispettare tutte le Normative per gli sviluppatori applicabili quando utilizzi i messaggi di marketing o altre funzioni della Piattaforma Messenger.

• Puoi richiedere a un utente di attivare i messaggi di marketing una sola volta all'interno della finestra dei messaggi standard. L'azione di un utente di attivare i messaggi di marketing non apre la finestra dei messaggi standard.

• La tua app e/o l'esperienza di messaggi che offri non devono ricevere un numero eccessivo di feedback negativi dagli utenti. Le funzionalità di messaggistica possono essere sottoposte a restrizioni o rimosse se riscontriamo che l'esperienza di messaggi della tua app ha ricevuto troppi feedback negativi dagli utenti.

• Non puoi usare i messaggi di marketing né le richieste di attivazione come una forma di spam a danno degli utenti. Ciò include l'invio di richieste di attivazione duplicate ad alta frequenza agli stessi utenti e altre forme di spam definite nelle nostre Normative per gli sviluppatori.

• Devi rispettare le limitazioni imposte per la funzionalità della Piattaforma Messenger e dei messaggi di marketing al fine di rispettare l'ambito del servizio che ti offriamo.

Limitazioni

• Puoi inviare una sola richiesta di iscrizione per persona a settimana con lo stesso titolo specifico. Ciò include il valore predefinito di "Aggiornamenti e promozioni".
• Non inviare richieste di iscrizione duplicate a una persona. Una richiesta di iscrizione duplicata viene definita come avente lo stesso title per le notifiche di una Pagina Facebook o gli stessi title e image_url per le notifiche di un account Instagram per professionisti.
• Puoi inviare le richieste di iscrizione solo durante la finestra dei messaggi standard.
• Se una persona attiva i messaggi di marketing, questa azione non apre una finestra dei messaggi standard.
• Puoi vedere solo se una persona ha attivato l'iscrizione per ricevere i messaggi di marketing, ma non gli stati per le richieste di iscrizione in sospeso.
• Se una persona ha scelto di interrompere la ricezione dei messaggi di marketing, le tue notifiche non verranno più consegnate a quella persona e riceverai un messaggio di errore.
• Una persona può bloccare, silenziare o segnalare i tuoi messaggi.
• Per i messaggi di marketing inviati da un account Instagram per professionisti, in genere, possono essere inviate fino a un massimo di 10 richieste di iscrizione per titoli diversi per utente in un periodo di 7 giorni. Si applica un sottolimite pari a 5 richieste di iscrizione al giorno. Tuttavia, valuta se gli utenti potrebbero trovare la richiesta di iscrizione pertinente e utile prima di inviarla.

Questi requisiti e limitazioni sono soggetti a variazioni dato che desideriamo offrire sempre la migliore esperienza a utenti e aziende.

Best practice

Dovresti inviare alle persone messaggi di marketing pertinenti e utili per creare un'esperienza utente di alta qualità seguendo queste indicazioni:

• La tua richiesta di iscrizione, comprensiva di titolo e immagine, include i tipi di messaggi di marketing che gli utenti possono aspettarsi di ricevere, ad esempio aggiornamenti sugli ordini, prodotti consigliati oppure determinate offerte.

• Quando invi più di una richiesta di iscrizione a un utente, ognuna di queste deve indicare chiaramente i diversi tipi specifici di messaggi di marketing che l'utente può aspettarsi di ricevere.

I messaggi di marketing devono essere pertinenti e adattati ai casi d'uso che un utente potrebbe trovare utili.

Gli utenti possono fornire feedback sulla tua esperienza di messaggi, ad esempio bloccandoli. Ciò potrebbe comportare limitazioni al tuo utilizzo dei messaggi di marketing. Dovresti controllare regolarmente le tue richieste di iscrizione e i messaggi di marketing per vedere se rispettano le best practice indicate in precedenza.

Frequenza dei messaggi

Si applica ai token dei messaggi di notifica creati prima del 2 febbraio 2023.

• Dopo che una persona ha fornito il consenso esplicito, puoi inviarle un messaggio con frequenza giornaliera, settimanale o mensile a seconda della preferenza che ha espresso durante l'attivazione.

Richiesta di autorizzazione per l'invio di messaggi di marketing

Una persona deve concedere l'autorizzazione, ovvero fornire il consenso esplicito, per ricevere messaggi di marketing dalla tua Pagina Facebook o dal tuo account Instagram per professionisti. La Piattaforma Messenger ti offre diversi modi per ottenere il consenso esplicito. Puoi creare le richieste di iscrizione nelle seguenti esperienze di messaggi:

• Inserzioni che rimandano a Messenger : quando una persona clicca sull'inserzione
• Plug-in della casella di spunta : quando una persona clicca sulla casella di spunta di un modulo e lo invia
• m.me Link : quando una persona clicca sul link m.me sul tuo sito web, nelle e-mail, nei post sui social media e altro ancora
• Risposte private : quando una persona pubblica un post di una persona che ha visitato la Pagina o commenta la Pagina Facebook della tua azienda
• Codici QR : quando una persona scansiona il tuo codice QR su superfici digitali e stampate (supportato dai link m.me)
• Plug-in Invia a Messenger : quando una persona avvia una conversazione utilizzando una lista di pulsanti di call to action o testo predefiniti

Esempio di richiesta di iscrizione

Per inviare una richiesta di iscrizione ai messaggi di marketing, invia una richiesta POST all'endpoint notification_messages con il tipo di modello di messaggio impostato su /PAGE-ID/messages. L'ID della Pagina corrisponde all'ID della Pagina Facebook o della Pagina Facebook collegata all'account Instagram per professionisti.

Nota: il parametro title è obbligatorio per i messaggi di marketing che contengono un carosello dalla tua Pagina Facebook o dall' account Instagram per professionisti .

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "id":"PSID-OR-IGSID"
  },
  "message":{
    "attachment":{
      "type":"template", 
      "payload":{
         "template_type":"notification_messages", 
         "notification_messages_timezone": "UTC",
         "title":"TITLE",
         "image_url":"IMAGE-URL",
         "payload": "ADDITIONAL-WEBHOOK-INFORMATION",
      }
    }
  }
}' "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages?access_token=PAGE-ACCESS-TOKEN"

Se l'invio procede correttamente, l'app riceve la seguente risposta JSON che include gli ID del destinatario e del messaggio.

{ 
        "recipient": {
          "id":"PSID-OR-IGSID",
          "message_id":"MESSAGE-ID",
}

Riferimento all'oggetto Message Attachment

Un oggetto JSON messageattachment deve essere incluso nella richiesta POST all'endpoint /PAGE-ID/messages per una richiesta di iscrizione ai messaggi di marketing.

Token dei messaggi di notifica

Quando una persona attiva l'iscrizione, la tua azienda riceverà una notifica webhook messaging_optin con un token dei messaggi di notifica e informazioni come il titolo del messaggio e il fuso orario della persona che ha attivato l'iscrizione. Il token dei messaggi di notifica ti consente di inviare i messaggi di marketing alla persona.

Notifica webhook di iscrizione

{
  "sender": {
    "id": "PSID",
  },
  "recipient": {
    "id": "PAGE-ID",
  },
  "timestamp": "TIMESTAMP",
  "optin": {
    "type": "notification_messages", 
      "payload": "ADDITIONAL-WEBHOOK-INFORMATION",
      "notification_messages_token": "NOTIFICATION-MESSAGES-TOKEN", 
      "notification_messages_timezone": "TIMEZONE-ID",
      "token_expiry_timestamp": "TIMESTAMP",
      "user_token_status": "TOKEN-STATUS"  
      "notification_messages_status": "MESSAGE-STATUS", 
      "title": "TITLE-FOR-THE-NOTIFICATION"
    }
}

Le date di scadenza del token saranno estese per le persone che scelgono di continuare a ricevere i messaggi di marketing. Le persone possono disattivarli in qualsiasi momento.

Iscrizione ai messaggi di follow-up

Quando una persona fornisce il consenso esplicito alla ricezione dei messaggi di marketing, puoi inviare fino a tre messaggi di follow-up. Questi messaggi di follow-up devono essere inviati entro due minuti dal primo messaggio di follow-up. Il secondo e il terzo messaggio di follow-up non possono superare i 250 caratteri. Questi messaggi di follow-up possono essere inviati al di fuori della finestra dei messaggi standard di 24 ore.

Per inviare un messaggio di follow-up, invia una richiesta POST all'endpoint /PAGE-ID/messages con l'oggetto recipient che contiene il token dei messaggi di notifica e l'oggetto message che contiene il testo dei messaggi di follow-up. La sintassi è la stessa per le richieste API per tutti e tre i messaggi di follow-up.

Esempio di richiesta

curl -X POST -H "Content-Type: application/json" -d 
    '{ 
        "recipient":{ 
            "notification_messages_token":"NOTIFICATION-MESSAGE-TOKEN" 
        }, 
        "message":{ 
            "text":FOLLOWUP-MESSAGE-TEXT-HERE, 
        } 
    }' 
"https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages?access_token=TOKEN"

Acquisizione di una lista di token

Per ottenere una lista di tutti i token dei messaggi di notifica validi invia una richiesta GET all'endpoint /PAGE-ID/notification_message_tokens.

Esempio di richiesta

curl -i -X GET "https://graph.facebook.com/API-VERSION-NUMBER/PAGE-ID/notification_message_tokens
    ?access_token=PAGE-ACCESS-TOKEN"

Per impostazione predefinita, viene restituita una lista di massimo 25 token ordinati in base all'orario aggiornato. Per ottenere maggiori informazioni, puoi aggiungere il parametro limit. Al momento, possono essere restituiti massimo 100 token. Puoi utilizzare il parametro after per la paginazione, tuttavia, il parametro before non è disponibile.

In caso di azione eseguita correttamente, la tua app riceverà la seguente risposta JSON che include il token, l'ID del destinatario (ID di Instagram o ID per singola Pagina), l'ora di creazione del token, il titolo della notifica e l'ora di invio del successivo messaggio di marketing a quel destinatario specifico.

{
  "data":[
    {
      "notification_messages_token":"NOTIFICATION-MESSAGE-TOKEN-ID-1",
      "recipient_id":"PAGE-OR-INSTAGRAM-SCOPED-ID-1",
      "notification_messages_reoptin":"RE-OPT-IN-STATUS",
      "creation_timestamp":TIMESTAMP,
      "token_expiry_timestamp":UNIX-TIMESTAMP-EXPIRATION-DATE,
      "user_token_status":"TOKEN-STATUS",
      "topic_title":"NOTIFICATION-TITLE",
      "notification_messages_timezone":"TIMEZONE-ID",
      "next_eligible_time": TIMESTAMP
    },
...
    {
      "notification_messages_token":"NOTIFICATION-MESSAGE-TOKEN-ID-25",
      "recipient_id":"PAGE-OR-INSTAGRAM-SCOPED-ID-25",
      "notification_messages_reoptin":"RE-OPT-IN-STATUS",
      "creation_timestamp":TIMESTAMP,
      "token_expiry_timestamp":UNIX-TIMESTAMP-EXPIRATION-DATE,
      "user_token_status":"TOKEN-STATUS",
      "topic_title":"NOTIFICATION-TITLE",
      "notification_messages_timezone":"TIMEZONE-ID",
      "next_eligible_time": TIMESTAMP
    }
  ],
  "paging":{"cursors":{"before":"QVFIU...","after":"QVFIU..."},"next":"https:\/\/graph.facebook.com\/LATEST-API-VERSION\/PAGE-ID\/notification_message_tokens?access_token=PAGE-ACCESS-TOKEN"}
}

Informazioni sul token

Anche se ti consigliamo di utilizzare il webhook messaging_optin per raccogliere informazioni sui messaggi di marketing, puoi inviare una richiesta GET all'endpoint del token in cui questo è allegato a notification_messages_, notification_messages_NOTIFICATION-MESSAGES-TOKEN, per acquisire informazioni sul token.

Esempio di richiesta

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/notification_messages_NOTIFICATION-MESSAGES-TOKEN
    ?access_token=PAGE-ACCESS-TOKEN"

In caso di azione eseguita correttamente la tua app riceverà la seguente risposta JSON che include il token dei messaggi di notifica, l'ID della persona che riceve il messaggio e altre informazioni sul token. Utilizzerai il token dei messaggi di notifica e l'ID del destinatario per inviare i messaggi di marketing.

{
  "notification_messages_token": "NOTIFICATION-MESSAGES-TOKEN",
  "recipient_id": "PAGE-OR-INSTAGRAM-SCOPED-ID",
  "creation_timestamp": "TIMESTAMP",
  "token_expiry_timestamp": "TIMESTAMP",
  "user_token_status": "REFRESHED",
  "notification_messages_reoptin": "ENABLED",
  "notification_messages_timezone": "TIMEZONE-ID"
  "next_eligible_time": TIMESTAMP
}

Queste chiamate API saranno conteggiate per il rate limiting della tua app.

Invio di un messaggio di marketing

Prima di iniziare

Ecco cosa ti servirà:

• Il token dei messaggi di notifica della persona che ha attivato l'iscrizione per la ricezione delle notifiche
• L'ID della Pagina Facebook della tua azienda
• Un token d'accesso della Pagina richiesto da un utente che può eseguire l'attività MESSAGING sulla Pagina
• L'autorizzazione pages_messaging, usando Facebook Login
• Tutte le risorse da includere nel messaggio di marketing
• L'iscrizione webhook messaging_referrals per la tua app

Per inviare un messaggio di marketing a una persona, invia una richiesta POST all'endpoint /PAGE-ID/messages con il valore NOTIFICATION-MESSAGES-TOKEN del destinatario e le informazioni sul messaggio nel relativo allegato.

Limitazioni

• Puoi inviare un solo messaggio al giorno per ogni token dei messaggi di notifica. Se stai inviando più messaggi, assicurati di posticipare i messaggi successivi di 24 ore o riceverai un errore (tale condizione non si applica all'Iscrizione ai messaggi di follow-up).

Consigli

• Consigliamo vivamente di fare riferimento al fuso orario del destinatario durante l'invio di messaggi di marketing per garantire che i messaggi vengano ricevuti all'ora adeguata per il destinatario.

Esempio di richiesta

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "notification_messages_token": "NOTIFICATION-MESSAGES-TOKEN"
  },
  "message":{
    "attachment":{
      "type":"template",
      "payload":{
        "template_type":"generic",
        "elements":[
           {
            "title":"Welcome!",
            "image_url":"https://raw.githubusercontent.com/fbsamples/original-coast-clothing/main/public/styles/male-work.jpg",
            "subtitle":"We have the right hat for everyone.",
            "default_action": {
              "type": "web_url",
              "url": "https://www.originalcoastclothing.com/",
              "webview_height_ratio": "tall"
            },
            "buttons":[
              {
                "type":"web_url",
                "url":"https://www.originalcoastclothing.com/",
                "title":"View Website"
              },{
                "type":"postback",
                "title":"Start Chatting",
                "payload":"ADDITIONAL-WEBHOOK-INFORMATION"
              }              
            ]      
          }
        ]
      }
    }
  }
}' "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages?access_token=PAGE-ACCESS-TOKEN"

Se l'azione viene eseguita correttamente, l'app riceve la seguente risposta:

{ 
  "recipient": "PAGE-OR-INSTAGRAM-SCOPED-ID",
  "message_id": "MESSAGE-ID"      
}

Test dei messaggi di marketing

Puoi testare i messaggi di marketing in qualsiasi momento.

Prima di iniziare

Ecco cosa ti servirà:

• Una persona, il tester, per ricevere la notifica. Questa persona deve avere un ruolo nell'app.

Iscrizioni di prova

Puoi testare i messaggi di marketing in qualsiasi momento seguendo questi passaggi.

• Passaggio 1: invia al tester un messaggio con il modello di iscrizione ai messaggi di marketing.
• Passaggio 2: assicurati che il tester clicchi sul pulsante di attivazione, come Ricevi messaggi con vendite con il 50% di sconto, nella conversazione.
• Passaggio 3: invia il primo messaggio di marketing al tuo tester.
• Passaggio 4: invia un altro messaggio di marketing immediatamente dopo il primo con il parametro developer_action impostato su ENABLE_FOLLOWUP_MESSAGE.
• Passaggio 5: invia un altro messaggio di marketing al tester; si tratta del tuo messaggio di prova.

Esempio di richiesta

curl -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/notification_messages_dev_support
    ?recipient={
        "notification_messages_token": "NOTIFICATION-MESSAGES-TOKEN"
    }
    &developer_action=ENABLE_FOLLOWUP_MESSAGE
    &access_token=PAGE-ACCESS-TOKEN"

In caso di azione eseguita correttamente, la tua app riceverà la seguente risposta JSON che contiene success impostato su true.

{ "success": true }

Per testare i rinnovi delle iscrizioni, ripeti i passaggi con il parametro developer_action impostato su SEND_RE_OPTIN descritto nel Passaggio 4.

Passaggi successivi

• Notifica webhook relativa all'iscrizione ai messaggi
• Visita la panoramica sui tipi di messaggi per scoprire i diversi tipi di messaggi che puoi inviare.

Altri contenuti da consultare

• Riferimento sui messaggi della Pagina per ulteriori informazioni sui campi disponibili per i messaggi ricorrenti
• Una lista dei fusi orari disponibili
• Codici di errore per la Piattaforma Messenger