Buscar conversaciones

Busca en las conversaciones del workspace por coincidencia textual, similitud semántica o ambas. El modo híbrido fusiona las dos señales, elimina fragmentos duplicados de una misma conversación y permite controlar exactamente qué campos regresan en la respuesta.

POST https://api.platica.mx/v1/search/conversations

Cuerpo de la solicitud

{
  "query": "el cliente quiere cancelar porque el cobro se duplicó",
  "mode": "hybrid",
  "filters": {
    "start_date": "2026-07-01",
    "tags": { "any": ["cancelación", "facturación"], "none": ["prueba"] },
    "platforms": ["whatsapp", "instagram"],
    "is_finished": true
  },
  "page_size": 20,
  "response": {
    "fields": ["id", "contactName", "topic", "tags", "snippet", "score", "sources"]
  }
}

Modos de búsqueda

En modo hybrid, query también se usa como consulta semántica cuando no envías semantic_queries. Si no hay ninguna consulta semántica, la búsqueda continúa sólo con la rama léxica y lo indica en warnings. Si envías semantic_queries sin query, se omite la rama léxica para no mezclar coincidencias semánticas con un listado general por recencia.

Filtros

Cada filtro de texto acepta un string o un arreglo de hasta 50 strings. Los filtros se aplican al resultado de ambos motores.

Ranking híbrido

{
  "ranking": {
    "lexical_weight": 0.65,
    "semantic_weight": 0.35,
    "rrf_k": 60
  }
}

Cada peso acepta valores de 0 a 1; en modo híbrido al menos uno debe ser mayor que cero. RRF combina la posición de cada conversación en ambas ramas, en lugar de comparar directamente sus escalas de relevancia. Los fragmentos semánticos se deduplican por id de conversación antes de ordenar.

El campo score final está normalizado entre 0 y 1. Solicita sources para saber qué motores encontraron el resultado y scores para inspeccionar lexicalRank, lexicalTextMatch, semanticRank y semanticDistance.

Controlar el tamaño de la respuesta

La proyección por defecto no incluye mensajes, teléfono ni correo:

{
  "response": {
    "fields": [
      "id", "contactName", "platform", "topic", "tags",
      "lastUpdate", "snippet", "conversationUrl", "score", "sources"
    ],
    "include_results": true,
    "include_analytics": false,
    "include_engine_metadata": false,
    "create_search_cache": false,
    "max_snippet_chars": 320,
    "max_content_chars": 2000
  }
}

fields acepta:

id, conversationId, contactName, phoneNumber, email, platform, topic, tags,
status, agent, channelId, clientId, operation, owners, isFinished, creationDate,
lastUpdate, snippet, messages, conversationUrl, contactUrl, score, sources, scores

Exportar CSV

Envía "export_csv": true para exportar las coincidencias de la ventana de candidatos con la selección de columnas predeterminada, o controla ambas opciones:

{
  "query": "solicitud de cancelación",
  "response": { "include_results": false },
  "export_csv": {
    "fields": ["id", "contactName", "phoneNumber", "topic", "lastUpdate", "conversationUrl"],
    "max_rows": 500
  }
}

max_rows limita las filas exportadas, pero no amplía candidate_limit. Las exportaciones que incluyen snippet o messages se limitan a 100 filas; sin esos campos pueden incluir hasta 1000.

La respuesta incluye export.url, filename, rowCount, sizeBytes, truncated y expiresAt. downloadUrl contiene la misma URL por compatibilidad. El archivo es privado, la URL firmada vence en 7 días y sus celdas se protegen contra fórmulas de hoja de cálculo.

Respuesta

{
  "success": true,
  "mode": "hybrid",
  "matchCount": 42,
  "candidateCount": 42,
  "totalFound": 42,
  "totalRelation": "lower_bound",
  "returnedCount": 2,
  "truncated": false,
  "fields": ["id", "contactName", "topic", "snippet", "score", "sources"],
  "results": [
    {
      "id": "conv_7a19",
      "contactName": "María López",
      "topic": "Facturación",
      "snippet": "...solicito cancelar porque aparece un cobro duplicado...",
      "score": 0.967213,
      "sources": ["lexical", "semantic"]
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "pageSize": 10,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "candidateWindow": 250
  },
  "tookMs": 183
}

La página solicitada debe caber dentro de candidate_limit. La ventana máxima es de 1000 conversaciones y permanece fija para conservar el orden al paginar.

Disponibilidad de motores

Si una rama solicitada no está disponible y la otra sí, el endpoint continúa con la disponible, reajusta el ranking y agrega una entrada en warnings. Activa response.include_engine_metadata al diagnosticar integraciones; evita habilitarlo por defecto si quieres minimizar el contexto.