SDK de conversaciones

Para chatear con clientes y leads en tu sitio web utilizando la bandeja de conversación de HubSpot, puedes configurar un widget de chat en vivo. Con el SDK de conversaciones, puedes proporcionarles una experiencia más personalizada a los visitantes adaptando el comportamiento del widget de chat.

En un nivel alto, el SDK de conversaciones te permite hacer lo siguiente:

Inicializar

La API se encuentra en el objeto window.HubSpotConversations, que proporciona acceso a todos los métodos disponibles. El objeto se crea con el código de seguimiento de HubSpot, pero es posible que no esté disponible inmediatamente al cargar la página. Para diferir el acceso a la API hasta que esté inicializado, puedes usar el ayudante window.hsConversationsOnReady.

window.hsConversationsOnReady es un campo opcional que puedes definir en el objeto window, el cual te permite especificar el código que se ejecutará tan pronto como el widget esté disponible. Este campo requiere que se ejecute una función de matriz una vez que se ha inicializado la API.

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

Establecer la configuración de tus conversaciones

hsConversationsSettings

Este objeto te permite proporcionar algunas opciones de configuración al widget antes de inicializar.

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.

Estilo de incrustación en línea

Cuando el widget se incrusta en una ubicación específica utilizando inlineEmbedSelector, se agregan varios elementos DOM y se pueden modificar (por ejemplo, altura, ancho, borde). 

Por ejemplo, si incrustas el widget de chat utilizando el selector # some-id, se cargará con los siguientes contenedores e ID:

<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 Predeterminado Descripción
widgetOpen Boolean false Si el widget debe cargarse en un estado abierto.

widget.refresh

El método widget.refresh maneja la actualización y la nueva representación de la información del widget, dada la URL de la página actual. Este método puede ser útil para widgets de chat integrados en aplicaciones de una sola página cuando necesites actualizar el widget en los cambios de ruta. Este método también te permite especificar diferentes widgets de chat en diferentes rutas de página.

Si llamas a widget.refresh en una ruta donde no hay widget de chat y el usuario no interactúa en un chat, se eliminará el widget. No eliminará el widget cuando haya un chat actualmente activo.

Este método se limita a una llamada por segundo.

window.HubSpotConversations.widget.refresh(); /* ... */ // Force the widget to open to a specific chat flow window.HubSpotConversations.widget.refresh({ openToNewThread: true });
Campo Tipo Predeterminado Descripción
openToNewThread Boolean false Ya sea para forzar la creación de un nuevo hilo. 

Ejemplo

Con este método, puedes crear botones y enlaces para abrir chatflows específicos en una página agregando parámetros de consulta a la URL de la página.

conversations-chat-widget-open-cropPor ejemplo, podrías agregar el siguiente código a tus páginas para generar los botones:

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

Luego, en la configuración objetivo de cada chat, establecerías que el chat se muestre cuando el parámetro de consulta coincida con el que has establecido en tu código de botón.
conversaciones-target-rule

widget.open

El método widget.open abre el widget si aún no está abierto o no está cargado actualmente.

window.HubSpotConversations.widget.open();

widget.close

El método widget.close cierra el widget si aún no está cerrado.

window.HubSpotConversations.widget.close();

widget.remove

El método widget.remove elimina el widget de la página. Si el widget no está presente en la página, este método no hace nada. El widget se mostrará de nuevo al actualizar la página o si se invoca widget.load.

window.HubSpotConversations.widget.remove();

widget.status

El método widget.status devuelve un objeto que contiene propiedades relacionadas con el estado actual del widget.

const status = window.HubSpotConversations.widget.status(); if (status.loaded) { window.HubSpotConversations.widget.refresh(); } else { window.HubSpotConversations.widget.load(); }
Campo Tipo Predeterminado Descripción
loaded Boolean false Ya sea que el widget iframe se haya cargado.

Borrar cookies del chat

El método clear elimina las cookies relacionadas con el widget de chat y lo devuelve a su estado predeterminado en la carga posterior.

El widget de chat crea varias cookies para preservar su estado durante las visitas al sitio y las actualizaciones de la página. Estas cookies se limitan al dominio de la página que aloja el widget y se utilizan para admitir las siguientes funciones:

  • Referenciar conversaciones históricas
  • Persistencia del estado abierto del widget de chat a través de cargas de página.
  • Persistencia del estado abierto del mensaje de bienvenida a través de cargas de página.

Las siguientes cookies se borran con este método:

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

Para obtener más información sobre estas cookies, consulta la Base de conocimientos de HubSpot.

window.HubSpotConversations.clear();

Además, puedes pasar {resetWidget:true} a la función clear() para borrar todas las cookies relacionadas con chat, eliminar el widget de la página y crear una nueva instancia del widget de chat.

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

Eventos de chat

El widget de chat emite varios eventos que puedes escuchar y responder a lo largo de su ciclo de vida. Estos eventos incluyen:

Para registrar y eliminar oyentes de eventos, los usarás on y off, como se muestra a continuación.

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

Obtén más información sobre cada evento a continuación.

conversationStarted

El evento conversationStarted se desencadena cuando se ha iniciado correctamente una nueva conversación.

window.HubSpotConversations.on('conversationStarted', payload => { console.log( `Started conversation with id ${payload.conversation.conversationId}` ); });
Campo Tipo Descripción
conversation ID de hilo El ID del hilo de la conversación que se inició. Puedes usar este ID al realizar llamadas a la API de conversaciones.

conversationClosed

El evento conversationClosed se desencadena cuando una nueva conversación se ha marcado como cerrada desde la bandeja de conversaciones.

Los visitantes del sitio que minimicen o cierren el widget de chat no desencadenarán este evento. Para ese evento, utiliza widgetClosed en su lugar.

window.HubSpotConversations.on('conversationClosed', payload => { console.log( `Conversation with id ${ payload.conversation.conversationId } has been closed!` ); });
Campo Tipo Descripción
conversation ID de hilo El ID del hilo de la conversación que se inició. Puedes usar este ID al realizar llamadas a la API de conversaciones.

unreadConversationCountChanged

El evento unreadConversationCountChanged se desencadena cuando aumenta o disminuye el número de conversaciones con mensajes no leídos.

window.HubSpotConversations.on('unreadConversationCountChanged', payload => { console.log(`New unread count is ${payload.unreadCount}!`); });
Campo Tipo Descripción
unreadCount Number El número total de conversaciones con al menos un mensaje no leído.

 

contactAssociated

El evento contactAssociated se desencadena cuando el visitante está asociado a un contacto en el CRM.

window.HubSpotConversations.on('contactAssociated', payload => { console.log(payload.message); });
Campo Tipo Descripción
message String Un mensaje de confirmación de que el visitante ha sido asociado con un contacto.

userInteractedWithWidget

El evento userInteractedWithWidget se desencadena cuando el visitante interactúa con el widget, como hacer clic para abrir el widget o cerrar el mensaje de bienvenida inicial.

window.HubSpotConversations.on(‘userInteractedWithWidget’, payload => { console.log(payload.message); });
Campo Tipo Descripción
message String Un mensaje de confirmación de que el visitante ha interactuado con el widget.

widgetLoaded

El evento widgetLoaded se desencadena cuando se carga el iframe del widget.

window.HubSpotConversations.on(‘widgetLoaded’, payload => { console.log(payload.message); });
Campo Tipo Descripción
message String Un mensaje de confirmación de que el iframe del widget se ha cargado.

quickReplyButtonClick

El evento quickReplyButtonClick se desencadena cuando el visitante hace clic en una respuesta rápida en una conversación de bot.

Campo Tipo Descripción
value Matriz Una matriz que contiene el texto de la opción de respuesta rápida en la que se hizo clic.
window.HubSpotConversations.on('quickReplyButtonClick', event => { console.log(`The text content of the clicked button is ${payload.value[0]}`); });

quick-reply-options-in-bot-conversation

En la captura de pantalla de ejemplo anterior, el chatflow del bot contiene tres opciones de respuesta rápida. Si el usuario selecciona Más información, la carga útil del evento resultante sería:

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

widgetClosed

El evento widgetClosed se desencadena cuando el visitante cierra el widget de chat.

window.HubSpotConversations.on('widgetClosed', event => { console.log(event); });
Campo Tipo Descripción
message String Un mensaje de confirmación de que el visitante ha cerrado el widget de chat.
¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.