Plugin de bate-papo

Este documento mostra como adicionar programaticamente o plugin de bate-papo à sua experiência do Messenger no site.

Se você quiser usar o Meta Business Suite para adicionar o plugin de bate-papo à sua página da web (recomendado), visite a Central de Ajuda da Meta para Empresas para mais informações.

Como funciona

Quando você instalar o SDK do Facebook para JavaScript na sua página da web, o plugin de bate-papo será renderizado na página. Por padrão, o diálogo de saudação será exibido no desktop e em dispositivos móveis. Para minimizá-lo, a pessoa poderá clicar no botão de fechar. É possível personalizar a saudação, a aparência (como a cor) e a experiência de envio de mensagens (como menus e respostas rápidas) do plugin. O estado da caixa de diálogo (maximizado ou minimizado) é armazenado em cache e persiste de sessão em sessão.

Logins

Se a pessoa estiver conectada ao Facebook, o plugin mostrará o botão "Continuar como [NOME]" e "Continuar como convidado". Se a pessoa não estiver conectada ao Facebook, o plugin mostrará o botão "Entrar no Messenger" e "Continuar como convidado".

Notificações de webhook

Quando uma pessoa clicar no plugin para iniciar ou continuar um bate-papo com a empresa, uma notificação de webhook será enviada para o seu servidor, contendo o seguinte:

• Informações sobre a pessoa, como IDs no escopo da página (PSID) ou IDs de referência do usuário
• Identifique a origem da mensagem como plugin de bate-papo
• Informações de referência incluídas na notificação

Se você implementou a tela de boas-vindas no plugin, e a pessoa clicar no botão Começar para iniciar uma conversa com a sua empresa, uma notificação de webhook messaging_postbacks será enviada ao seu servidor. Sua empresa poderá então usar o ID de referência do usuário para enviar mensagens à pessoa na janela-padrão de envio de 24 horas.

Conversas existentes

Se a pessoa tiver uma conversa existente com a empresa, o histórico de conversas será carregado automaticamente no plugin. Quando a pessoa continuar a conversa (seja enviando uma mensagem, clicando em um botão ou executando outra ação que você tenha implementado na conversa), uma notificação de webhook messaging será enviada ao seu servidor, ou uma notificação de webhook messaging_referral, se você incluir informações de referência. Sua empresa poderá então usar o PSID para enviar mensagens à pessoa na janela-padrão de envio de 24 horas.

Tipos de mensagem compatíveis com o plugin de bate-papo

O plugin não aceita:

Antes de começar

Você precisará:

• A permissão pages_messaging
• Um token de acesso à Página solicitado de uma pessoa que pode executar a tarefa MODERATE na sua Página do Facebook
• O app vinculado à sua Página do Facebook inscrito nos campos de webhooks messaging, messaging_postbacks e messaging_referrals
• O domínio do seu site adicionado à lista de permissão usando a API de Perfil do Messenger ou o Meta Business Suite

Os Termos das Ferramentas da Meta para Empresas se aplicam de acordo com o seu uso do plugin de bate-papo.

Limitações

• Seu site deve estar publicado ou na lista de permissões para que o plugin de bate-papo seja implementado com sucesso.
• Caso a Página do Facebook da sua empresa tenha restrições de país ou idade, o plugin de bate-papo não será exibido para pessoas que não estiverem conectadas à conta do Facebook ao visitarem o seu site.
• A caixa de diálogo de saudação não é armazenada em cache no Safari 12+ e nos navegadores Firefox.

Adicionar o plugin de bate-papo

Etapa 1: adicionar o SDK

Adicione o SDK do Facebook para JavaScript a cada página do seu site onde você quer renderizar o plugin.

<!-- 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> 

Etapa 2: personalizar o plugin

Com a API

Envie uma solicitação POST ao ponto de extremidade /PAGE-ID/chat_plugin para personalizar diversos aspectos do plugin, como a saudação, a cor, o ícone e muito mais.

Exemplo de solicitação

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"

Visite a referência do plugin de bate-papo para mais informações sobre os campos usados para personalizar o plugin.

Com atributos de HTML

Recomendamos usar este método para personalizações que não estão disponíveis pela ferramenta de configuração da Página ou pela API.

Notificações de webhook

Quando uma pessoa enviar uma mensagem à sua empresa, uma notificação webhook será enviada ao seu servidor.

Conversas existentes

Quando uma pessoa envia uma mensagem para uma conversa existente com a sua empresa, uma notificação de webhook messaging é enviada. A notificação incluirá o ID no escopo da Página da pessoa e o parâmetro source do objeto tags definido como customer_chat_plugin.

Notificação de envio de mensagem

{
    "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ção de referências de envio de mensagens

Se você definir o atributo ref para o plugin de bate-papo, uma notificação webhook messaging_referrals será enviada para o seu servidor.

{
    "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"
                    }
                }
            ]
        }
    ]
}

Conversas novas

Uma notificação webhook messaging_postbacks é enviada quando uma pessoa inicia uma conversa clicando no botão Começar, na tela de boas-vindas no plugin.

Notificação de postbacks de mensagens

{
    "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",
                    }
                }
            ]
        }
    ]
}

Solicitações de aceitação de mensagens de marketing

Acesse o nosso guia sobre notificações recorrentes e veja como criar solicitações para ativar mensagens de marketing.

Limitações

Somente o tópico Atualizações e promoções é compatível com as mensagens de marketing do plugin de bate-papo.

Notificação sobre a aceitação de mensagens

Uma notificação de webhook messaging_optins será enviada ao servidor quando uma pessoa aceitar receber mensagens de marketing da empresa.

"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"
                    }
                }
            ]
        }
    ]
}

Você pode definir o valor de notification_messages_token como o valor do ID no objeto recipient para enviar mensagens de marketing a uma pessoa.

Dicas de solução de problemas

• Exibição recusada...

  • Verifique se o seu domínio está na lista de liberação
  • Confira se o cabeçalho Referrer-Policy foi definido para que a URL do referenciador seja enviada.

• O plugin de bate-papo não está renderizando no Firefox

  • Remova o add-on Facebook Container do Firefox.
  • Desative o bloqueio de conteúdo (clique no escudo cinza na barra de pesquisa) para ver o renderizador do plugin.

Próximas etapas

• Enviar uma mensagem
• Marketing Messages

Veja também

• Desabilitar o menu persistente
• SDK do Facebook para JavaScript
• Guest Mode for Messenger: permita que os usuários iniciem conversas sem que precisem fazer login no Facebook.
• ice_breakers Reference: permita que os usuários usem uma lista de perguntas frequentes para iniciar uma conversa com empresa.
• Referência de persistent_menu: ajude as pessoas a descobrir e acessar com mais facilidade as suas funcionalidades durante a conversa.