Exportar mensajes - Mindo API

curl -s \
  -H "X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.mindosoftware.com/api/v1/qualitative-export/messages?company_id=42&from=2026-04-01T00:00:00Z&to=2026-04-07T00:00:00Z"

{
  "message_id": "msg_a1b2c3d4e5f6a1b2c3d4e5f6",
  "conversation_id": "conv_f6e5d4c3b2a1f6e5d4c3b2a1",
  "occurred_at": "2026-04-05T12:30:45.123456",
  "channel": "META_WHATSAPP",
  "direction": "inbound",
  "author": {
    "type": "contact",
    "id": "ctc_a1b2c3d4e5f6a1b2c3d4e5f6",
    "display_name": null
  },
  "agent": null,
  "content": {
    "type": "text",
    "text": "Hola, quiero consultar el estado de mi pedido",
    "media_url": null,
    "media_mime": null
  },
  "context": {
    "reply_to_message_id": null,
    "thread_position": null
  },
  "metadata": {
    "client_id": "cmp_d4c3b2a1f6e5d4c3b2a1f6e5",
    "company_id": 42,
    "exported_at": "2026-05-05T18:30:00.000000Z",
    "schema_version": "1.0"
  },
  "classifications": [
    { "label": "Intención", "value": "consulta_pedido" }
  ]
}

GET

api

qualitative-export

messages

curl -s \
  -H "X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.mindosoftware.com/api/v1/qualitative-export/messages?company_id=42&from=2026-04-01T00:00:00Z&to=2026-04-07T00:00:00Z"

{
  "message_id": "msg_a1b2c3d4e5f6a1b2c3d4e5f6",
  "conversation_id": "conv_f6e5d4c3b2a1f6e5d4c3b2a1",
  "occurred_at": "2026-04-05T12:30:45.123456",
  "channel": "META_WHATSAPP",
  "direction": "inbound",
  "author": {
    "type": "contact",
    "id": "ctc_a1b2c3d4e5f6a1b2c3d4e5f6",
    "display_name": null
  },
  "agent": null,
  "content": {
    "type": "text",
    "text": "Hola, quiero consultar el estado de mi pedido",
    "media_url": null,
    "media_mime": null
  },
  "context": {
    "reply_to_message_id": null,
    "thread_position": null
  },
  "metadata": {
    "client_id": "cmp_d4c3b2a1f6e5d4c3b2a1f6e5",
    "company_id": 42,
    "exported_at": "2026-05-05T18:30:00.000000Z",
    "schema_version": "1.0"
  },
  "classifications": [
    { "label": "Intención", "value": "consulta_pedido" }
  ]
}

Descripción

Exporta mensajes de chat como un stream NDJSON (Newline-Delimited JSON) para análisis cualitativo. Todos los IDs de personas se anonimizan automáticamente con HMAC-SHA256.

La respuesta es un stream NDJSON (application/x-ndjson), no JSON estándar. Cada línea es un objeto JSON independiente.

Header de autenticación

X-API-Key

string

requerido

Tu API Key de Mindo. Acepta dos tipos:

Global (cross-company): mindo_global_<key> — acceso a todas las empresas
De empresa: mindo_xxxxxxxxxxxxxxxxxxxxxxxx — acceso limitado a la empresa asociada

Query parameters

company_id

string

requerido

ID de empresa. Acepta un entero o lista separada por comas: 42 o 42,57.

from

string

requerido

Fecha/hora de inicio (ISO-8601, inclusive). Ejemplo: 2026-04-01T00:00:00Z.

string

requerido

Fecha/hora de fin (ISO-8601, exclusivo). Debe ser mayor que from. Máximo 31 días de rango.

channel

string

predeterminado:"all"

Filtro de plataforma: whatsapp, instagram, messenger, all.

agent_id

string

Filtrar por agente IA. Un entero o lista CSV: 5 o 5,12.

direction

string

predeterminado:"all"

Dirección del mensaje: incoming, outgoing, all.

include

string

predeterminado:"classifications"

Campos extras a incluir (CSV): classifications, extractions, tool_calls, trace_id.

cursor

string

Cursor de paginación obtenido de next_cursor en la respuesta anterior.

limit

integer

predeterminado:"5000"

Cantidad máxima de filas por llamada. Rango: 1–10000.

Respuesta

La respuesta es un stream NDJSON. Cada línea es un objeto JSON con los siguientes campos:

message_id

string

ID anonimizado del mensaje (msg_<24 hex chars>).

conversation_id

string

ID anonimizado del chat (conv_<24 hex chars>).

occurred_at

string

Timestamp ISO-8601 de cuándo se envió el mensaje.

channel

string

Plataforma: META_WHATSAPP, WHATSAPP_EVOLUTION, INSTAGRAM, MESSENGER, MANYCHAT_WHATSAPP, MANYCHAT_INSTAGRAM.

direction

string

"inbound" (del contacto) o "outbound" (del sistema/agente/operador).

author

object

Quién envió el mensaje.

Mostrar Propiedades de author

type

string

Tipo de autor: contact, agent, human_operator, system.

string

ID anonimizado del autor (ctc_, agt_, op_ según tipo). null para system.

display_name

string

Nombre visible del autor. Solo presente para agent.

agent

object

Datos del agente IA (solo si el mensaje fue generado por un agente).

Mostrar Propiedades de agent

integer

ID real del agente IA (no anonimizado).

name

string

Nombre del agente.

version

string

Versión del agente.

content

object

Contenido del mensaje.

Mostrar Propiedades de content

type

string

Tipo: text, image, video, audio, file, sticker, location, contact, system, notification_template, carousel, story_mention, story_reply, ice_breaker_response.

text

string

Contenido textual del mensaje.

media_url

string

URL del archivo multimedia (si aplica).

media_mime

string

MIME type del media (ej: image/jpeg).

context

object

Contexto de la conversación.

Mostrar Propiedades de context

reply_to_message_id

string

ID anonimizado del mensaje citado (msg_<hash>).

thread_position

null

Reservado para uso futuro.

metadata

object

Datos de exportación.

Mostrar Propiedades de metadata

client_id

string

ID anonimizado de la empresa (cmp_<hash>).

company_id

integer

ID real de la empresa.

exported_at

string

Timestamp UTC de cuándo se generó este registro.

schema_version

string

Versión del schema ("1.0").

Campos opcionales (parámetro `include`)

Estos campos solo aparecen si se solicitan en el parámetro include.

classifications

array

Clasificaciones aplicadas al mensaje (incluido por defecto).

Mostrar Propiedades de classifications

label

string

Nombre del clasificador.

value

any

Resultado de la clasificación.

extractions

array

Datos extraídos del mensaje por extractores de custom fields.

Mostrar Propiedades de extractions

key

string

Nombre del custom field.

value

any

Valor extraído.

tool_calls

array

Herramientas ejecutadas por el agente IA durante la generación del mensaje.

Mostrar Propiedades de tool_calls

tool_name

string

Nombre de la herramienta.

success

boolean

Si la ejecución fue exitosa.

execution_time_ms

integer

Tiempo de ejecución en milisegundos.

trace_id

string

ID de traza en Langfuse para debugging. Solo tiene valor en mensajes outgoing generados por un agente IA.

Paginación

La paginación es cursor-based. Si hay más resultados, la última línea del stream es un sentinel:

{"_truncated": true, "next_cursor": "<cursor_string>"}

Envía la siguiente request con cursor=<next_cursor> para obtener la página siguiente. Cuando no hay sentinel, se agotaron todos los datos.

Anonimización de IDs

Prefijo	Representa
`msg_`	ID de mensaje
`conv_`	ID de conversación
`ctc_`	ID de contacto
`agt_`	ID de agente (en author)
`op_`	ID de operador humano
`cmp_`	ID de empresa (en metadata)

La anonimización es determinista por empresa, irreversible y consistente entre exportaciones.

curl -s \
  -H "X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.mindosoftware.com/api/v1/qualitative-export/messages?company_id=42&from=2026-04-01T00:00:00Z&to=2026-04-07T00:00:00Z"

{
  "message_id": "msg_a1b2c3d4e5f6a1b2c3d4e5f6",
  "conversation_id": "conv_f6e5d4c3b2a1f6e5d4c3b2a1",
  "occurred_at": "2026-04-05T12:30:45.123456",
  "channel": "META_WHATSAPP",
  "direction": "inbound",
  "author": {
    "type": "contact",
    "id": "ctc_a1b2c3d4e5f6a1b2c3d4e5f6",
    "display_name": null
  },
  "agent": null,
  "content": {
    "type": "text",
    "text": "Hola, quiero consultar el estado de mi pedido",
    "media_url": null,
    "media_mime": null
  },
  "context": {
    "reply_to_message_id": null,
    "thread_position": null
  },
  "metadata": {
    "client_id": "cmp_d4c3b2a1f6e5d4c3b2a1f6e5",
    "company_id": 42,
    "exported_at": "2026-05-05T18:30:00.000000Z",
    "schema_version": "1.0"
  },
  "classifications": [
    { "label": "Intención", "value": "consulta_pedido" }
  ]
}

Mapeo de canales

Valor del parámetro `channel`	Plataformas incluidas
`whatsapp`	META_WHATSAPP, WHATSAPP_EVOLUTION, MANYCHAT_WHATSAPP
`instagram`	INSTAGRAM, MANYCHAT_INSTAGRAM
`messenger`	MESSENGER
`all`	Todas las plataformas

Errores mid-stream

Si ocurre un error después de que el stream ya comenzó, se emite como una línea NDJSON adicional:

{"_error": {"code": "ERROR_CODE", "message": "descripción del error"}}

Límites

Restricción	Valor
Rango máximo de fechas	31 días
Máximo de filas por request	10,000
Default de filas por request	5,000
Mensajes eliminados	Excluidos automáticamente

Casos de uso

Análisis de calidad de respuestas de agentes

Exportar solo mensajes outgoing de un agente específico con tool_calls para evaluar qué herramientas usó y con qué éxito:

GET /api/v1/qualitative-export/messages?company_id=42&from=2026-04-01T00:00:00Z&to=2026-04-07T00:00:00Z&agent_id=5&direction=outgoing&include=classifications,tool_calls,trace_id

Dataset de entrenamiento para clasificadores

Exportar mensajes incoming con sus clasificaciones para evaluar o reentrenar modelos:

GET /api/v1/qualitative-export/messages?company_id=42&from=2026-04-01T00:00:00Z&to=2026-04-30T00:00:00Z&direction=incoming&include=classifications,extractions

Auditoría cross-platform

Exportar todos los mensajes de múltiples empresas para auditoría comparativa:

GET /api/v1/qualitative-export/messages?company_id=42,57&from=2026-04-01T00:00:00Z&to=2026-04-07T00:00:00Z&include=classifications

Debugging de agentes con Langfuse

Exportar mensajes con trace_id para correlacionar con trazas en Langfuse:

GET /api/v1/qualitative-export/messages?company_id=42&from=2026-04-05T10:00:00Z&to=2026-04-05T12:00:00Z&include=tool_calls,trace_id

Listar envíos masivos

​Descripción

​Header de autenticación

​Query parameters

​Respuesta

​Campos opcionales (parámetro include)

​Paginación

​Anonimización de IDs

​Mapeo de canales

​Errores mid-stream

​Límites

​Casos de uso

Descripción

Header de autenticación

Query parameters

Respuesta

Campos opcionales (parámetro `include`)

Paginación

Anonimización de IDs

Mapeo de canales

Errores mid-stream

Límites

Casos de uso