SDK de conversas

O widget de chat ao vivo do HubSpot permite conversar com clientes e leads no seu próprio site. Com o SDK widget de chat, você pode fornecer uma experiência mais ajustada aos visitantes com a personalização do comportamento do widget de chat.

Caso de uso: o SDK de widget de chat pode ser usado para personalizar quando e como o widget de chat do HubSpot aparece no seu site.

Em um nível alto, isso permite:

Introdução

A API está hospedada no objeto window.HubSpotConversations. Todos os métodos disponíveis podem ser acessados por meio desse objeto. O carregador de script do HubSpot (também chamado de código de rastreamento da HubSpot) na sua página criará esse objeto para você, mas pode não estar disponível imediatamente. Para adiar o acesso à API até que ela seja inicializada, você pode usar o assistente window.hsConversationsOnReady. Veja abaixo um exemplo simples:

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

Referência de SDK 

window.hsConversationsOnReady

Esse é um campo especial que você pode definir no objeto window que permite especificar o código a ser executado assim que o widget se tornar disponível. O uso dessa propriedade é opcional. Se for usado, esse campo deve ser definido para um conjunto de funções. Assim que a API tiver sido inicializada, ela verificará a existência desse conjunto e executará as funções em série. Por exemplo:

if (window.HubSpotConversations) { console.log('The api is ready already'); } else { window.hsConversationsOnReady = [ () => { console.log('Now the api is ready'); }, ]; }

hsConversationsSettings

Esse objeto permite oferecer algumas opções de configuração para o widget antes que ele inicie. O uso desse objeto é opcional.

Campos
Nome do campo Tipo de dados Padrão  Descrição

loadImmediately

 

 Booleano true Se o widget deve ser carregado implicitamente ou aguardar até que o método widget.load seja chamado
inlineEmbedSelector String "" Onde o widget deve ser incorporado na página. Se um seletor (por exemplo, #some-id) for fornecido, o widget será integrado ao seu nó DOM. Sempre será aberto até ser removido pelo widget.remove
enableWidgetCookieBanner Enum false Controla o comportamento do banner de cookies para todos os chats na página:

false - usa a configuração dos fluxos de chat (padrão)

true - permite banners de cookie quando o widget é carregado

ON_WIDGET_LOAD - igual a verdadeiro: permite banners de cookie quando o widget é carregado

ON_EXIT_INTENT - permite banners de cookies quando o usuário exibe a intenção de sair


Observe que esse campo usou um Booleano. Agora, pode acomodar os valores do Booleano original e os valores de enum atualizados.
disableAttachment Booleano false Se o botão do anexo do carregamento deve estar oculto no widget de chat.
disableInitialInputFocus Booleano false Determina se deve impedir automaticamente o foco no campo de entrada do widget depois que um widget incorporado em linha é inicialmente carregado em uma página.
 
window.hsConversationsSettings = { loadImmediately: false, inlineEmbedSelector: '#some-id', enableWidgetCookieBanner: true, disableAttachment: true }; window.hsConversationsOnReady = [ () => { window.HubSpotConversations.widget.load(); }, ];

Estilos integrados em linha

window.hsConversationsOnReady

Quando o widget está incorporado a um local especificado pelo cliente, vários elementos DOM são adicionados e podem ser estilizados para se adequar aos requisitos de personalização do cliente (por exemplo, altura, largura, borda). Observe que essa estrutura se aplica apenas se você usar a opção inlineEmbedSelector.

<�div� �id�=�"hubspot-conversations-inline-parent"�>
<�iframe� �id�=�"hubspot-conversations-inline-iframe"� />
</�div�>

Por exemplo, o widget de chat pode ter essa aparência por padrão:

livechat_before

 

Esse layout esmagado não é uma experiência ideal, então você pode personalizar o widget incluindo estilos como este:


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

livechat_after

Isso facilita muito a experiência do usuário. 

 

HubSpotConversations.widget

O objeto do widget contém um número de métodos que permitem lidar com o widget de chat na sua página.

widget.load

Carregue o widget pela primeira vez na página. Se o widget estiver carregado no momento, as chamadas subsequentes para esse método são no-ops.

Esse método é necessário apenas se você definir o sinalizador loadImmediately como false. Caso contrário, o widget será carregado automaticamente.

Observação: widget.load é limitado a uma chamada por segundo.

Parâmetros:
Nome do campo Tipo de dados? Padrão Descrição
widgetOpen Booleano false Se o widget deve carregar em um estado aberto
 
window.HubSpotConversations.widget.load(); /* ... */ // Force the widget to load in an open state window.HubSpotConversations.widget.load({ widgetOpen: true });

widget.refresh

Atualize e renderiza as informações do widget, dado a URL da página atual.

Se você colocar o widget de chat em um aplicativo de página única, esse método pode ser útil para atualizar o widget em alterações de rota. Isso permite especificar diferentes fluxos de chat em diferentes fluxos de página. Se widget.refresh for ativado em uma rota onde não há um fluxo de chat e o usuário não está envolvido em uma conversa, o widget será removido.

Observação: widget.refresh é limitado a uma chamada por segundo.

Parâmetros:
Nome do campo Tipo de dados? Padrão Descrição
openToNewThread Booleano false Se a criação de um thread será forçada

Para um exemplo de como usar o campo openToNewThread, consulte Abrir um fluxo de chat específico.

Exemplo:
window.HubSpotConversations.widget.refresh(); /* ... */ // Force the widget to open to a specific chat flow window.HubSpotConversations.widget.refresh({ openToNewThread: true });

Observação: widget.refresh não removerá a conversa existente que o visitante da página iniciou no widget.

 

widget.open

Abre o widget. Se o widget já estiver aberto ou não estiver carregado no momento, isso é um no-op.

Exemplo:
window.HubSpotConversations.widget.open();

widget.close

Fechar o widget. Se o widget já estiver fechado ou não estiver carregado no momento, isso não é um no-op.

Exemplo:
window.HubSpotConversations.widget.close();

widget.remove

Remove o widget da página. Se o widget não estiver presente na página, esse é um no-op. Para exibir o widget novamente, uma atualização completa de página terá que ocorrer ou  widget.load pode ser invocado.

Exemplo:
window.HubSpotConversations.widget.remove();

widget.status

Retorna um objeto contendo propriedades relacionadas ao status do widget.

Nome do campo Tipo de dados Padrão Descrição
loaded Booleano false Se o iframe do widget é carregado ou não.

 

Exemplo:
const status = window.HubSpotConversations.widget.status(); if (status.loaded) { window.HubSpotConversations.widget.refresh(); } else { window.HubSpotConversations.widget.load(); }

clear

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:

  • Consultar conversas históricas
  • Persistir o estado aberto do widget de chat em carregamentos de página
  • Persistir o estado aberto da mensagem de boas-vindas em carregamentos de página

O método clear pode ser usado para excluir esses cookies, retornando o widget ao seu estado padrão em cargas subsequentes.

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 este artigo da base de conhecimento.

Exemplo:
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.

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

Especificação do evento

O widget de chat emitirá vários eventos que você pode ouvir e responder ao seu ciclo de vida.

 

Eventos compatíveis

conversationStarted

Emitido quando uma nova conversa foi iniciada com sucesso.

Payload do evento
Nome do campo Tipo de dados Descrição
conversation Conversa Detalhes sobre a conversa que foi iniciada

 

Exemplo:
window.HubSpotConversations.on('conversationStarted', payload => { console.log( `Started conversation with id ${payload.conversation.conversationId}` ); });

conversationClosed

Emitido quando uma nova conversa foi fechada com sucesso.

Observação: esse evento dispara quando a conversa é marcada como fechada da caixa de entrada de conversas e não está relacionado ao usuário minimizar ou fechar o widget de chat.

 

Payload do evento
Nome do campo Tipo de dados Descrição
conversation Conversa Detalhes sobre a conversa que foi fechada

 

Exemplo:
window.HubSpotConversations.on('conversationClosed', payload => { console.log( `Conversation with id ${ payload.conversation.conversationId } has been closed!` ); });

unreadConversationCountChanged

Emitido quando o número de conversas no widget com qualquer de mensagens não lidas muda (aumento ou redução).

Payload do evento
Nome do campo Tipo de dados Descrição
unreadCount Número O novo total de conversas no widget com qualquer mensagem não lida

 

Exemplo:
window.HubSpotConversations.on('unreadConversationCountChanged', payload => { console.log(`New unread count is ${payload.unreadCount}!`); });

contactAssociated

Emitido quando o visitante está associado a um contato no CRM. 

Payload do evento
Nome do campo Tipo de dados Descrição
message String Uma mensagem de confirmação de que o visitante foi associado a um contato
Exemplo:
window.HubSpotConversations.on('contactAssociated', payload => { console.log(payload.message); });

userInteractedWithWidget

Emitido assim que o usuário interage com o widget (por exemplo, clicando no inicializador para abrir o widget, fechando a mensagem de boas-vindas inicial etc.)

Payload do evento
Nome do campo Tipo de dados Descrição
message String Uma mensagem de confirmação de que o usuário interagiu com o widget.
Exemplo:
window.HubSpotConversations.on(‘userInteractedWithWidget’, payload => { console.log(payload.message); });

widgetLoaded

Emitido quando o iframe do widget é carregado.

Payload do evento
Nome do campo Tipo de dados Descrição
message String Mensagem de confirmação de que o iframe do widget foi carregado.
Exemplo:
window.HubSpotConversations.on(‘widgetLoaded’, payload => { console.log(payload.message); });

quickReplyButtonClick

Emitido quando o usuário clica no botão de resposta rápida em uma conversa de bot

Payload do evento
Nome do campo Tipo de dados Descrição
value Array Inclui o conteúdo de texto do botão de resposta rápida que foi clicado.
Exemplo:
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 disponíveis para o usuário selecionar. 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" ] }
window.HubSpotConversations.on('quickReplyButtonClick', event => { console.log(`The text content of the clicked button is ${payload.value[0]}`); });

widgetClosed

Emitido quando o widget é fechado.

Carga útil do evento
Nome do campo Tipo de dados Descrição
message String Mensagem de confirmação de que o widget está fechado.
Exemplo:
window.HubSpotConversations.on('widgetClosed', event => { console.log(event); });

Registrar e remover ouvintes de eventos

on

Registra um ouvinte de eventos. Consulte tipos de evento compatíveis

Exemplo:
window.HubSpotConversations.on('conversationStarted', payload => { console.log(payload); });

off

Remove um ouvinte de eventos. Consulte tipos de evento compatíveis

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

Tipos de dados

O seguinte é uma referência aos tipos de dados comuns ao SDK do JavaScript.

Conversa
Nome do campo Tipo de dados Descrição
conversationId Número O id da conversa
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..