SDK de conversas

Para conversar com clientes e leads no seu site usando a caixa de entrada de conversas do HubSpot, você pode configurar um widget de chat ao vivo. Com o SDK de conversas, você pode fornecer uma experiência mais adaptada aos visitantes com a personalização do comportamento do widget de chat.

Em um nível alto, o SDK de conversas permite que você faça o seguinte:

Inicializando

A API está hospedada no objeto window.HubSpotConversations, que fornece acesso a todos os métodos disponíveis. O objeto é criado pelo código de acompanhamento do HubSpot, mas pode não estar disponível imediatamente no carregamento da página. Para adiar o acesso à API até que ela seja inicializada, você pode usar o assistente window.hsConversationsOnReady.

window.hsConversationsOnReady é um campo opcional que você pode definir no objeto window , que permite especificar o código a ser executado assim que o widget se tornar disponível. Este campo usa funções de matriz para serem executadas assim que a API for inicializada.

<script type="text/javascript"> function onConversationsAPIReady() { console.log(`HubSpot Conversations API: ${window.HubSpotConversations}`); } /* configure window.hsConversationsSettings if needed. */ window.hsConversationsSettings = {}; /* If external API methods are already available, use them. */ if (window.HubSpotConversations) { onConversationsAPIReady(); } else { /* Otherwise, callbacks can be added to the hsConversationsOnReady on the window object. These callbacks will be called once the external API has been initialized. */ window.hsConversationsOnReady = [onConversationsAPIReady]; } </script>

Configurar as definições de conversas

hsConversationsSettings

Este objeto opcional permite fornecer algumas opções de configuração ao widget antes que ele seja inicializado.

window.hsConversationsSettings = { loadImmediately: false, inlineEmbedSelector: '#some-id', enableWidgetCookieBanner: true, disableAttachment: true }; window.hsConversationsOnReady = [ () => { window.HubSpotConversations.widget.load(); }, ];
Field Type Default Description
loadImmediately Boolean true Whether the widget should implicitly load or wait until the widget.load method is called.
inlineEmbedSelector String "" Specify a selector  (#some-id) to embed the chat widget in a specific location on the page. Widget will be embedded inline within that DOM node and will remain open until it is removed with widget.remove. Learn more about styling embedded chat widgets.
enableWidgetCookieBanner Enumeration false Control behavior of the cookie banner for all chat widgets on the page. Options include:
  • false (default): uses the chat widget's settings.
  • true: presents cookie banners when the widget is loaded.
  • ON_WIDGET_LOAD: same as true.
  • ON_EXIT_INTENT: enable cookie banners when the user exhibits an exit intent.
disableAttachment Boolean false Whether to hide the upload attachment button in the chat widget.
disableInitialInputFocus Boolean false Whether to automatically prevent focusing on the widget's input field after an inline embedded widget is initially loaded.
avoidInlineStyles Boolean false When set to true, injects a link tag with externally hosted CSS instead of a direct dynamic insertion of a style tag.

Estilos integrados em linha

Quando o widget está incorporado em um local específico usando inlineEmbedSelector, vários elementos DOM são adicionados e podem ser estilizados (por exemplo, altura, largura, borda). 

Por exemplo, se você incorporar o widget de chat usando o seletor #some-id, ele será carregado com os seguintes contêineres e IDs:

<div id="some-id"> <div id="hubspot-conversations-inline-parent"> <iframe id="hubspot-conversations-inline-iframe"> <!-- rest of iframe content --> </iframe> </div> </div>

You can then customize the chat widget using those selectors, such as:

#hubspot-conversations-inline-iframe { width: 300px; height: 500px; border:none; }

livechat_after

 

Widget behavior

HubSpotConversations.widget

The widget object contains a number of methods that allow you to manipulate the chat widget on your page, including:

Below, learn more about each method.

widget.load

The widget.load method handles the initial load on the page. This method is only necessary if you set loadImmediately to false. Otherwise, the widget will load itself automatically.

This method is throttled to one call per second.

window.HubSpotConversations.widget.load(); /* ... */ // Force the widget to load in an open state window.HubSpotConversations.widget.load({ widgetOpen: true });
Campo Tipo Padrão Descrição
widgetOpen Booleano false Se o widget deve carregar em um estado aberto.

widget.refresh

O método widget.refresh trata da atualização e da nova renderização das informações do widget, de acordo com o URL da página atual. Esse método pode ser útil para widgets de chat incorporados em aplicativos de página única, quando você precisa atualizar o widget nas alterações de rota. Esse método também permite especificar diferentes widgets de chat em diferentes rotas da página.

Se você acionar widget.refresh em uma rota onde não haja widget de chat e o usuário não esteja envolvido em um chat, o widget será removido. Isso não removerá o widget quando houver um chat ativo no momento.

Este método é limitado a uma chamada por segundo.

window.HubSpotConversations.widget.refresh(); /* ... */ // Force the widget to open to a specific chat flow window.HubSpotConversations.widget.refresh({ openToNewThread: true });
Campo Tipo Padrão Descrição
openToNewThread Booleano false Se a criação de um thread será forçada. 

Exemplo

Com este método, você pode criar botões e links para abrir fluxos de chat específicos em uma página, adicionando parâmetros de consulta ao URL da página.

conversations-chat-widget-open-cropPor exemplo, você pode adicionar o seguinte código às suas páginas para gerar os botões:

<div class="chat-buttons"> <button onclick="window.history.pushState({}, 'talk_to_sales', '?sales_chat=true'); window.HubSpotConversations.widget.refresh({openToNewThread: true});">Talk to sales</button> <button onclick="window.history.pushState({}, 'talk_to_customer_support', '?cs_chat=true'); window.HubSpotConversations.widget.refresh({openToNewThread: true});">Talk to customer support</button> <button onclick="window.history.pushState({}, 'talk_to_the_ceo', '?ceo_chat=true'); window.HubSpotConversations.widget.refresh({openToNewThread: true});">Talk to the CEO</button> </div>

Em seguida, nas configurações de destino de cada chat, defina o chat para ser exibido quando o parâmetro de consulta corresponder ao que foi definido no código do botão.
conversations-target-rule

widget.open

O método widget.open abre o widget se ele ainda não estiver aberto ou carregado.

window.HubSpotConversations.widget.open();

widget.close

O método widget.close fecha o widget se ele ainda não estiver fechado.

window.HubSpotConversations.widget.close();

widget.remove

O método widget.remove remove o widget da página. Se o widget não estiver presente na página, este método não fará nada. O widget será exibido novamente na atualização da página ou se widget.load for acionado.

window.HubSpotConversations.widget.remove();

widget.status

O método widget.status devolve um objeto que contém propriedades relacionadas ao status atual do widget.

const status = window.HubSpotConversations.widget.status(); if (status.loaded) { window.HubSpotConversations.widget.refresh(); } else { window.HubSpotConversations.widget.load(); }
Campo Tipo Padrão Descrição
loaded Booleano false Se o iframe do widget foi carregado.

Limpar cookies de chat

O método clear exclui os cookies relacionados ao widget de chat e o retorna ao seu estado padrão no carregamento subsequente.

O widget de chat cria vários cookies para preservar seu estado em visitas do site e atualizar a página. O escopo desses cookies é criado no domínio da página que hospeda o widget e eles são usados para permitir os seguintes recursos:

  • Referência a conversas históricas.
  • Persistência do estado aberto do widget de chat em carregamentos de página.
  • Persistência do estado aberto da mensagem de boas-vindas em carregamentos de página.

Os cookies a seguir são apagados com este método:

  • messagesUtk
  • hs-messages-is-open
  • hs-messages-hide-welcome-message

Para obter mais informações sobre esses cookies, consulte a Central de Conhecimento da HubSpot.

window.HubSpotConversations.clear();

Além disso, você pode passar {resetWidget:true} para a função clear() para apagar todos os cookies relacionados a chat, remover o widget da página e criar uma instância do widget de chat.

window.HubSpotConversations.clear({resetWidget:true});

Eventos de chat

O widget de chat emitirá vários eventos que você pode ouvir e responder durante todo o seu ciclo de vida. Esses eventos incluem:

Para registar e remover ouvintes de eventos, use on e off, conforme mostrado abaixo.

const handleEvent = eventPayload => console.log(eventPayload); window.HubSpotConversations.on('conversationStarted', handleEvent); /* ... */ window.HubSpotConversations.off('conversationStarted', handleEvent);

Saiba mais sobre cada evento abaixo.

conversationStarted

O evento conversationStarted é acionado quando uma nova conversa é iniciada com sucesso.

window.HubSpotConversations.on('conversationStarted', payload => { console.log( `Started conversation with id ${payload.conversation.conversationId}` ); });
Campo Tipo Descrição
payload.conversation.conversationId Número O ID do thread da conversa que foi iniciada. Você pode usar esse ID ao fazer chamadas para a API de conversas.

conversationClosed

O evento conversationClosed é acionado quando uma nova conversa é marcada como fechada na caixa de entrada de conversas.

Os visitantes do site que minimizam ou fecham o widget de chat não acionam este evento. Para esse evento, use widgetClosed.

window.HubSpotConversations.on('conversationClosed', payload => { console.log( `Conversation with id ${ payload.conversation.conversationId } has been closed!` ); });
Campo Tipo Descrição
payload.conversation.conversationId Número O ID do thread da conversa que foi iniciada. Você pode usar esse ID ao fazer chamadas para a API de conversas.

userSelectedThread

O evento userSelectedThread é disparado ao criar um thread ou selecionar um thread existente. 

window.HubSpotConversations.on('userSelectedThread', payload => { console.log( `User selected thread with ID ${ payload.conversation.conversationId }!` ); });
Campo Tipo Descrição
payload.conversation.conversationId Número O ID do thread da conversa que foi iniciada. Você pode usar esse ID ao fazer chamadas para a API de conversas.

unreadConversationCountChanged

O evento unreadConversationCountChanged é acionado quando o número de conversas com mensagens não lidas aumenta ou diminui.

window.HubSpotConversations.on('unreadConversationCountChanged', payload => { console.log(`New unread count is ${payload.unreadCount}!`); });
Campo Tipo Descrição
unreadCount Número O número total de conversas com pelo menos uma mensagem não lida.

 

contactAssociated

O evento contactAssociated é acionado quando o visitante é associado a um contato no CRM.

window.HubSpotConversations.on('contactAssociated', payload => { console.log(payload.message); });
Campo Tipo Descrição
message String Uma mensagem de confirmação de que o visitante foi associado a um contato.

userInteractedWithWidget

O evento userInteractedWithWidget é acionado quando o visitante interage com o widget, como clicar para abrir o widget ou fechar a mensagem de boas-vindas inicial.

window.HubSpotConversations.on(‘userInteractedWithWidget’, payload => { console.log(payload.message); });
Campo Tipo Descrição
message String Uma mensagem de confirmação de que o visitante interagiu com o widget.

widgetLoaded

O evento widgetLoaded é acionado quando o iframe do widget é carregado.

window.HubSpotConversations.on(‘widgetLoaded’, payload => { console.log(payload.message); });
Campo Tipo Descrição
message String Uma mensagem de confirmação de que o iframe do widget foi carregado.

quickReplyButtonClick

O evento quickReplyButtonClick é acionado quando o visitante clica em uma resposta rápida de uma conversa de bot.

Campo Tipo Descrição
value Matriz Uma matriz com o texto da opção de resposta rápida que foi clicada.
window.HubSpotConversations.on('quickReplyButtonClick', event => { console.log(`The text content of the clicked button is ${payload.value[0]}`); });

quick-reply-options-in-bot-conversation

Na captura de tela do exemplo acima, o fluxo de chat do bot contém três opções de resposta rápida. Se o usuário selecionar Saiba mais, a carga útil resultante do evento será:

// Example event payload when a quick reply option is selected { "name": "QUICK_REPLIES", "multiSelect": false, "value": [ "Learn more" ] }

widgetClosed

O evento widgetClosed é acionado quando o visitante fecha o widget de chat.

window.HubSpotConversations.on('widgetClosed', event => { console.log(event); });
Campo Tipo Descrição
message String Uma mensagem de confirmação de que o visitante fechou o widget de chat.
Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..