Documentación
🇺🇸🇧🇷Discord

Botón de chat web de la API

Suggest Edits

🚧

Todo lo que se describe en el artículo funciona solo con el código para colocar el botón de chat web copiado desde la interfaz de Kommo.

Obtén el botón

Debes ir a Pipeline ➡️ +Automatiza ➡️ botón Agregar fuentes en el menú izquierdo ➡️

Select Website chat button

Selecciona Botón del chat web

➡️ Ve a la pestaña Instalación ➡️ Copia el código.

Necesitas ubicar el objeto de configuración Botón de chat web window.crmPluginConfig para el botón de chat web en cualquier parte de la página antes de incluir el código para el mismo botón.

window.crmPluginConfig = { 
  hidden: false, // ocultar el botón al cargar la página
  color: '#000', // cambiar el color del botón, ignorará el color configurado en Kommo

  onlinechat: { 
    mode: 'widget', // también puede ser 'frame', más detalles a continuación
    user_id: '', // ID de usuario de chat en línea (parámetro opcional)

    locale: { 
      extends: "com", 
      compose_placeholder: "escribe tu pregunta...", 
    }, 

    theme: { 
      header: false, 
    },
  }, 
};

Veamos más de cerca los ajustes del chat en línea.

Mostrar una ventana de chat en un elemento personalizado de la página

window.crmPluginConfig = {
 onlinechat: { 
   mode: 'frame', 
   container: '#custom_chat_holder', 
 }, 
};

En este caso, cuando haces clic en el icono de chat en línea en el botón, el chat se abrirá no en un bloque emergente al lado del botón, sino en un elemento específico de la página que se especifica en la propiedad container .

📘

En este modo, los mensajes emergentes dejan de aparecer al lado del botón. Cuando llega un nuevo mensaje en el chat en línea, solo se muestra la cantidad de mensajes no leídos.

Localización

Lista completa de cadenas disponibles para localización:

window.crmPluginConfig = {
 onlinechat: {
  locale: { 
    extends: 'es',
    date_format: 'dd.MM.YYYY', 
    time_format: 'HH:mm', 
    compose_placeholder: 'Escribe un mensaje...',
    delivery_status_sending: 'Enviando', 
    delivery_status_sent: 'Enviado', 
    delivery_status_read: 'Leído', 
    delivery_status_error: 'Error', 
    powered_by: 'Desarrollado por', 
    new_messages: 'Nuevos mensajes' 
  }, 
 }, 
};

Puedes enviar solo los strings necesarios para traducir especificando el locale inicial a través de extends. Actualmente, el chat en línea soporta tres localizaciones predefinidas: en, es, pt.

Para date_format y time_format puedes especificar cualquier valor válido de la librería date-fns .

Cambiar la apariencia del chat

window.crmPluginConfig = {
 onlinechat: {
  theme: {
   background: 'yellow', // fondo
   system_color: 'pink', // color de los textos del sistema (estado de entrega, fecha)
   header: { // Puedes especificar header: entonces no se renderizará en absoluto
     background: 'skyblue', // el color de fondo de la parte superior del chat 
     color: 'black', // color del texto superior 
   }, 
   message: {
     outgoing_background: 'red', // fondo del mensaje del usuario
     outgoing_color: 'white', // color del mensaje del usuario
     incoming_background: 'blue', // fondo de la respuesta 
     incoming_color: 'white', // color de la respuesta
   }, 
   compose: { 
     height: 100, // altura mínima en píxeles (máximo 170px, no se puede cambiar)     
     button_background: 'black', // fondo del botón de envío
   } 
  }, 
 }, 
};

Todos los colores deben ser especificados en un formato que pueda ser procesado por CSS en el navegador(por ej.: código hex, rgb, rgba).

Cambiar el usuario del chat

Aplicar la propiedad user_id para crear el ID de usuario del chat en línea. Puede ser útil en casos cuando quieras continuar la conversación en un chat preexistente si el usuario ha iniciado sesión desde otro dispositivo.

Ejemplos de uso:

  1. El cliente de la tienda en línea está autorizado en su cuenta e inicia el diálogo en el chat en línea (donde el user_id fue transferido previamente).
  2. El mismo cliente decide iniciar sesión desde otro dispositivo (por ejemplo, a través de su teléfono móvil).
  3. Después de que el cliente sea autorizado en su cuenta, pasamos el mismo user_id.
  4. Cuando el cliente abre la ventana del chat en línea, aparecerá un diálogo existente con todo el historial de correspondencia.

Se recomienda aplicar un hash al user_id utilizando cualquier algoritmo de encriptación conveniente para ti (SHA-256, MD-5, etc.) para proteger la conversación contra el acceso no autorizado al iterar sobre el ID de usuario.

window.crmPluginConfig = {
 onlinechat: {
  user_id: 'abc123'
 }, 
};

Métodos JS

Para trabajar con chats, también está disponible una función especial de JavaScript llamada crmPlugin . Puede ser utilizada en cualquier parte luego de haber instalado el código del botón.

Métodos compatibles:

  1. crmPlugin(‘runChatShow’) – mostrar el chat.
  2. crmPlugin(‘runChatHide’) – ocultar el chat chat.

A veces necesitamos eliminar la instancia actual del botón e inicializar una nueva, por ejemplo, para iniciar un chat con un user_id diferente.

Para eliminar una instancia, se ofrece el siguiente método:

  1. crmPlugin(‘runDestroy’) – elimina la instancia actual del botón.

Callbacks

También se ofrecen callbacks para manejar eventos que ocurren en el botón y en el chat en línea.

crmPlugin('onChatShow|onChatHide', function () {
  
});

crmPlugin('onChatReady', function () {
  // se inicializa el chat
  // puedes trabajar con él a través de la API de JavaScript
  crmPlugin('runChatShow');
});

crmPlugin('onConversationsChange', function (conversations) {
   // cuando cambies de conversación
   //
   // cuando las conversaciones múltiples estén desactivadas, el evento se ejecutará 1 vez
   // donde las conversaciones serán false
   //
   // parámetros de entrada:
   // conversations - array de conversaciones visibles

  // el formato de la conversación
  //
  // {
  //   name: 'A123',
  //   is_closed: true | false,
  //   last_message: {
  //     media: {
  //       url: 'https://path_to_resource.mp4',
  //       thumbnail: 'https://path_to_preview.jpg',
  //     } | undefined,
  //     created_at: 1655283158457,
  //     is_out: true | false,
  //     text: 'Hola',
  //     type: 'text' | 'video' | 'photo',
  //     author: {
  //       name: author.name,
  //     } | undefined,
  //   },
  // },
});

Parámetros JS en el chatbot en línea

Puedes pasar tus propios parámetros al chatbot en línea utilizando el método crm_plugin.setMeta y crear diferentes cadenas de comportamiento del bot basadas en estos parámetros.

Por ejemplo, un usuario es autorizado en tu sitio, y te gustaría darle la bienvenida por su nombre. En este caso, necesitas llamar el siguiente código en tu sitio:

var NOMBRE_USUARIO = ""; 
crm_plugin.setMeta({ 
  bot_params: { 
    username: NOMBRE_USUARIO
  } 
});

Añade el mensaje de bienvenida hola, {{bot_params.username}} en el chatbot en línea.

Además, el chatbot en línea admite la condición con la verificación bot_params check in the first step, so you can easily implement, for example, multilingualism in the welcome message.

En tu sitio, necesitas pasar el parámetro con la configuración regional actual del usuario:

var LOCALE = "com"; // obtén la configuración regional mediante geoip o la API del navegador
crm_plugin.setMeta({
 bot_params: {
  locale: LOCALE 
 } 
});

Coloca la condición en primer lugar en el bot, y en el área de texto de la condición añade el siguiente código:

// como puedes ver, aquí hay un array
// por lo tanto, puede haber varias condiciones "y"
[
  {
    "term1": "{{bot_params.locale}}",
    "term2": "com",
    "operation": "="
  }
]

Ahora, si el usuario ha ingresado al sitio y hemos determinado que su idioma es el inglés, procederemos con él utilizando la rama del bot en inglés.

También puedes añadir scripts en otros idiomas a través de la interfaz de bloques, y siempre habrá un bloque común "else", que contendrá una rama alternativa del script si el usuario no cumple con ninguna de nuestras condiciones.

Ejecutar una 'Key Action' con un hook

Para enviar tu propio hook y disparar una acción clave, necesitas ejecutar el siguiente código en cualquier lugar después de conectar el código del botón o a través de algún evento del navegador (por ejemplo, al hacer clic en el botón):

crmPlugin('sendKeyActionHook', 'Nombre del hook');

Puedes configurarlo en la pestaña de Configuración avanzada en la configuración del botón de chat del sitio web.

Updated 8 days ago