SDK de conversaciones

El widget de chat en directo de HubSpot te permite chatear con clientes y leads en tu propio sitio web. Con el SDK de widget de chat, puedes proporcionarles una experiencia más personalizada a los visitantes personalizando el comportamiento del widget de chat.

Caso de uso: El SDK de widget de chat se puede usar para personalizar cuándo y cómo aparece el widget de chat de HubSpot en tu sitio web.

En un nivel alto, te permite hacer lo siguiente:

Primeros pasos

La API está alojada en el objeto window.HubSpotConversations . Todos los métodos disponibles pueden acceder a través de este objeto. El cargador de scripts de HubSpot (también conocido como el código de seguimiento de HubSpot) en tu página creará este objeto para ti, pero es posible que no esté disponible inmediatamente. Para diferir el acceso a la API hasta que esté inicializado, puedes usar el ayudante window.hsConversationsOnReady. Ve a continuación un ejemplo simple:

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

Referencia de SDK 

window.hsConversationsOnReady

Este es un campo especial que puedes definir en el objeto de window que te permite especificar el código que se ejecutará tan pronto como el widget esté disponible. El uso de esta propiedad es opcional. Si se usa, este campo debe establecerse en una matriz de funciones. Una vez que la API haya sido inicializada, comprobará la existencia de esta matriz y ejecutará las funciones en serie. Por ejemplo:

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

hsConversationsSettings

Este objeto te permite proporcionar algunas opciones de configuración al widget antes de inicializar. El uso de este objeto es opcional.

Campos
Nombre de campo Tipo de dato Predeterminado  Descripción

loadImmediately 

 

 Boolean true Ya sea que el widget se cargue implícitamente o espere hasta que se llame al método  widget.load
inlineEmbedSelector String "" Si el widget debe estar incrustado en la página. Si se proporciona un selector (por ejemplo, #some-id), el widget se incrustará en línea dentro de ese nodo DOM. Siempre estará abierto hasta que se elimine a través de widget.remove
enableWidgetCookieBanner Enum false Controla el comportamiento del banner de cookies para todos los chatflows en la página:

false: usa la configuración de chatflows (opción predeterminada)

true: activa banners de cookies cuando se carga el widget

ON_WIDGET_LOAD: igual que true: activa banners de cookies cuando el widget está cargado

ON_EXIT_INTENT: activa los banners de cookies cuando el usuario muestra un intento de salida


Ten en cuenta que este campo solía ser un Boolean. Ahora puede aceptar tanto los valores Boolean originales como los valores de enum actualizados.
disableAttachment Boolean false Si el botón de carga de archivos adjuntos debe ocultarse o no en el widget de chat.
disableInitialInputFocus Boolean false Determina si se debe evitar automáticamente el enfoque en el campo de entrada del widget después de que un widget incrustado en línea se cargue inicialmente en una página.
 
window.hsConversationsSettings = { loadImmediately: false, inlineEmbedSelector: '#some-id', enableWidgetCookieBanner: true, disableAttachment: true }; window.hsConversationsOnReady = [ () => { window.HubSpotConversations.widget.load(); }, ];

Estilo de incrustación en línea

window.hsConversationsOnReady

Cuando el widget está incrustado en una ubicación especificada por cliente, se agregan varios elementos de DOM y se pueden adaptar a los requisitos de personalización del cliente (por ejemplo, alto, ancho, borde). Ten en cuenta que esta estructura solo se aplica si usas la opción  inlineEmbedSelector.

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

Por ejemplo, por opción predeterminada, el widget de chat puede verse como este:

livechat_before

 

Este diseño aplastado no es una experiencia ideal, por lo que puedes personalizar el widget incluyendo estilos como esto:


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

livechat_after

Esto ofrece una experiencia de usuario mucho más amigable. 

 

HubSpotConversations.widget

El objeto del widget contiene varios métodos que te permiten manipular el widget de chat en tu página.

widget.load

Carga el widget por primera vez en la página. Si el widget está cargado actualmente, las llamadas posteriores a este método no son operativas.

Este método solo es necesario si configuras la bandera loadImmediately en false. De lo contrario, el widget se cargará automáticamente.

Nota: widget.load se limita a una llamada por segundo.

Parámetros:
Nombre de campo ¿Tipo de dato? Predeterminado Descripción
widgetOpen Boolean false Si el widget debe cargarse en un estado abierto
 
window.HubSpotConversations.widget.load(); /* ... */ // Force the widget to load in an open state window.HubSpotConversations.widget.load({ widgetOpen: true });

widget.refresh

Actualiza y vuelve a mostrar la información del widget, dada la URL de la página actual.

Si alojas el widget de chat en una aplicación de una sola página, este método puede ser útil para actualizar el widget en los cambios de ruta. Esto te permite especificar diferentes chatflows en diferentes rutas de página. Si se llama widget.refresh en una ruta donde no hay ningún chatflow, y el usuario no está interactuando en una conversación, el widget será eliminado.

Nota: widget.refresh se limita a una llamada por segundo.

Parámetros:
Nombre de campo ¿Tipo de dato? Predeterminado Descripción
openToNewThread Boolean false Ya sea para forzar la creación de un nuevo hilo

Para un ejemplo de cómo usar el campo openToNewThread, consulta Abrir un chatflow específico.

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

Nota: widget.refresh no eliminará las conversaciones existentes que un visitante de una página ha comenzado en el widget.

 

widget.open

Abre el widget. Si el widget ya está abierto o no está cargado actualmente, esto no es operativo.

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

widget.close

Cierra el widget. Si el widget ya está cerrado o no está cargado actualmente, esto no es operativo.

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

widget.remove

Elimina el widget de la página. Si el widget no está presente en la página, esto no es operativo. Para mostrar el widget de nuevo, tendrás que tener en cuenta una actualización completa de la página o una opción que pueda generar widget.load.

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

widget.status

Devuelve un objeto que contiene propiedades relacionadas con el estado del widget.

Nombre de campo Tipo de dato Predeterminado Descripción
loaded Boolean false Ya sea que el widget iframe se haya cargado o no.

 

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

clear

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

El método clear puede utilizarse para eliminar estas cookies, regresando al widget a su estado predeterminado en cargas subsiguientes.

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 acerca de estas cookies, consulta este artículo de la base de conocimientos.

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

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

Especificación de eventos

El widget de chat emitirá varios eventos que puedes escuchar y responder a lo largo del ciclo de vida.

 

Eventos admitidos

conversationStarted

Se emite cuando se ha iniciado correctamente una nueva conversación.

Carga de eventos
Nombre de campo Tipo de dato Descripción
conversation Conversación Detalles sobre la conversación que se inició

 

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

conversationClosed

Se emite cuando se ha cerrado correctamente una nueva conversación.

Nota: este evento se activa cuando la conversación se marca como cerrada desde la bandeja de entrada de conversaciones y no está relacionado con que el usuario minimice o cierre el widget de chat.

 

Carga de eventos
Nombre de campo Tipo de dato Descripción
conversation Conversación Detalles sobre la conversación que se cerró

 

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

unreadConversationCountChanged

Se emite cuando cambia (aumenta o disminuye) la cantidad de conversaciones en el widget con mensajes no leídos.

Carga de eventos
Nombre de campo Tipo de dato Descripción
unreadCount Number El nuevo total de conversaciones en el widget con cualquier mensaje no leído

 

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

contactAssociated

Se emite cuando el visitante está asociado a un contacto en el CRM. 

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

userInteractedWithWidget

Se emite tan pronto como el usuario interactúa con el widget (por ejemplo, haciendo clic en el iniciador para abrir el widget, cerrando el mensaje de bienvenida inicial, etc.)

Carga de eventos
Nombre de campo Tipo de dato Descripción
message String Un mensaje de confirmación de que el usuario ha interactuado con el widget.
Ejemplo:
window.HubSpotConversations.on(‘userInteractedWithWidget’, payload => { console.log(payload.message); });

widgetLoaded

Se emite cuando el iframe del widget se ha cargado.

Carga de eventos
Nombre de campo Tipo de dato Descripción
message String Mensaje de confirmación de que el iframe del widget se ha cargado.
Ejemplo:
window.HubSpotConversations.on(‘widgetLoaded’, payload => { console.log(payload.message); });

quickReplyButtonClick

Se emite cuando el usuario hace clic en el botón de respuesta rápida en una conversación de bot

Carga de eventos
Nombre de campo Tipo de dato Descripción
value Matriz Contiene el contenido del texto del botón de respuesta rápida en el que se hizo clic.
Ejemplo:
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 disponibles para que el usuario las seleccione. Si el usuario seleccionó 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" ] }
window.HubSpotConversations.on('quickReplyButtonClick', event => { console.log(`The text content of the clicked button is ${payload.value[0]}`); });

widgetClosed

Se emite cuando se cierra el widget.

Carga de eventos
Nombre de campo Tipo de dato Descripción
message String Mensaje de confirmación de que el widget está cerrado.
Ejemplo:
window.HubSpotConversations.on('widgetClosed', event => { console.log(event); });

Registrar y eliminar detector de eventos

on

Registra un contacto de evento. Consulta tipos de eventos compatibles

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

off

Elimina un detector de eventos. Consulta tipos de eventos compatibles

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

Tipo de dato

Lo siguiente es una referencia a los tipos de datos que son comunes al SDK de JavaScript.

Conversación
Nombre de campo Tipo de dato Descripción
conversationId Number El ID de la conversación
¿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.