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:
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.
hsConversationsSettings
Este objeto te permite proporcionar algunas opciones de configuración al widget antes de inicializar.
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:
|
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. |
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:
You can then customize the chat widget using those selectors, such as:
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.
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.
Campo | Tipo | Predeterminado | Descripción |
---|---|---|---|
widgetOpen |
Boolean | false |
Si el widget debe cargarse en un estado abierto. |
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.
Campo | Tipo | Predeterminado | Descripción |
---|---|---|---|
openToNewThread |
Boolean | false |
Ya sea para forzar la creación de un nuevo hilo. |
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.
Por ejemplo, podrías agregar el siguiente código a tus páginas para generar los botones:
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.
El método widget.close
cierra el widget si aún no está cerrado.
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
.
El método widget.status
devuelve un objeto que contiene propiedades relacionadas con el estado actual del widget.
Campo | Tipo | Predeterminado | Descripción |
---|---|---|---|
loaded |
Boolean | false |
Ya sea que el widget iframe se haya cargado. |
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.
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.
El widget de chat emite varios eventos que puedes escuchar y responder a lo largo de su ciclo de vida. Estos eventos incluyen:
- conversationStarted
- conversationClosed
- unreadConversationCountChanged
- contactAssociated
- userInteractedWithWidget
- widgetLoaded
- quickReplyButtonClick
- widgetClosed
Para registrar y eliminar oyentes de eventos, los usarás on
y off
, como se muestra a continuación.
Obtén más información sobre cada evento a continuación.
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. |
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.
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. |
El evento unreadConversationCountChanged
se desencadena cuando aumenta o disminuye el número de conversaciones con mensajes no leídos.
Campo | Tipo | Descripción |
---|---|---|
unreadCount |
Number | El número total de conversaciones con al menos un mensaje no leído. |
El evento contactAssociated
se desencadena cuando el visitante está asociado a un contacto en el CRM.
Campo | Tipo | Descripción |
---|---|---|
message |
String | Un mensaje de confirmación de que el visitante ha sido asociado con un contacto. |
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.
Campo | Tipo | Descripción |
---|---|---|
message |
String | Un mensaje de confirmación de que el visitante ha interactuado con el widget. |
El evento widgetLoaded
se desencadena cuando se carga el iframe del widget.
Campo | Tipo | Descripción |
---|---|---|
message |
String | Un mensaje de confirmación de que el iframe del widget se ha cargado. |
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. |
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:
El evento widgetClosed
se desencadena cuando el visitante cierra el widget de chat.
Campo | Tipo | Descripción |
---|---|---|
message |
String | Un mensaje de confirmación de que el visitante ha cerrado el widget de chat. |
Gracias por tus comentarios, son muy importantes para nosotros.