Exportar mensagens

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": "Olá, quero consultar o status do meu 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": "Intenção", "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": "Olá, quero consultar o status do meu 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": "Intenção", "value": "consulta_pedido" }
  ]
}

Descrição

Exporta mensagens de chat como um stream NDJSON (Newline-Delimited JSON) para análise qualitativa. Todos os IDs de pessoas são anonimizados automaticamente com HMAC-SHA256.

A resposta é um stream NDJSON (application/x-ndjson), não JSON padrão. Cada linha é um objeto JSON independente.

Header de autenticação

X-API-Key

string

obrigatório

Sua API Key do Mindo. Aceita dois tipos:

Global (cross-company): mindo_global_<key> — acesso a todas as empresas
De empresa: mindo_xxxxxxxxxxxxxxxxxxxxxxxx — acesso limitado à empresa associada

Query parameters

company_id

string

obrigatório

ID da empresa. Aceita um inteiro ou lista separada por vírgulas: 42 ou 42,57.

from

string

obrigatório

Data/hora de início (ISO-8601, inclusivo). Exemplo: 2026-04-01T00:00:00Z.

string

obrigatório

Data/hora de fim (ISO-8601, exclusivo). Deve ser maior que from. Máximo de 31 dias de intervalo.

channel

string

padrão:"all"

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

agent_id

string

Filtrar por agente IA. Um inteiro ou lista CSV: 5 ou 5,12.

direction

string

padrão:"all"

Direção da mensagem: incoming, outgoing, all.

include

string

padrão:"classifications"

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

cursor

string

Cursor de paginação obtido de next_cursor na resposta anterior.

limit

integer

padrão:"5000"

Quantidade máxima de linhas por chamada. Intervalo: 1–10000.

Resposta

A resposta é um stream NDJSON. Cada linha é um objeto JSON com os seguintes campos:

message_id

string

ID anonimizado da mensagem (msg_<24 hex chars>).

conversation_id

string

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

occurred_at

string

Timestamp ISO-8601 de quando a mensagem foi enviada.

channel

string

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

direction

string

"inbound" (do contato) ou "outbound" (do sistema/agente/operador).

author

object

Quem enviou a mensagem.

Mostrar Propriedades de author

type

string

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

string

ID anonimizado do autor (ctc_, agt_, op_ conforme o tipo). null para system.

display_name

string

Nome visível do autor. Presente apenas para agent.

agent

object

Dados do agente IA (somente se a mensagem foi gerada por um agente).

Mostrar Propriedades de agent

integer

ID real do agente IA (não anonimizado).

name

string

Nome do agente.

version

string

Versão do agente.

content

object

Conteúdo da mensagem.

Mostrar Propriedades 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

Conteúdo textual da mensagem.

media_url

string

URL do arquivo multimídia (se aplicável).

media_mime

string

MIME type da mídia (ex: image/jpeg).

context

object

Contexto da conversa.

Mostrar Propriedades de context

reply_to_message_id

string

ID anonimizado da mensagem citada (msg_<hash>).

thread_position

null

Reservado para uso futuro.

metadata

object

Dados de exportação.

Mostrar Propriedades de metadata

client_id

string

ID anonimizado da empresa (cmp_<hash>).

company_id

integer

ID real da empresa.

exported_at

string

Timestamp UTC de quando este registro foi gerado.

schema_version

string

Versão do schema ("1.0").

Campos opcionais (parâmetro `include`)

Estes campos só aparecem se solicitados no parâmetro include.

classifications

array

Classificações aplicadas à mensagem (incluído por padrão).

Mostrar Propriedades de classifications

label

string

Nome do classificador.

value

any

Resultado da classificação.

extractions

array

Dados extraídos da mensagem por extratores de campos personalizados.

Mostrar Propriedades de extractions

key

string

Nome do campo personalizado.

value

any

Valor extraído.

tool_calls

array

Ferramentas executadas pelo agente IA durante a geração da mensagem.

Mostrar Propriedades de tool_calls

tool_name

string

Nome da ferramenta.

success

boolean

Se a execução foi bem-sucedida.

execution_time_ms

integer

Tempo de execução em milissegundos.

trace_id

string

ID de rastreamento no Langfuse para debugging. Só tem valor em mensagens outgoing geradas por um agente IA.

Paginação

A paginação é baseada em cursor. Se houver mais resultados, a última linha do stream é um sentinel:

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

Envie a próxima requisição com cursor=<next_cursor> para obter a página seguinte. Quando não há sentinel, todos os dados foram retornados.

Anonimização de IDs

Prefixo	Representa
`msg_`	ID da mensagem
`conv_`	ID da conversa
`ctc_`	ID do contato
`agt_`	ID do agente (em author)
`op_`	ID do operador humano
`cmp_`	ID da empresa (em metadata)

A anonimização é determinística por empresa, irreversível e consistente entre exportações.

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": "Olá, quero consultar o status do meu 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": "Intenção", "value": "consulta_pedido" }
  ]
}

Mapeamento de canais

Valor do parâmetro `channel`	Plataformas incluídas
`whatsapp`	META_WHATSAPP, WHATSAPP_EVOLUTION, MANYCHAT_WHATSAPP
`instagram`	INSTAGRAM, MANYCHAT_INSTAGRAM
`messenger`	MESSENGER
`all`	Todas as plataformas

Erros mid-stream

Se ocorrer um erro após o stream já ter iniciado, ele é emitido como uma linha NDJSON adicional:

{"_error": {"code": "ERROR_CODE", "message": "descrição do erro"}}

Limites

Restrição	Valor
Intervalo máximo de datas	31 dias
Máximo de linhas por requisição	10.000
Padrão de linhas por requisição	5.000
Mensagens excluídas	Excluídas automaticamente

Casos de uso

Análise de qualidade das respostas dos agentes

Exportar apenas mensagens outgoing de um agente específico com tool_calls para avaliar quais ferramentas foram usadas e com qual sucesso:

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 treinamento para classificadores

Exportar mensagens incoming com suas classificações para avaliar ou retreinar 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

Auditoria cross-platform

Exportar todas as mensagens de múltiplas empresas para auditoria 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 com Langfuse

Exportar mensagens com trace_id para correlacionar com rastreamentos no 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 envios em massa

​Descrição

​Header de autenticação

​Query parameters

​Resposta

​Campos opcionais (parâmetro include)

​Paginação

​Anonimização de IDs

​Mapeamento de canais

​Erros mid-stream

​Limites

​Casos de uso

Descrição

Header de autenticação

Query parameters

Resposta

Campos opcionais (parâmetro `include`)

Paginação

Anonimização de IDs

Mapeamento de canais

Erros mid-stream

Limites

Casos de uso