Niucore

Documentación

Modo incógnito

Qué significa el campo `anonymization` y cómo afecta a un turno de la API.

NiuCore puede sustituir datos personales por marcadores antes de que el texto salga hacia el proveedor del modelo, y reponerlos en la respuesta. Es el modo incógnito, y desde la API se nota en un solo lugar: el campo anonymization de un mensaje.

No se activa desde la API

Lo decide la empresa, no el integrador. El cuerpo de un turno no acepta un campo anonymize: mandarlo devuelve 422. Que la privacidad de una organización dependa de si el cliente se acordó de pedirla sería un mal diseño.

Qué ves desde la API

El texto que mandás y el que recibís están en claro. La sustitución ocurre por dentro, entre NiuCore y el proveedor del modelo, y se deshace antes de contestarte.

Cuando la empresa lo tiene activo, el mensaje trae además qué se sustituyó:

JSON
{
  "id": 90213,
  "content": "Le escribimos a María Rossi a maria@example.com.",
  "anonymization": {
    "enabled": true,
    "replacements": [
      { "original": "María Rossi", "placeholder": "⟦Nombre#a91f3c⟧", "category": "Nombre" },
      { "original": "maria@example.com", "placeholder": "⟦Correo#7d20be⟧", "category": "Correo" }
    ]
  }
}
Valor de `anonymization`Significa
nullEl turno no pasó por el modo incógnito.
{ "enabled": true, "replacements": [] }El modo estaba activo y no se detectó nada que sustituir.
{ "enabled": true, "replacements": [ … ] }Se sustituyó lo que lista. Los marcadores tienen la forma ⟦Categoría#hash⟧.

Atención

replacements contiene los valores originales: es exactamente el dato que el modo incógnito existe para proteger. Si guardás la respuesta completa, estás guardando esos valores. Tratá ese campo con el mismo cuidado que trataría tu organización a un dato personal.

Herramientas y conectores

Las herramientas externas —Gmail, Drive, Calendar— reciben los argumentos desanonimizados: un correo tiene que llegar a la dirección real, no a un marcador. Lo que veas en el payload de una interacción tool_approval es lo que la herramienta va a recibir de verdad.

Las herramientas internas de NiuCore siguen operando en el espacio anonimizado, a propósito: nunca necesitan el valor real para hacer su trabajo.

Documentos y búsquedas

El contenido indexado de las bibliotecas no se anonimiza: la búsqueda tiene que funcionar sobre el texto real para encontrar lo que el usuario busca. Lo que se protege es el egreso hacia el proveedor del modelo, que es donde el dato saldría de la organización.

Qué hacer en tu integración

  • Tratá anonymization como informativo. No cambia la forma de la respuesta ni te obliga a nada.
  • Si tu sistema hace su propio registro de datos personales, replacements te dice qué detectó NiuCore en ese turno — puede servirte como señal.
  • No dependas de que esté presente: una empresa puede tener el modo apagado, y ahí el campo es null siempre.
  • Si vas a persistir respuestas, decidí explícitamente si guardás replacements o lo descartás. Es una decisión de privacidad, no un detalle de serialización.