Referencia de eventos

Los 126 eventos que emite Tinkay, con su payload y cuándo se disparan.

Cada cambio relevante en un workspace emite un evento. Los mismos eventos alimentan los webhooks, las automatizaciones, el registro de actividad y el endpoint GET /v1/events.

La versión actual del payload es 2026-09-01. Los eventos nuevos y los campos nuevos no son cambios que rompan: tu integración debe ignorar lo que no conoce.

Los eventos marcados como disparador pueden iniciar una automatización sin escribir código.

Estructura de un evento

Todos los eventos llegan con la misma envoltura. Lo específico de cada uno vive en data.

Campos de la envoltura

Campo	Tipo	Descripción
`id`	string	Identificador único de la entrega. Usalo como clave de idempotencia.
`object`	string	Siempre `"event"`.
`name`	string	Nombre del evento, por ejemplo `conversation.created`.
`api_version`	string	Versión del payload con la que se generó.
`workspace_id`	string	Workspace que originó el evento.
`occurred_at`	string	Fecha ISO 8601 del momento en que ocurrió.
`data`	object	Payload propio del evento. Ver la tabla de cada uno.

event

{  "id": "evt_8f1c2a9d4b",  "object": "event",  "name": "conversation.created",  "api_version": "2026-09-01",  "workspace_id": "ws_tinkay",  "occurred_at": "2026-09-02T14:03:11.000Z",  "data": {    "id": "cv_1832",    "contact_id": "ct_juan",    "channel": "messenger"  }}

Conversaciones

Todo el ciclo de vida de una conversación: apertura, asignación, prioridad, etiquetas, SLA y cierre. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`conversation.created`	disparador · alto	Alguien abrió una conversación nueva por cualquier canal.
`conversation.assigned`	disparador · alto	La conversación pasó a una persona o a un equipo.
`conversation.unassigned`	disparador · medio	La conversación quedó sin responsable.
`conversation.claimed`	disparador · medio	Un agente tomó una conversación que estaba esperando.
`conversation.status_changed`	disparador · alto	Cambió el estado: abierta, esperando, pospuesta o cerrada.
`conversation.closed`	disparador · alto	Se cerró la conversación.
`conversation.reopened`	disparador · medio	El cliente volvió a escribir en una conversación cerrada.
`conversation.snoozed`	disparador · medio	Se pospuso hasta una fecha.
`conversation.priority_changed`	disparador · medio	Cambió la prioridad.
`conversation.tagged`	disparador · alto	Se agregó una etiqueta.
`conversation.untagged`	medio	Se quitó una etiqueta.
`conversation.rated`	disparador · medio	El cliente calificó la atención (CSAT).
`conversation.merged`	bajo	Dos conversaciones del mismo contacto se unieron.
`conversation.sla_breached`	disparador · pro · medio	Se venció el tiempo de primera respuesta o de resolución.
`conversation.participant_added`	bajo	Se sumó otro agente a la conversación.

Mensajes

Cada mensaje que entra o sale, incluidas notas internas, entregas y lecturas. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`message.created`	disparador · alto	Se envió o se recibió un mensaje.
`message.received`	disparador · alto	Mensaje entrante de un cliente.
`message.sent`	alto	Mensaje saliente de tu equipo o de la IA.
`message.delivered`	alto	El canal confirmó la entrega.
`message.read`	alto	El cliente leyó el mensaje.
`message.failed`	disparador · bajo	El canal rechazó el envío.
`message.note_created`	disparador · medio	Se agregó una nota interna, invisible para el cliente.
`message.reaction_added`	medio	Alguien reaccionó a un mensaje.

Tinkay AI

Lo que hace Tinkay AI: cuándo responde, con qué fuente, cuándo deriva, qué aprende y cuánto consume. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`ai.replied`	disparador · alto	Tinkay AI respondió en una conversación.
`ai.resolved`	disparador · alto	Tinkay AI resolvió la consulta sin intervención humana.
`ai.handoff`	disparador · alto	Tinkay AI derivó la conversación a una persona.
`ai.closed_conversation`	disparador · medio	Tinkay AI cerró la conversación después de resolverla.
`ai.action_called`	disparador · medio	Tinkay AI llamó a una acción de tu sistema.
`ai.action_failed`	disparador · bajo	Una acción devolvió error o venció el tiempo de espera.
`ai.answer_learned`	disparador · bajo	Se aprobó una respuesta aprendida: desde ahora se responde sin llamar al modelo.
`ai.answer_served`	alto	Se respondió con una respuesta aprendida, sin costo de modelo.
`ai.answer_outdated`	disparador · bajo	Cambió el artículo de origen y la respuesta aprendida quedó marcada para revisar.
`ai.training_requested`	disparador · pro · bajo	Alguien pidió aprobación para entrenar a la IA con una respuesta.
`ai.budget_threshold`	disparador · bajo	El consumo del modelo llegó al umbral configurado.
`ai.budget_exceeded`	disparador · bajo	Se agotó el presupuesto o el cupo de resoluciones del plan.
`ai.provider_changed`	bajo	Se cambió el proveedor del modelo, por ejemplo a una API propia.
`ai.provider_error`	disparador · bajo	El proveedor de IA devolvió error y se aplicó el plan alternativo.

Tickets

Casos con seguimiento: creación, estado, responsable, SLA y resolución. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`ticket.created`	disparador · medio	Se creó un ticket.
`ticket.updated`	disparador · medio	Cambió algún campo del ticket.
`ticket.status_changed`	disparador · medio	El ticket cambió de estado.
`ticket.assigned`	disparador · medio	El ticket pasó a una persona o equipo.
`ticket.resolved`	disparador · medio	Se resolvió el ticket.
`ticket.reopened`	disparador · bajo	Se reabrió un ticket resuelto.
`ticket.sla_breached`	disparador · pro · medio	Venció el SLA del ticket.
`ticket.note_added`	medio	Se agregó una nota interna al ticket.
`ticket.deleted`	bajo	Se eliminó un ticket.

Contactos

Personas que escriben: alta, identificación, atributos, segmentos y bajas. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`contact.created`	disparador · alto	Se creó un contacto.
`contact.updated`	disparador · alto	Cambiaron datos o atributos del contacto.
`contact.identified`	disparador · alto	El sitio identificó al visitante con Tinkay.identify.
`contact.merged`	bajo	Dos contactos duplicados se unieron.
`contact.tagged`	disparador · medio	Se etiquetó a un contacto.
`contact.deleted`	bajo	Se eliminó un contacto, por ejemplo por un pedido de privacidad.
`contact.segment_entered`	disparador · pro · medio	El contacto empezó a cumplir las condiciones de un segmento.
`contact.segment_left`	disparador · pro · medio	El contacto dejó de cumplir un segmento.

Empresas

Empresas agrupadas a partir de sus contactos. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`company.created`	pro · bajo	Se creó una empresa a partir de sus contactos.
`company.updated`	pro · bajo	Cambiaron datos de la empresa.

Conocimiento

Artículos, colecciones, fuentes de conocimiento y brechas detectadas. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`article.created`	bajo	Se creó un artículo, aunque sea borrador.
`article.published`	disparador · bajo	Se publicó un artículo en el centro de ayuda.
`article.updated`	disparador · medio	Se editó un artículo publicado.
`article.unpublished`	bajo	Un artículo volvió a borrador.
`article.rated`	medio	Alguien votó si el artículo fue útil.
`collection.created`	bajo	Se creó una colección.
`knowledge_source.synced`	disparador · bajo	Terminó de sincronizarse una fuente de conocimiento.
`knowledge_source.failed`	disparador · bajo	Falló la sincronización de una fuente.
`knowledge_gap.detected`	disparador · bajo	Se detectó una pregunta frecuente sin respuesta documentada.
`knowledge_gap.resolved`	bajo	Se cubrió una brecha con un artículo o una respuesta aprendida.

Datos de tu empresa

Los cuatro niveles con los que Tinkay lee datos de tu negocio: atributos firmados del Messenger, conectores HTTP en vivo, sincronización de clientes y acceso directo por réplica de solo lectura. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`attribute.detected`	disparador · medio	El Messenger mandó un atributo que Tinkay no conocía y quedó disponible para la IA.
`attribute.updated`	bajo	Cambió la configuración de un atributo: etiqueta, tipo, visibilidad para la IA o marca de sensible.
`attribute.payload_rejected`	disparador · bajo	Llegó un payload de atributos con firma inválida o campos mal formados.
`connector.called`	alto	Tinkay consultó en vivo un conector HTTP de tu sistema durante una conversación.
`connector.failed`	disparador · bajo	Un conector devolvió error, venció el tiempo de espera o no pudo mapear la respuesta.
`connector.updated`	bajo	Se creó, editó o pausó un conector HTTP.
`write_action.proposed`	disparador · medio	Tinkay propuso escribir algo en tu sistema y quedó esperando confirmación.
`write_action.confirmed`	disparador · medio	Una persona autorizó la escritura: recién ahí sale el pedido a tu sistema.
`write_action.rejected`	disparador · bajo	Alguien rechazó la escritura y nunca salió ningún pedido.
`write_action.executed`	disparador · medio	Se escribió en tu sistema: se reservó un turno, se cambió un pedido, se emitió una nota de crédito.
`write_action.failed`	disparador · bajo	Una escritura devolvió error o venció el tiempo de espera, y la conversación se derivó a una persona.
`write_action.blocked`	disparador · bajo	Una protección frenó la escritura antes de que saliera: límites, acción apagada o datos faltantes.
`write_action.reverted`	disparador · bajo	Se deshizo una escritura ejecutando la acción inversa declarada.
`write_action.updated`	bajo	Se creó, editó o pausó una acción de escritura, o cambió su nivel de confirmación.
`sync.completed`	disparador · medio	Terminó una sincronización de tu base de clientes hacia Contactos.
`sync.failed`	disparador · bajo	Falló una sincronización de clientes y no se aplicó ningún cambio.
`database.connected`	business · bajo	Se habilitó el acceso directo por réplica de solo lectura o agente de túnel.
`database.query_blocked`	disparador · business · bajo	Se bloqueó una consulta contra tu base por salir del alcance permitido.

Equipo

Miembros, equipos, roles, disponibilidad y permisos. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`member.invited`	disparador · bajo	Se invitó a alguien al workspace.
`member.joined`	disparador · bajo	La persona aceptó la invitación.
`member.role_changed`	disparador · bajo	Cambió el rol de un miembro.
`member.removed`	bajo	Se quitó a alguien del workspace.
`member.availability_changed`	disparador · alto	Un agente cambió su disponibilidad.
`team.created`	bajo	Se creó un equipo.
`team.member_added`	bajo	Se sumó una persona a un equipo.
`team.member_removed`	bajo	Se quitó una persona de un equipo.
`team.permissions_changed`	disparador · pro · bajo	El líder cambió los permisos del equipo, por ejemplo quién puede entrenar la IA.

Automatizaciones

Ejecuciones de tus flujos, con sus pasos y errores. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`automation.enabled`	bajo	Se activó una automatización.
`automation.disabled`	bajo	Se pausó una automatización.
`automation.run_started`	alto	Empezó una ejecución.
`automation.run_completed`	alto	Terminó una ejecución con éxito.
`automation.run_failed`	disparador · bajo	Falló un paso de la automatización.
`automation.goal_reached`	pro · medio	Se cumplió el objetivo definido para la automatización.

Canales

Canales y apps conectadas: altas, bajas y fallas de token. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`channel.connected`	disparador · bajo	Se conectó un canal o una app.
`channel.disconnected`	bajo	Se desconectó un canal.
`channel.error`	disparador · bajo	Un canal dejó de funcionar, por ejemplo por un token vencido.

Messenger

Comportamiento del Messenger en el sitio del cliente. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`widget.opened`	disparador · alto	Un visitante abrió el Messenger.
`widget.closed`	alto	El visitante cerró el Messenger.
`widget.article_viewed`	alto	El visitante leyó un artículo dentro del Messenger.
`widget.search_performed`	disparador · alto	El visitante buscó en el centro de ayuda desde el Messenger.
`widget.search_empty`	disparador · medio	Una búsqueda no devolvió resultados: candidata a artículo nuevo.

Facturación

Suscripción, facturas y límites de consumo. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`subscription.created`	bajo	Se activó una suscripción.
`subscription.updated`	disparador · bajo	Cambió el plan o la cantidad de asientos.
`subscription.canceled`	disparador · bajo	Se canceló la suscripción.
`invoice.paid`	bajo	Se cobró una factura.
`invoice.payment_failed`	disparador · bajo	Falló el cobro.
`usage.limit_approaching`	disparador · bajo	El consumo llegó al 80% del límite del plan.
`usage.limit_reached`	disparador · bajo	Se alcanzó un límite del plan.

Seguridad

API keys, webhooks, accesos y sesiones. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`api_key.created`	bajo	Se creó una API key.
`api_key.revoked`	disparador · bajo	Se revocó una API key.
`webhook.created`	bajo	Se registró un webhook.
`webhook.delivery_failed`	disparador · bajo	Una entrega de webhook falló después de todos los reintentos.
`webhook.disabled`	disparador · bajo	Se desactivó un webhook por fallas repetidas.
`login.succeeded`	medio	Alguien inició sesión.
`login.failed`	disparador · bajo	Intento de acceso fallido.
`session.revoked`	bajo	Se cerró una sesión activa.

Workspace

Configuración general, dominios y publicaciones. Ver el detalle de cada evento.

Campo	Tipo	Descripción
`domain.verified`	bajo	Se verificó un dominio permitido o el del centro de ayuda.
`workspace.updated`	bajo	Cambió la configuración general del workspace.
`messenger.published`	disparador · bajo	Se publicó una versión del Messenger.
`help_center.published`	bajo	Se publicó el centro de ayuda.