Plug-in per la chat

Questo documento mostra come aggiungere in modo programmatico il plug-in per la chat all'esperienza su Messenger sul sito web.

Se desideri utilizzare Meta Business Suite per aggiungere il plug-in per la chat alla tua pagina web (scelta consigliata), consulta il Centro assistenza per le aziende di Meta per ulteriori informazioni.

Come funziona

Quando installi l'SDK di Facebook per JavaScript sulla tua pagina web, questa visualizzerà il plug-in per la chat. Per impostazione predefinita, la finestra di dialogo del saluto verrà visualizzata su computer e mobile e una persona può cliccare sul pulsante Chiudi per ridurla a icona. Puoi personalizzare diversi elementi del plug-in: il saluto, l'aspetto, come il colore, e l'esperienza di messaggistica, come menu e risposte rapide. Lo stato della finestra di dialogo viene memorizzato nella cache, ingrandito o ridotto a icona e persiste da una sessione all'altra.

Accessi

Se la persona ha effettuato l'accesso a Facebook, il plug-in mostrerà i pulsanti "Continua come [NOME]" e "Continua come ospite". Invece, se la persona non ha effettuato l'accesso a Facebook, il plug-in mostrerà i pulsanti "Accedi a Messenger" e "Continua come ospite".

Notifiche webhook

Quando una persona clicca sul plug-in per avviare o continuare una chat con l'azienda, viene inviata una notifica webhook al server contenente i seguenti dati:

• Informazioni sulla persona, come ID della singola Pagina (PSID) o ID di riferimento dell'utente
• Identificazione del plug-in per la chat come origine del messaggio
• Informazioni relative al reindirizzamento incluse nella notifica

Se hai implementato la schermata di benvenuto nel plug-in e la persona clicca sul pulsante Inizia per avviare una conversazione con la tua azienda, viene inviata una notifica webhook messaging_postbacks al server. La tua azienda può quindi utilizzare l'ID di riferimento per inviare messaggi alla persona entro la finestra dei messaggi standard di 24 ore.

Conversazioni esistenti

Se la persona ha una conversazione esistente con la tua azienda, la cronologia delle chat verrà caricata automaticamente nel plug-in. Quando la persona continua la conversazione, invia un messaggio, clicca su un pulsante o esegue un'altra azione che hai implementato nella conversazione, viene inviata una notifica webhook messaging al server e una notifica webhook messaging_referral se desideri includere le informazioni relative all'invito. La tua azienda può quindi utilizzare il PSID per inviare messaggi alla persona entro la finestra dei messaggi standard di 24 ore.

Tipi di messaggi supportati dal plug-in per la chat

Il plug-in non supporta:

Prima di iniziare

Ecco cosa ti servirà:

• L'autorizzazione pages_messaging
• Un token d'accesso della Pagina richiesto da una persona che può eseguire l'attività MODERATE sulla Pagina Facebook
• L'app collegata alla Pagina Facebook per cui hai attivato l'iscrizione per i campi dei webhook messaging, messaging_postbacks e messaging_referrals
• Il dominio per il sito web aggiunto alla lista di elementi consentiti utilizzando l' API Messenger Profile oppure Meta Business Suite

In relazione al tuo utilizzo del plug-in per la chat, si applicano le Condizioni per gli strumenti business di Meta.

Limitazioni

• Il sito web deve essere attivo o aggiunto alla lista di elementi consentiti prima che il plug-in per la chat possa essere implementato correttamente.
• Se nelle impostazioni della Pagina Facebook della tua azienda sono configurate delle restrizioni relative all'età o al Paese, il plug-in per la chat non verrà visualizzato per le persone che non hanno effettuato l'accesso al proprio account Facebook quando visitano il tuo sito web.
• La finestra di dialogo del saluto non è memorizzata nella cache per i browser Safari 12+ e Firefox.

Aggiunta del plug-in per la chat

Passaggio 1: aggiunta dell'SDK

Aggiungi l'SDK di Facebook per JavaScript a ogni pagina del tuo sito web in cui desideri visualizzare il plug-in.

<!-- Messenger Chat Plugin Code --> <div id="fb-root"></div> <div id="fb-customer-chat" class="fb-customerchat"></div> <script> var chatbox = document.getElementById('fb-customer-chat'); chatbox.setAttribute("page_id", "PAGE-ID"); chatbox.setAttribute("attribution", "biz_inbox"); </script> <script> window.fbAsyncInit = function() { FB.init({ xfbml : true, version : 'API-VERSION' }); }; (function(d, s, id) { var js, fjs = d.getElementsByTagName(s)[0]; if (d.getElementById(id)) return; js = d.createElement(s); js.id = id; js.src = 'https://connect.facebook.net/en_US/sdk/xfbml.customerchat.js'; fjs.parentNode.insertBefore(js, fjs); }(document, 'script', 'facebook-jssdk')); </script> 

Passaggio 2: personalizzazione del plug-in

Utilizzo dell'API

Invia una richiesta POST all'endpoint /PAGE-ID/chat_plugin per personalizzare il saluto, il colore, l'icona e altri elementi del plug-in.

Esempio di richiesta

curl -i -X POST "https://graph.facebook.com/v21.0/PAGE-ID/chat_plugin
    ?welcome_screen_greeting:YOUR-WELCOME-TEXT
    &theme_color:553399
    &entry_point_icon:MESSENGER-ICON
    &entry_point_label:CHAT
    &access_token=PAGE-ACCESS-TOKEN"

Consulta il Riferimento per il plug-in per la chat per maggiori informazioni sui campi utilizzati per personalizzare il plug-in.

Utilizzo degli attributi HTML

Consigliamo di utilizzare questo metodo solo per le personalizzazioni non disponibili tramite lo strumento di configurazione delle impostazioni della Pagina o l'API.

Notifiche webhook

Quando una persona invia un messaggio alla tua azienda, viene inviata una notifica webhook al server.

Conversazioni esistenti

Viene inviata una notifica webhook messaging quando una persona invia un messaggio a una conversazione esistente con la tua azienda. La notifica include l'ID della singola Pagina della persona e il parametro source dell'oggetto tags impostato su customer_chat_plugin.

Notifica messaging

{
    "object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": 1559598624359,
            "messaging": [
                {
                    "sender": {
                        "id": "PSID"
                    },
                    "recipient": {
                        "id": "PAGE-ID"
                    },
                    "timestamp": 1559598623749,
                    "message": {
                        "tags": {
                            "source": "customer_chat_plugin"
                        },
                        "mid": "nhEqs_THGoYyAhpK93uNCrIfLZD...",
                        "text": "hello, from customer chat!"
                    }
                }
            ]
        }
    ]
}

Notifica messaging_referrals

Se imposti l'attributo ref per il plug-in per la chat, viene inviata una notifica del webhook messaging_referrals al server.

{
    "object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": 1559598385735,
            "messaging": [
                {
                    "recipient": {
                        "id": "PAGE-ID"
                    },
                    "timestamp": 1559598385735,
                    "sender": {
                        "user_ref":"USER-REFERENCE-ID"
                    },
                    "referral": {
                        "ref": "REF-PARAMETER-INFORMATION",
                        "source": "CUSTOMER_CHAT_PLUGIN",
                        "type": "OPEN_THREAD",
                        "referer_uri": "REFERRAL-URI"
                    }
                }
            ]
        }
    ]
}

Nuove conversazioni

Viene inviata una notifica del webhook messaging_postbacks quando una persona avvia una conversazione cliccando sul pulsante Inizia nella schermata di benvenuto del plug-in.

Notifica messaging_postbacks

{
    "object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": 1559598624359,
            "messaging": [
                {
                    "sender": {
                        "user_ref": "USER-REFERENCE-ID"
                    },
                    "recipient": {
                        "id": "PAGE-ID"
                    },
                    "timestamp": 1559598623749,
                    "postback":{
                        "title": "TITLE-FOR-THE-CTA",  
                        "payload": "PAYLOAD-DEFINED-BY-CTA",
                        "referral": {
                            "ref": "ADDITIONAL-INFORMATION",
                            "source": "CUSTOMER_CHAT_PLUGIN",
                            "type": "OPEN_THREAD",
                    }
                }
            ]
        }
    ]
}

Richieste di iscrizione ai messaggi di marketing

Visita la nostra Guida ai messaggi di marketing per la modalità di creazione delle richieste di iscrizione ai messaggi di marketing.

Limitazioni

Solo l'argomento Aggiornamenti e promozioni è supportato per i messaggi di marketing per il plug-in per la chat.

Notifica messaging_optins

Una notifica webhook messaging_optins viene inviata al server quando una persona fornisce il consenso esplicito per la ricezione di messaggi di marketing dalla tua azienda.

"object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": TIMESTAMP,
            "messaging": [
                {
                    "recipient": {
                        "id": "PAGE-ID"
                    },
                    "timestamp": TIMESTAMP,
                    "optin": {
                        "type": "notification_messages",
                        "payload": "empty_payload",
                        "notification_messages_token": "NOTIFICATION-MESSAGE-TOKEN",
                        "notification_messages_frequency": "MESSAGE-FREQUENCY",
                        "topic": "NOTIFICATION-MESSAGE-TOPIC",
                        "token_expiry_timestamp": EXPIRATION-DATE-TIMESTAMP,
                        "ref": "ADDITIONAL-INFORMATION",
                        "user_token_status": "NOT_REFRESHED",
                        "notification_messages_status": "RESUME_NOTIFICATIONS"
                    }
                }
            ]
        }
    ]
}

Puoi impostare il valore notification_messages_token sul valore dell'ID nell'oggetto recipient per inviare messaggi di marketing a una persona.

Suggerimenti per la risoluzione dei problemi

• Impossibile visualizzare...

  • Assicurati che il tuo dominio sia stato aggiunto alla whitelist.
  • Assicurati che l'intestazione Referrer-Policy sia stata impostata in modo da inviare l'URL di reindirizzamento.

• Il plug-in per la chat non viene visualizzato su Firefox

  • Rimuovi il componente aggiuntivo Facebook Container per Firefox.
  • Per visualizzare il plug-in, disattiva il blocco dei contenuti (clicca sullo scudo grigio nella barra di ricerca).

Passaggi successivi

• Invio di una risposta
• Invio di messaggi di marketing

Altri contenuti da consultare

• Disabilitazione del menu always-on
• SDK di Facebook per JavaScript
• Modalità ospite: consente agli utenti di iniziare una conversazione senza aver effettuato l'accesso a Facebook.
• Rompighiaccio: consentono agli utenti di iniziare una conversazione con un'azienda partendo da una lista di domande frequenti.
• Menu always-on: consente agli utenti di scoprire e accedere con maggiore facilità alle tue funzionalità nel corso della conversazione.