Hay cuatro formas, de menos a más esfuerzo, y la primera se resuelve en quince minutos sin tocar tu backend.
Conectar Tinkay con los datos de tu empresa tiene cuatro niveles, y no hace falta empezar por el más grande. El nivel 1 son atributos que tu propia página le pasa al widget y se pone en una tarde. El nivel 2 son conectores HTTP que consultan tu sistema en vivo mientras hablás con el cliente. El nivel 3 sincroniza tu base de clientes hacia Contactos. El nivel 4 es una réplica de solo lectura de tu base. Esta nota explica cada uno, qué necesita y cuándo conviene.
¿Por qué conectar los datos y no copiarlos a mano?
Porque la diferencia se nota en la primera conversación. Sin datos conectados, quien atiende empieza preguntando "¿me pasás tu email?" y sigue con "dame un minuto que lo busco". Con datos conectados, la conversación arranca con el plan del cliente, su estado de cuenta y su último pedido ya a la vista, y Tinkay AI puede responder con ese dato en vez de mandar a alguien a mirar otro sistema.
El otro motivo es que copiar no escala. Una exportación a CSV envejece el mismo día que la hacés, y la respuesta "según lo que veo acá tu plan es Esencial" es exactamente el tipo de error que quema la confianza de un cliente.
¿Cuáles son los cuatro niveles?
| Nivel | Qué es | Qué necesitás | Cuándo conviene |
|---|
| 1 · Atributos | Tu página le manda datos al widget junto con el usuario | Editar el snippet y calcular una firma en tu servidor | Siempre. Es el piso y no cuesta casi nada. |
| 2 · Conectores HTTP | Tinkay consulta tu API en vivo durante la conversación | Un endpoint que devuelva JSON y una credencial | Cuando el dato cambia seguido: cobros, envíos, stock. |
| 3 · Sincronización | Tu base de clientes se copia periódicamente a Contactos | Un usuario de solo lectura o una planilla | Para segmentar, buscar y tener a todos cargados. |
| 4 · Base directa | Réplica de solo lectura o agente de túnel contra tu base | Una réplica y una regla de red | Cuando no hay API y los datos viven solo en la base. |
Nivel 1: ¿qué son los atributos del Messenger?
Son datos que tu propia página le entrega al widget cuando carga, junto con la identidad del usuario logueado. No hay integración de servidor a servidor: la información viaja con la persona.
Un ejemplo de lo que se manda habitualmente: user_id, plan, saldo_ars, antiguedad_dias, estado_cuenta. Cada atributo queda guardado en el contacto, se ve en el panel al costado de la conversación y se puede segmentar.
La parte importante es la firma. Junto con el identificador se manda un user_hash, que es un HMAC-SHA256 del user_id calculado en tu servidor con una clave secreta que solo vos y Tinkay conocen:
// Node
const crypto = require("crypto");
const userHash = crypto.createHmac("sha256", SECRET).update(String(user.id)).digest("hex");
Sin esa firma, cualquiera podría abrir la consola del navegador, cambiar el user_id y ver la conversación de otra persona. Con la firma, el servidor rechaza cualquier identidad que no venga acompañada del hash correcto. El mismo cálculo existe en PHP, Python, .NET y Ruby, y es siempre HMAC-SHA256 sobre el identificador.
La clave secreta nunca va en el navegador. Si el hash lo calcula el frontend, el mecanismo entero no sirve para nada: cualquiera lo puede recalcular. Se calcula en tu servidor y se imprime en la plantilla, junto con el resto de los atributos.
Nivel 2: ¿cómo funciona un conector HTTP?
Un conector es una llamada a tu API que Tinkay hace en el momento en que alguien pregunta algo, con el contacto de la conversación como parámetro. No copia nada: consulta y muestra.
Se define con cuatro cosas: un método y una URL con variables, una credencial, un tiempo de espera y un mapeo de campos. Así se ve uno para el estado de una suscripción:
GET https://api.tuempresa.com/v2/billing/subscription?email={{contact.email}}
Autenticación: Bearer
Tiempo de espera: 4000 ms · Reintentos: 2 (exponencial) · Caché: 60 s
Del JSON que devuelve tu API se eligen los campos que importan con un JSONPath simple, y cada uno se configura por separado:
| Campo | Ruta | Formato | ¿Lo ve la IA? |
|---|
| Plan | $.data.plan | Etiqueta | Sí |
| Estado de cobro | $.data.status | Etiqueta | Sí |
| Próximo débito | $.data.next_charge_at | Fecha | Sí |
| Tarjeta | $.data.card_last4 | Texto | No, marcado como sensible |
Ese último renglón es el que hace que esto sea usable en serio: un campo puede aparecer en el panel para el agente y quedar fuera del alcance de la IA, o estar disponible solo para un equipo. La decisión es por campo, no por conector.
La caché existe por una razón práctica: si veinte personas preguntan por su plan en un minuto, tu API recibe menos llamadas de las que parece. Con 60 segundos de caché, una operación real puede resolver más de la mitad de las consultas sin salir a pedir nada.
¿Qué pasa si tu API se cae?
El conector devuelve error y la conversación sigue: Tinkay muestra el resto del panel y quien atiende ve que ese dato no está disponible ahora. Cada llamada queda registrada con su código de estado, su latencia y si se sirvió del caché, así que cuando algo no anda se puede ver exactamente qué se pidió y qué contestó tu sistema.
Nivel 3: ¿qué hace la sincronización de clientes?
Trae tu base de clientes a Contactos cada 15 minutos, cada hora o una vez por día, para que estén todos cargados aunque nunca hayan escrito. Sirve para buscar, segmentar y tener el historial completo desde el primer mensaje.
El origen puede ser Postgres, MySQL, SQL Server, MongoDB, BigQuery, Snowflake, una planilla de Google, un CSV o un endpoint REST. Se eligen las columnas, se mapea cada una a un campo de Tinkay o a un atributo, y se define con qué clave se evita duplicar: email, teléfono o identificador externo.
Dos decisiones que conviene tomar de entrada. La primera es el modo: insertar crea contactos nuevos y no toca los existentes, actualizar hace lo contrario, y upsert hace las dos cosas. La segunda es la clave de deduplicación: si tenés identificador propio, usalo; el email cambia más de lo que uno cree.
Cada corrida deja un registro con cuántas filas se leyeron, cuántas se crearon, cuántas se actualizaron y cuáles fallaron, con el error fila por fila. Es lo que convierte una sincronización en algo mantenible en vez de una caja negra.
Nivel 4: ¿cuándo hace falta conectar la base directo?
Cuando el dato existe solamente en la base y no hay API que lo exponga, que es más común de lo que parece en sistemas internos con años encima.
Hay dos formas. Una réplica de solo lectura a la que Tinkay se conecta con un usuario sin permisos de escritura, habilitando nuestras IPs de salida en tu firewall. O un agente de túnel que instalás vos del lado de tu red y que abre la conexión hacia afuera, sin que tengas que exponer ningún puerto.
La regla que no cambia en ningún nivel: Tinkay nunca pide permisos de escritura sobre tu base de producción. El usuario es de solo lectura, la conexión va con SSL y cada consulta queda auditada con quién la hizo, para qué conversación y qué campos se leyeron.
¿Y si la IA tiene que hacer algo, no solo leer?
Un conector puede quedar habilitado para que Tinkay AI lo llame sola cuando la conversación lo pide, en vez de esperar a que un agente apriete un botón. Esa es la diferencia entre una IA que repite artículos y una que contesta "tu próximo débito es el 12 de septiembre por $ 49.800", con el dato traído de tu sistema en ese segundo.
Escribimos aparte sobre eso, con ejemplos de qué cambia cuando la IA arranca sabiendo quién le está escribiendo: qué puede hacer una IA de atención al cliente que sabe quién le está escribiendo.
La parte de escritura —que la IA no solo consulte sino que además cree o modifique algo en tu sistema— la estamos construyendo, y preferimos no venderla hasta que esté. Hoy el alcance es consulta en vivo, y es bastante.
¿Por dónde empezar?
- Nivel 1, esta semana. Mandá
user_id firmado y dos o tres atributos que uses todos los días. Es la mejor relación entre esfuerzo y resultado de las cuatro.
- Nivel 2, cuando tengas una pregunta repetida con respuesta en tu sistema. "¿Dónde está mi pedido?" y "¿cuándo me cobran?" son las dos que aparecen siempre primero.
- Nivel 3, cuando necesites buscar o segmentar por gente que todavía no te escribió.
- Nivel 4, solo si no hay API. Es el más potente y el que más coordinación pide con el área de infraestructura.
Los detalles técnicos de cada uno, con el snippet para cada stack, están en la documentación para desarrolladores. Y si todavía estás decidiendo herramienta, la lista de lo que conviene mirar antes de firmar está en qué mirar antes de elegir un software de atención al cliente.
