Plugin de bate-papo (beta)

O plugin de bate-papo permite integrar sua experiência do Messenger diretamente no seu site. Isso permite que seus clientes interajam com sua empresa a qualquer momento com a mesma experiência personalizada e avançada que eles têm no Messenger.

O plugin de bate-papo carrega automaticamente o histórico do bate-papo recente entre a pessoa e a sua empresa. Isso significa que as interações recentes com sua empresa no messenger.com, no aplicativo Messenger ou no plugin de bate-papo no seu site ficarão visíveis. Isso ajuda a criar uma experiência única para os clientes e permite que você continue a conversa mesmo depois que o cliente sai da sua página da web. Não é necessário capturar as informações dos clientes para acompanhar, basta usar a mesma conversa no Messenger.

Conteúdo

Suporte de recursos

Suporte do navegador

O plugin de bate-papo é compatível com os navegadores para celular e de desktop mais modernos e populares, exceto os navegadores no aplicativo do Messenger e o Internet Explorer.

Suporte de modelo e tipo de mensagem

Atualmente, o plugin de bate-papo oferece suporte aos seguintes tipos de mensagem e modelos de mensagem estruturada:

Recurso com suporte

Mensagem de texto

Sim

Vídeo/imagem/áudio/GIF

Sim

Modelo de botão/genérico

Sim (suportado em tipos limitados de botão)

Postback

Botão URL

Botão Chamar

Botão Comprar

Botão Compartilhar

Botão Entrar

Botão Sair

Botão de jogo

Modelo de Open Graph/mídia/lista

Não

Respostas rápidas

Sim (suportado em tipos limitados de resposta rápida)

Resposta rápida de texto

Resposta rápida de número de telefone de usuário

Resposta rápida de email de usuário

Resposta rápida de localização

Menu persistente

Sim

Ações do remetente

Sim

Como incluir o SDK

Para usar o plugin de bate-papo, você deve incluir uma versão do SDK do JavaScript para Facebook que contenha o SDK do Bate-papo com Clientes na página em que o plugin será exibido.

Para obter instruções sobre como incluir o SDK, consulte SDK do Bate-papo com Clientes.

Localização e internacionalização

Para obter vantagens da internacionalização, incluindo a tradução automática de idiomas, você precisa configurar a localidade do SDK para a mesma do seu site. Especificamente, você precisa alterar en_US para um código de localidade com suporte ao iniciar o SDK.

Para mais informações, consulte Localização com Plugins Sociais e SDK do JavaScript.

Controles dinâmicos do plugin

Nós também fornecemos APIs que permitem que você controle de modo dinâmico determinados comportamentos do plugin, como abrir e fechar o diálogo.

Para obter mais informações, consulte o SDK do Bate-papo com Clientes.

Como configurar o plugin

Para incluir o plugin de bate-papo em sua página da web, você pode usar a ferramenta de configuração ou configurar seguindo as etapas do desenvolvedor.

Opção 1: Como usar a ferramenta de configuração

Para administradores da Página, as configurações da Página também fornecem uma ferramenta de configuração fácil para personalizar o plugin de bate-papo. Para usar a ferramenta de configuração, faça o seguinte:

  1. Vá para Configurações da Página > Mensagens
  2. Na seção 'Adicionar Messenger ao seu site', clque no botão 'Começar a usar'.

A ferramenta de configuração fornece uma interface do usuário simples para personalizar a mensagem de saudação, a cor do tema, o tempo de resposta exibido e a configuração dos domínios da lista de liberação do plugin.

No final, a ferramenta de configuração gera automaticamente os trechos de código que você poderá copiar/colar para incluir o plug-in de bate-papo em sua página da web.

Opção 2: Configurar seguindo as etapas do desenvolvedor

Para incluir o plugin de bate-papo em sua página da web, faça o seguinte:

  1. Inclua o domínio do seu site na lista de liberação

    Por motivos de segurança, o plugin será gerado somente quando for carregado em um domínio que você tiver incluído na lista de liberação. Consulte a whitelisted_domainsreferência para saber mais sobre como incluir seu domínio na lista de liberação programaticamente.

    Nome do domínio e HTTPS obrigatórios

    Os domínios devem atender aos seguintes requisitos para serem incluídos na lista de liberação:

    • Exibidos com HTTPS

    • Use um nome de domínio totalmente qualificado, como https://www.messenger.com/. Não há suporte para endereços IP e localhost em listas de liberação.

    As empresas cuja experiência do Messenger é fornecida por um provedor de serviços não terão acesso ao gerador de token da página nas configurações do aplicativo, uma vez que elas não possuem o aplicativo do Facebook. Nesse caso, você pode adicionar ou remover domínios da lista de liberação por meio das configurações da Página. Para inserir um domínio na lista de liberação, faça o seguinte:

    1. Clique em Configurações no alto da Página
    2. Clique em Plataforma do Messenger à esquerda
    3. Edite os domínios da lista de liberação da sua página na seção Domínios da lista de liberação
  2. Inclua o plugin na sua página da Web

    Para adicionar o plugin à sua página da web, inclua um div com os seguintes atributos no HTML:
    <div class="fb-customerchat"
     page_id="<PAGE_ID>">
    </div>

    Por padrão, o diálogo de saudação será exibido no desktop e em dispositivos móveis. Para personalizar o comportamento do diálogo de saudação, você pode usar os atributos greeting_dialog_display e "greeting_dialog_delay".

    Posicionamento recomendado

    É altamente recomendável não alterar a posição padrão do plugin de bate-papo no canto inferior direito da sua página.

    Para obter uma lista completa dos atributos, confira a Referência do plugin de bate-papo.

  3. Opcional. Controle o evento messaging_postbacks para novas conversas

    Se uma nova conversa for iniciada por meio do plugin, e seu bot tiver configurado o botão Começar, enviaremos um evento de webhookmessaging_postbacks ao seu webhook quando o usuário clicar no botão Começar.

    Se o atributo ref for definido na inclusão do plugin de bate-papo, ele será incluído no evento de postback.

    Alteração urgente (5 de maio de 2020)

    O evento de webhook messaging_postback da Graph API v7.0+ do plugin de bate-papo não retornará o campo sender.id. Ele retornará um novo campo sender.user_ref. Essa alteração entrará em vigor para todas as versões mais antigas da Graph API a partir de 2 de novembro de 2020.

    Novo evento de webhook do postback de mensagem (Graph API v7.0+ e todas as versões da Graph API a partir de 2 de novembro de 2020)

    {
      "sender":{
        "user_ref":"<USER_REF>" // new field
      },
      "recipient":{
        "id":"<PAGE_ID>"
      },
      "timestamp":1458692752478,
      "postback":{
        "title": "<TITLE_FOR_THE_CTA>",  
        "payload": "<USER_DEFINED_PAYLOAD>",
        "referral": {
          "ref": "<USER_DEFINED_REFERRAL_PARAM>",
          "source": "<SHORTLINK>",
          "type": "OPEN_THREAD",
        }
      }
    }    

    Evento de webhook antigo do postback de mensagem (Graph API <= v6.0 - disponível até 2 de novembro de 2020)

    {
      "sender":{
        "id":"<PSID>"
      },
      "recipient":{
        "id":"<PAGE_ID>"
      },
      "timestamp":1458692752478,
      "postback":{
        "title": "<TITLE_FOR_THE_CTA>",  
        "payload": "<USER_DEFINED_PAYLOAD>",
        "referral": {
          "ref": "<USER_DEFINED_REFERRAL_PARAM>",
          "source": "<SHORTLINK>",
          "type": "OPEN_THREAD",
        }
      }
    }    

    Com o novo formato de webhook messaging_postback, você aproveitará o USER_REF para enviar mensagens. O USER_REF não funcionará na API de perfil do usuário. Você obterá o PSID quando o usuário responder e poderá usá-lo na API de envio e na API de perfil do usuário.

    API de envio com o USER_REF

    curl -X POST -H "Content-Type: application/json" -d '{
      "messaging_type": "<MESSAGING_TYPE>",
      "recipient": {
        "user_ref": "<USER_REF>"
      },
      "message": {
        "text": "hello, world!"
      }
    }' "https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    
  4. Opcional. Controle o evento messaging_referrals para conversas existentes

    Para conversas existentes, se o atributo ref estiver definido na inclusão do plugin de bate-papo, um evento de webhook messaging_referrals será enviado para o seu webhook quando a conversa for continuada por meio do plugin.

    O ref pode ser qualquer cadeia de caracteres e pode ser usado para vários fins. Por exemplo, você pode usá-lo para verificar quais clientes entraram em contato com sua empresa por meio do plugin.

    Alteração urgente (5 de maio de 2020)

    O evento de webhook messaging_referrals da Graph API v7.0+ do plugin de bate-papo não retornará o campo sender.id. Ele retornará um novo campo sender.user_ref. Essa alteração entrará em vigor para todas as versões mais antigas da Graph API a partir de 2 de novembro de 2020.

    Novo evento de webhook da referência (Graph API v7.0+ e todas as versões da Graph API a partir de 2 de novembro de 2020)

    {
        "object": "page",
        "entry": [
            {
                "id": "<PAGE_ID>",
                "time": 1559598385735,
                "messaging": [
                    {
                        "recipient": {
                            "id": "<PAGE_ID>"
                        },
                        "timestamp": 1559598385735,
                        "sender": {
                            "user_ref":"<USER_REF>" // new field
                        },
                        "referral": {
                            "ref": "<DEVELOPER_DEFINED_REFERRAL>",
                            "source": "CUSTOMER_CHAT_PLUGIN",
                            "type": "OPEN_THREAD",
                            "referer_uri": "<REFERRAL_URI>"
                        }
                    }
                ]
            }
        ]
    }
    

    Evento de webhook anterior da referência (Graph API <= v6.0 - disponível até 2 de novembro de 2020)

    {
        "object": "page",
        "entry": [
            {
                "id": "<PAGE_ID>",
                "time": 1559598385735,
                "messaging": [
                    {
                        "recipient": {
                            "id": "<PAGE_ID>"
                        },
                        "timestamp": 1559598385735,
                        "sender": {
                            "id": "<USER_PSID>"
                        },
                        "referral": {
                            "ref": "<DEVELOPER_DEFINED_REFERRAL>",
                            "source": "CUSTOMER_CHAT_PLUGIN",
                            "type": "OPEN_THREAD",
                            "referer_uri": "<REFERRAL_URI>"
                        }
                    }
                ]
            }
        ]
    }
    

    Com o novo formato de webhook messaging_referrals, você aproveitará o USER_REF para enviar mensagens. O USER_REF não funcionará na API de perfil do usuário. Você obterá o PSID quando o usuário responder e poderá usá-lo na API de envio e na API de perfil do usuário.

    API de envio com o USER_REF

    curl -X POST -H "Content-Type: application/json" -d '{
      "messaging_type": "<MESSAGING_TYPE>",
      "recipient": {
        "user_ref": "<USER_REF>"
      },
      "message": {
        "text": "hello, world!"
      }
    }' "https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    

Como personalizar o plugin

O plugin de bate-papo tem suporte para as seguintes personalizações. Todas as personalizações são definidas como um atributo quando o plugin é incluído na sua página da web:

Atributo Descrição

theme_color

Opcional. A cor para usar como um tema para o plugin, incluindo a cor do plano de fundo do ícone do plugin de bate-papo e a cor do plano de fundo de qualquer mensagem enviada pelos usuários. É compatível com qualquer código de cor hexadecimal precedido por um símbolo de número (por exemplo, #0084FF), exceto branco. Recomendamos que você escolha uma cor que tenha um alto contraste com o branco.

logged_in_greeting

Opcional. O texto de saudação que será exibido se o usuário estiver conectado com o Facebook. Máximo de 80 caracteres.

logged_out_greeting

Opcional. O texto de saudação que será exibido se o usuário não estiver conectado com o Facebook. Máximo de 80 caracteres.

greeting_dialog_display

Opcional. Define como o diálogo de saudação será exibido. Os valores a seguir têm suporte:


  • show: o diálogo de saudação é exibido e permanece aberto no desktop e em plataformas móveis depois do tempo em segundos definido pelo atributo greeting_dialog_delay.
  • hide: o diálogo de saudação ficará oculto até que o usuário clique no plugin no desktop e em plataformas móveis.
  • fade: o diálogo de saudação é exibido brevemente depois do tempo em segundos definido pelo atributo greeting_dialog_delay e, em seguida, desaparece e fica oculto no desktop.

A configuração do plugin é definida para o padrão show no desktop e em dispositivos móveis. Confira a seção Comportamento de armazenamento em cache a seguir para saber mais.

greeting_dialog_delay

Opcional. Define o tempo de atraso em segundos antes da exibição do diálogo de saudação depois do carregamento do plugin. Isso pode ser usado para personalização quando você desejar que o diálogo de saudação seja exibido. Se greeting_dialog_delay estiver configurado, mas greeting_dialog_display não estiver, o atraso do diálogo de saudação será mantido em desktops, mas não haverá atraso em dispositivos móveis.

ref

Opcional. Você poderá passar um parâmetro ref opcional se desejar incluir contexto adicional para ser passado de volta para o evento de webhook. Ele pode ser usado para muitas finalidades, como rastrear em qual página o usuário iniciou a conversa, direcionar o usuário para um conteúdo ou recursos específicos disponíveis dentro do bot, ou associar um usuário do Messenger a uma sessão ou conta no site.

Como desativar o menu persistente

Poderá haver casos onde seja preferível desativar o menu persistente de seu bot no plug-in de bate-papo. Para fazer isso, adicione "disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"] quando definir seu menu persistente:

Exemplo de carga da API do Perfil do Messenger

{
  "persistent_menu":[
    {
      "locale":"default",
      "disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"],
      "composer_input_disabled": false,      
      "call_to_actions":[
        {
          "title":"My Account",
          "type":"postback",
          "payload":"PAYBILL_PAYLOAD"
        }
      ]
    }
  ]
}

Modo convidado

Algumas páginas de negócios têm acesso ao “Modo convidado” para o plugin de bate-papo, permitindo que as pessoas iniciem um bate-papo com as empresas por meio do plugin de bate-papo sem precisar fazer login em uma conta do Facebook. Estes “usuários convidados” são contas temporárias que podem receber mensagens quando o usuário está no seu site. “Bate-papos de convidados” serão encerrados quando o usuário decidir encerrar a conversa no menu Mais ou 24 horas depois do início da conversa, o que vier primeiro. O convidado aparecerá como “Convidado” seguido de uma cadeia de caracteres curta.

Se a empresa tentar enviar uma mensagem para este usuário convidado quando as contas do convidado forem encerradas, ela receberá uma mensagem de erro: “Esta pessoa não pode receber mensagens: A pessoa não está recebendo mensagens suas no momento.” A transcrição desses “bate-papos de convidados” permanecerá no navegador do usuário convidado por até 24 horas. Porém, as empresas manterão uma cópia da conversa/transcrição na sua caixa de entrada mesmo depois que o bate-papo expirar até que seja excluída.

Desde o dia 16/06, os desenvolvedores cujas páginas tenham acesso ao "modo convidado" verão as seguintes mudanças na implementação de plugins:

  • Webhook de referências de mensagem: facilitamos a identificação de um usuário convidado. O Webhook messaging_referrals incluirá a sinalização is_guest_user=true para indicar um usuário convidado.
  • Webhook de encerramento: quando um usuário convidado escolher encerrar a conversa, enviaremos uma notificação de webhook para informar a empresa de que o convidado não está mais disponível. Haverá falha no envio de mensagens futuras para o ID do convidado.

As empresas têm o seguinte controle com relação ao modo convidado:

  • Ativar/desativar o modo convidado nas Configurações da Página → Mensagem → Adicionar o Messenger ao seu site → Começar → Desativar o modo convidado
  • Bloquear um usuário convidado na Caixa de Entrada da Página do Facebook
  • Envie este formulário para denunciar um usuário convidado que infringiu regras mais de uma vez

Webhook de referências de mensagem

O Webhook messaging_referrals de usuários convidados agora inclui o sinalizador is_guest_user=true, indicando que se trata do Webhook de um usuário convidado.

{
  "sender":{
    "id":"<GUEST_ID>"
  },
  "recipient":{
    "id":"<PAGE_ID>>"
  },
  "timestamp":1458692752478,
  "referral": {
     "ref": "<REF_DATA_PASSED_IN_CODE>",
     "source": "CUSTOMER_CHAT_PLUGIN",
     "type": "OPEN_THREAD",
     "referer_uri": "<WEBSITE_URL>",
     "is_guest_user": "true"
  }
}

Webhook de encerramento

Quando um usuário convidado encerrar a conversa no Plugin de bate-papo, enviaremos um webhook para informar os desenvolvedores de que o GUEST_ID não é mais válido e não receberá mais mensagens. Os desenvolvedores devem garantir que seu ambiente bloqueie o recebimento de mensagens futuras desta conversa.

{
  "sender":{
    "id":"<GUEST_ID>"
  },
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp":1458692752478,
  "referral": {
     "ref": "<REF_DATA_PASSED_IN_CODE>",
     "source": "CUSTOMER_CHAT_PLUGIN",
     "type": "END_CHAT",
     "referer_uri": "<WEBSITE_URL>"
     "is_guest_user": "true" #this is optional
  }
}

API de perfil do usuário

Informações de localidade, gênero e fuso horário não estão disponíveis para usuários convidados.

curl -X GET "https://graph.facebook.com/v7.0/<GUEST_ID>?fields=first_name,last_name,profile_pic,is_guest_user"
  
{
    "first_name": "Guest",
    "last_name": "1234",
    "profile_pic": "https://example.com/profile.jpg",
    "is_guest_user": "true"
}

API da Conversa

O parâmetro user_id da API da Conversa também aceitará GUEST_ID para permitir que desenvolvedores obtenham o histórico da conversa de um usuário convidado.

curl -i -X GET \
 "https://graph.facebook.com/v7.0/me/conversations?user_id=<PSID/GUEST_ID>"

API de Envio

O envio do parâmetro id da API da Conversa também aceitará GUEST_ID para permitir que desenvolvedores obtenham o histórico da conversa de um usuário convidado.

curl -X POST -H "Content-Type: application/json" -d '{
  "messaging_type": "<MESSAGING_TYPE>",
  "recipient": {
    "id": "<GUEST_ID>"
  },
  "message": {
    "text": "hello, world!"
  }
}' "https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Login do usuário

Se o usuário estiver conectado à conta do Facebook, poderá começar a conversar com seu bot imediatamente. Se ele não estiver conectado, uma mensagem de boas-vindas padrão será exibida e ele será solicitado a entrar ou a criar uma nova conta do Facebook.

Páginas que utilizam restrições de país/idade

Se sua Página tiver restrições de país ou idade definidas nas configurações da Página, o plugin de bate-papo não será exibido aos usuários que não estiverem conectados à conta do Facebook quando visitarem seu site.

Comportamento de armazenamento em cache

O estado do diálogo de saudação é armazenado em cache no navegador e persiste mesmo quando o navegador é fechado e aberto novamente. O plugin sempre voltará para o último estado em que o usuário manteve o plugin com base no cache do navegador (com a exceção dos navegadores Safari 12+ e Firefox).

Por padrão, para cada nova solicitação do plugin, o diálogo de saudação será exibido no desktop e em dispositivos móveis. Os usuários podem clicar no botão Fechar para minimizar o diálogo, ou você pode substituir o padrão de solicitação por suas próprias preferências de exibição.

Como detectar a origem da mensagem

Em alguns casos, poderá ser necessário determinar se um usuário está entrando em contato com sua empresa usando o plugin de bate-papo. Para habilitar isso, a Plataforma do Messenger incluirá a propriedade "source": "customer_chat_plugin" na carga de todas as mensagens enviadas do plugin.

Exemplo de evento de webhook de mensagens

{
    "object": "page",
    "entry": [
        {
            "id": "<PAGE_ID>",
            "time": 1559598624359,
            "messaging": [
                {
                    "sender": {
                        "id": "<USER_PSID>"
                    },
                    "recipient": {
                        "id": "<PAGE_ID>"
                    },
                    "timestamp": 1559598623749,
                    "message": {
                        "tags": {
                            "source": "customer_chat_plugin"
                        },
                        "mid": "nhEqs_THGoYyAhpK93uNCrIfLZD...",
                        "text": "hello, from customer chat!"
                    }
                }
            ]
        }
    ]
}

Plugin do Wordpress

Para facilitar a integração do plugin de bate-papo nos sites do Wordpress, oferecemos o plugin oficial de bate-papo do cliente do Messenger para Wordpress em wordpress.org.

Dicas de solução de problemas

Se você estiver com problemas para que o plugin renderize corretamente, experimente as dicas abaixo:

  • Se você vir um erro de console como "Recusa em exibir *** em uma estrutura porque um anterior viola a seguinte diretriz da Política de Segurança de Conteúdo: ***", verifique se o domínio da página em que o plugin está sendo processado foi liberado. Certifique-se de não ter definido o cabeçalho Referrer-Policy como no-referrer.
  • O complemento do Contêiner do Facebook para Firefox impede que o plugin apareça. Remova o complemento se desejar que o plugin seja renderizado.
  • Os navegadores privados do Firefox (versão 63 e superior) e os navegadores móveis do Firefox bloqueiam o rastreamento de conteúdo por padrão, o que impede a renderização do plugin. Desative o bloqueio de conteúdo (clique no escudo cinza na barra de pesquisa) para ver o renderizador do plugin.