API de JavaScript
Opciones de configuración, métodos, eventos y el contrato de postMessage.
window.TinkaySettings
Se define antes de cargar widget.js. Todos los campos menos token son opcionales.
| Campo | Tipo | Descripción |
|---|---|---|
tokenrequerido | string | Token público del Messenger (pk_live_...). |
visitor | object | Datos del usuario logueado. Equivale a llamar a identify al arrancar. |
hideLauncher | boolean | Oculta el botón flotante. Abrís el Messenger desde tu propio control. |
position | "left" | "right" | Lado de la pantalla. Por defecto usa lo configurado en el workspace. |
color | string | Color del lanzador en hexadecimal. Por defecto usa el del workspace. |
sideSpacing | number | Separación lateral en píxeles. Por defecto 20. |
bottomSpacing | number | Separación inferior en píxeles. Útil si tenés una barra fija abajo. |
locale | "es" | "en" | "pt" | Idioma de la interfaz del Messenger. |
window.TinkaySettings = { token: "pk_live_xxx", position: "right", bottomSpacing: 88, hideLauncher: false, visitor: { email: "[email protected]", name: "Camila Rodríguez" },};Métodos
Disponibles en window.Tinkay una vez que el loader terminó de ejecutarse.
| Campo | Tipo | Descripción |
|---|---|---|
Tinkay.open() | void | Abre el panel del Messenger. |
Tinkay.close() | void | Cierra el panel. |
Tinkay.toggle() | void | Alterna abierto y cerrado. |
Tinkay.identify(attrs) | void | Asocia la conversación a un contacto. Guarda los atributos para las próximas visitas. |
Tinkay.isOpen() | boolean | Indica si el panel está abierto. |
// Abrir desde tu propio botóndocument.querySelector("#ayuda").addEventListener("click", () => window.Tinkay.open());// Identificar al usuario después del loginwindow.Tinkay.identify({ email: "[email protected]", name: "Camila Rodríguez", plan: "Pro", created_at: "2026-01-15", company: "Kipu Pagos",});Si llamás a un método antes de que el loader termine, la llamada se descarta. Usá el evento tinkay:ready o comprobá window.Tinkay?.open?.().
Atributos del visitante
email es el único campo que Tinkay usa para vincular con un contacto existente. El resto se muestra como atributos en el panel lateral del Inbox.
| Campo | Tipo | Descripción |
|---|---|---|
email | string | Vincula con un contacto del workspace. Si no existe, se crea. |
name | string | Nombre a mostrar. |
plan | string | Plan o segmento del cliente. |
company | string | Empresa a la que pertenece. |
created_at | string (ISO 8601) | Fecha de alta del usuario en tu producto. |
(cualquier otro) | string | number | boolean | Se muestra como atributo personalizado en el panel del contacto. |
Eventos
El loader emite eventos del DOM sobre window. Sirven para sincronizar tu interfaz con el estado del Messenger.
| Campo | Tipo | Descripción |
|---|---|---|
tinkay:ready | CustomEvent | El Messenger terminó de cargar y la API está disponible. |
tinkay:open | CustomEvent | Se abrió el panel. |
tinkay:close | CustomEvent | Se cerró el panel. |
tinkay:unread | CustomEvent<{ count: number }> | Cambió la cantidad de mensajes sin leer. |
window.addEventListener("tinkay:ready", () => { window.Tinkay.identify({ email: currentUser.email, name: currentUser.name });});window.addEventListener("tinkay:unread", (e) => { document.title = e.detail.count > 0 ? `(${e.detail.count}) Soporte` : "Soporte";});window.addEventListener("tinkay:open", () => analytics.track("support_opened"));Contrato de postMessage
El loader y el iframe se comunican con postMessage. Documentamos el contrato por si necesitás embeber el Messenger vos mismo (por ejemplo dentro de otra aplicación).
Los mensajes del host llevan source: "tinkay-host"; los del iframe llevan source: "tinkay-widget".
{ source: "tinkay-widget", type: "tinkay:ready" }{ source: "tinkay-widget", type: "tinkay:open" }{ source: "tinkay-widget", type: "tinkay:close" }{ source: "tinkay-widget", type: "tinkay:unread", count: 2 }{ source: "tinkay-widget", type: "tinkay:resize", height: 640 }Apariencia
El Messenger vive en un iframe: tu CSS no lo afecta y el suyo no afecta a tu sitio. Los colores, el saludo y los módulos se configuran en Configuración, Messenger del workspace.
Lo único que podés ajustar desde el sitio es la posición y la separación de los bordes, útil cuando tenés una barra fija o un botón de cookies abajo.
window.TinkaySettings = { token: "pk_live_xxx", position: "left", sideSpacing: 24, bottomSpacing: 96, // deja lugar para tu barra fija};Cargarlo bajo demanda
Si querés que el widget solo pese cuando alguien pide ayuda, inyectá el loader al hacer clic.
function abrirSoporte() { if (window.Tinkay) return window.Tinkay.open(); window.TinkaySettings = { token: "pk_live_xxx", hideLauncher: true }; const s = document.createElement("script"); s.src = "https://cdn.tinkay.app/widget.js"; s.async = true; s.onload = () => window.addEventListener("tinkay:ready", () => window.Tinkay.open(), { once: true }); document.body.appendChild(s);}Cómo saber que quedó bien
- `window.Tinkay` responde en la consola
- `Tinkay.open()` abre el panel