Documentación — chatcocoa

Antes de empezar

Una vez registrado el canal, en «Ajustes del canal → Instalación» de la consola encontrarás dos cosas: la clave del canal y el secreto de API. La clave del canal aparece en el código fuente de la página y es pública; el secreto de API solo puede vivir en tu servidor.

En esa página hay además un enlace de prueba sin ningún parámetro: pégalo en el navegador para confirmar que el canal funciona. Conviene empezar por ahí.

Incrustar el script

En la esquina inferior derecha de tu web aparece una burbuja que se abre en una ventana de chat. Colócalo antes de </body>:

<script src="https://chat.jstosecret.com/embed.js"
        data-channel="TU_CLAVE_DE_CANAL"
        defer></script>

El chat corre dentro de un iframe, así que el CSS de tu página y el nuestro no se tocan. El script solo inyecta la burbuja y crea el iframe; no toca ningún otro elemento de tu página.

Instalación por enlace

Abre directamente una página de chat: sirve para navegadores dentro de apps, correos o acuses de tique, sitios donde no se puede insertar un script.

https://chat.jstosecret.com/?c=TU_CLAVE_DE_CANAL

Enviar la identidad del usuario

Envía los datos de usuario que ya tienes y el agente sabrá con quién habla desde el primer mensaje; además, si el visitante vuelve, se le dirige preferentemente al agente que lo atendió. Los tres campos son opcionales: envía los que tengas.

Parámetro	Atributos del script	Longitud máxima	Notas
`c`	`data-channel`	32	Clave del canal, obligatoria
`uid`	`data-uid`	64	El ID de usuario de tu sistema; es la señal principal para reconocer a quien vuelve
`email`	`data-email`	128	Email del usuario
`account`	`data-account`	128	Nombre de usuario o cuenta
`lang`	`data-lang`	20	Idioma concreto; si lo dejas vacío, se usa el del navegador
`extra`	`data-extra`	256	Información extra, texto plano, se muestra tal cual al agente y no interviene en la identificación

Lo que exceda el límite se guarda truncado: no da error ni echa a perder toda la instalación. La longitud se mide en caracteres, no en bytes; un ideograma o un emoji pueden ocupar varias posiciones.

<!-- Método de script: sustituye los marcadores en tu servidor -->
<script src="https://chat.jstosecret.com/embed.js"
        data-channel="TU_CLAVE_DE_CANAL"
        data-uid="10001"
        data-email="[email protected]"
        data-extra="Cliente VIP pedido#8823"
        defer></script>

Cómo se identifica a un visitante

Los tres campos de identidad son una prioridad excluyente, no una cadena de alternativas:

Has enviado	Se identifica por	Cuando no hay coincidencia
`uid`	Solo por `uid`	Se cuenta como visitante nuevo y no se prueba con el email
Solo `email`	Por `email`	Se cuenta como visitante nuevo
Solo `account`	Por `account`	Se cuenta como visitante nuevo
Sin enviar nada	Identificador local del navegador	Se cuenta como visitante nuevo

Si envías uid, solo se usa uid, y esta es la regla más importante. Recurrir a otro campo mezcla identidades: si cambias de sistema de usuarios y el uid cambia, o dos empleados comparten un mismo [email protected], el segundo hereda la ficha del primero y ve todo su historial de conversaciones. El uid es una afirmación de identidad que haces a propósito; cuando dice "este es un usuario nuevo", no deberíamos contradecirlo con un campo más débil.

Dos cosas a tener en cuenta al instalarlo:

Si tienes uid, envíalo siempre. Mandar uid esta vez y solo email la siguiente convierte a una persona en dos visitantes, y el historial deja de cuadrar.
El uid tiene que ser estable. Usa un valor que no cambie, como la clave primaria de tu base de datos, y no un teléfono o un email que el propio usuario pueda editar: cambiarlo equivale a convertirse en otra persona.

El reconocimiento se limita a un mismo canal. La misma persona son dos registros independientes en dos canales tuyos, sin conversaciones ni historial compartidos; forma parte del aislamiento entre canales.

Caracteres especiales en la información extra

La información extra es el parámetro que más problemas da, porque su contenido lo decide tu negocio por completo: números de pedido, direcciones, peticiones del cliente, cualquier cosa puede acabar ahí. Tres reglas:

Al construir el enlace usa siempre encodeURIComponent() en lugar de concatenar cadenas a mano. Un &, #, ?, + o espacio sin codificar corta el enlace o se cuela en otro parámetro: la B de extra=A&B llega como un parámetro aparte.
Escapa el HTML de lo que escribas en el atributo data-extra: " pasa a " y < pasa a <. Si no, una sola comilla cierra el atributo antes de tiempo y se lleva por delante toda la etiqueta script. En el servidor basta con el escapado que ya trae tu motor de plantillas.
Los saltos de línea y los tabuladores se sustituyen por espacios; dejarlos solo descuadra la vista del agente.

Los emoji y cualquier alfabeto funcionan tal cual; el almacenamiento es utf8mb4.

// La forma correcta de construirlo
const url = 'https://chat.jstosecret.com/?c=TU_CLAVE_DE_CANAL'
  + '&uid=' + encodeURIComponent(user.id)
  + '&extra=' + encodeURIComponent('Cliente VIP pedido#8823 nota:urgente&prioritario')

// Mal: & y # sin codificar, extra solo recibe "Cliente VIP pedido"
// y el "prioritario" final acaba como un parámetro suelto llamado "prioritario"
const bad = base + '&extra=Cliente VIP pedido#8823 nota:urgente&prioritario'

Estos parámetros van en texto plano

Aparecen en el código fuente de la página y en la barra de direcciones, y cualquiera puede cambiarlos. Es decir, si la identidad viaja solo así, basta con cambiar el uid para hacerse pasar por otro usuario y ver su historial. Si en la conversación se hablará de pedidos o cuentas, usa el método de tique que viene abajo.

Tiques de un solo uso

Tu servidor canjea el secreto de API por un tique y luego mete ese tique en el enlace que entrega al visitante. En la URL no aparece ningún dato del usuario, el tique caduca al usarse y un enlace reenviado no abre una segunda vez.

Paso 1: canjear el tique en tu servidor

curl -X POST https://chat.jstosecret.com/api/open/ticket \
  -H 'Content-Type: application/json' \
  -H 'X-Channel-Secret: TU_SECRETO_DE_API' \
  -d '{"channelCode":"TU_CLAVE_DE_CANAL","uid":"10001","extra":"Cliente VIP pedido#8823"}'

# Respuesta
{ "ticket": "a1b2c3...", "expiresIn": 300 }

Paso 2: entregar el tique al visitante

# Método de enlace
https://chat.jstosecret.com/?c=TU_CLAVE_DE_CANAL&ticket=a1b2c3...

# O método de script
<script src="https://chat.jstosecret.com/embed.js"
        data-channel="TU_CLAVE_DE_CANAL"
        data-ticket="a1b2c3..."
        defer></script>

El secreto de API solo puede quedarse en tu servidor. Ponerlo en el front equivale a publicarlo: cualquiera podría firmar la identidad de otra persona.
Los tiques duran 5 minutos por defecto; con expiresIn puedes fijar entre 30 y 1800 segundos.
Que el visitante recargue no afecta a nada: tras la primera entrada, el tique se cambia por un token local de larga duración.
El tique transmite la identidad, no la almacena. Si el visitante vuelve tres meses después, basta con canjear otro tique: el historial sigue ahí.

Apariencia y posición

El icono, la posición, los márgenes y el color de la burbuja, además del nombre y el icono del proyecto en la cabecera del chat, se configuran en «Ajustes del canal» de la consola. Los cambios se aplican en cuanto el visitante recarga la página; no hay que volver a pegar el código.

Si algún sitio necesita ajustar la posición (por ejemplo, si la esquina inferior derecha ya está ocupada por otro botón), puedes añadir atributos que la sobrescriban:

<script src="https://chat.jstosecret.com/embed.js"
        data-channel="TU_CLAVE_DE_CANAL"
        data-position="left-bottom"
        data-offset-x="24"
        data-offset-y="90"
        defer></script>

Ten en cuenta que estos atributos tienen prioridad: una vez añadidos, la posición en ese sitio queda fija y los cambios posteriores en la consola no se aplican. Úsalos solo cuando haga falta de verdad.

Dominio propio

Profesional y superiores incluyen un dominio propio. El chat y la burbuja se sirven desde un dominio tuyo, por ejemplo chat.yourdomain.com, así que la dirección que ve el visitante es tu marca.

Por qué merece la pena

Más allá de la marca, el beneficio práctico es aislar el riesgo de caídas. Por defecto todos los clientes comparten nuestro dominio de chat: basta con que a uno lo bloquee una red, un operador o el cortafuegos de una empresa para que deje de cargar para todos. Tú solo ves "los visitantes de pronto no conectan", y estarías buscando la causa en el sitio equivocado.

Con tu propio dominio, las caídas ajenas no te alcanzan; y cuando el problema te toque a ti, cambiar un registro DNS te devuelve el servicio sin hacer cola detrás de nosotros. Insignia incluye 5, así que varias marcas o varios sitios pueden usar cada uno el suyo sin afectarse.

Cómo se configura

Tú añades un registro CNAME en tu DNS apuntando a la dirección que te damos
Del certificado nos encargamos nosotros, incluida la renovación
Cuando esté activo, cambia la dirección del código de instalación por el nuevo dominio; no hay que tocar nada más

Para activarlo, escribe a [email protected] indicándonos el dominio que quieres usar.

Control manual

Para abrir el chat desde un botón de tu propia página en lugar de la burbuja por defecto:

// Disponible una vez cargado el script
window.KefuWidget.open()
window.KefuWidget.close()
window.KefuWidget.toggle()

La burbuja en sí no se puede ocultar: si solo quieres usar tu propio botón, desplázala fuera de la pantalla con sus márgenes, por ejemplo data-offset-x="-100".

Problemas al instalar

Empieza por el mensaje de error que devolvió tu servidor. La mayoría de los problemas de instalación (clave de canal mal escrita, tique caducado, secreto expuesto en el front) indican la causa directamente en la respuesta.

Soporte técnico: Telegram @chatcocoaofficial, 24/7
Comercial y proyectos a medida: [email protected]