Conversaciones

search_workspace_conversations

Busca conversaciones por texto, significado o ambos, con filtros avanzados, proyección de campos, analítica y exportación CSV. Fusiona ambas señales con Reciprocal Rank Fusion (RRF) y deduplica los fragmentos semánticos por conversación.

Los filtros disponibles dentro de filters son:

start_date, end_date, date_field, tags, platforms, topics, statuses, agents,
channel_ids, operations, owner_ids, conversation_ids, client_ids, phone_numbers,
has_phone, is_finished

tags puede ser un string/lista o { any, all, none }. Los demás filtros de texto aceptan un string o una lista de hasta 50 valores. El rango predeterminado cubre los últimos 90 días según lastUpdate; usa date_field: "creationDate" para filtrar por creación.

Mantener compacto el contexto

La respuesta predeterminada incluye sólo:

id, contactName, platform, topic, tags, lastUpdate, snippet,
conversationUrl, score, sources

Usa response.fields para elegir entre:

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

response.max_snippet_chars acepta 40-2000 y max_content_chars acepta 100-10000. También puedes desactivar include_results, activar include_analytics, solicitar include_engine_metadata o crear un searchId temporal con create_search_cache.

messages contiene el pasaje coincidente disponible, no el historial completo de la conversación.

El texto que ve el modelo es un preview compacto de hasta 10 resultados y 7 columnas; nunca coloca messages en esa tabla. La respuesta JSON completa, con todos los campos que pediste, queda disponible en structuredContent.

Ejemplo

{
  "name": "search_workspace_conversations",
  "arguments": {
    "query": "clientes que quieren cancelar por cobro duplicado",
    "mode": "hybrid",
    "filters": {
      "start_date": "2026-07-01",
      "tags": { "any": ["cancelación", "facturación"] },
      "platforms": ["whatsapp"]
    },
    "page_size": 10,
    "response": {
      "fields": ["id", "contactName", "topic", "snippet", "score", "sources"]
    }
  }
}

Para crear un archivo sin llenar el contexto con resultados:

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

El preview agrega un enlace de descarga cuando existe export.url. La anotación del tool no es de sólo lectura porque export_csv y create_search_cache son escrituras opt-in; la búsqueda por sí sola no modifica conversaciones.

Las exportaciones con snippet o messages admiten hasta 100 filas; sin esos campos admiten hasta 1000, siempre dentro de candidate_limit.

totalRelation: "exact" sólo aparece en una búsqueda léxica no truncada. En resultados híbridos o semánticos es lower_bound; revisa también truncated y warnings. Si una rama no está disponible, la otra puede continuar.

Consulta el contrato completo del endpoint para ver todos los campos, límites y la respuesta.

list_conversations

Lista conversaciones del workspace agrupadas. Cada resultado trae el id único del hilo, que debe usarse para obtenerlo o actualizarlo.

id es el ID canónico del documento, conversationId identifica el hilo de chat y clientId identifica al cliente. Un cliente puede tener varios hilos. canSendDirectMessage solo puede ser false en WhatsApp, Instagram y Messenger/Facebook y se calcula desde el último mensaje del usuario; en chats internos de Platica siempre es true.

get_conversation

Obtiene una conversación por su id canónico, incluyendo todo el historial. Busca en todos los workspaces de la API Key. El argumento conversationId conserva el comportamiento legacy (teléfono/identificador compartido) y puede devolver varios hilos; para agrupar por cliente usa list_client_conversations.

¹ Envía id o conversationId.

update_conversation

Actualiza dueños (owners) y/o estado (status) de una conversación exacta. Usa id; el argumento conversationId queda disponible como fallback legacy y puede afectar varios hilos.

¹ Envía id o conversationId.

En chats internos, status: "active" reabre el hilo. También se reactiva automáticamente cuando send_chat_message recibe otro mensaje para su conversationId chat_*.

Ejemplo

{
  "name": "update_conversation",
  "arguments": {
    "id": "conversation_doc_id",
    "status": "finished",
    "owners": ["ana@miempresa.com"]
  }
}