Conversations

search_workspace_conversations

Searches conversations by text, meaning, or both, with advanced filters, field projection, analytics, and CSV export. It fuses both signals with Reciprocal Rank Fusion (RRF) and deduplicates semantic chunks by conversation.

The available fields inside filters are:

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 can be a string/list or { any, all, none }. Other text filters accept a string or a list of up to 50 values. The default range covers the past 90 days by lastUpdate; use date_field: "creationDate" to filter by creation time.

Keep model context compact

The default response only includes:

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

Use response.fields to select from:

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 accepts 40-2000, and max_content_chars accepts 100-10000. You can also disable include_results, enable include_analytics, request include_engine_metadata, or create a temporary searchId with create_search_cache.

messages contains the available matching passage, not the conversation's complete history.

The model-facing text is a compact preview of up to 10 results and 7 columns; it never puts messages in that table. The complete JSON response, with every requested field, remains available in structuredContent.

Example

{
  "name": "search_workspace_conversations",
  "arguments": {
    "query": "customers who want to cancel because they were charged twice",
    "mode": "hybrid",
    "filters": {
      "start_date": "2026-07-01",
      "tags": { "any": ["cancellation", "billing"] },
      "platforms": ["whatsapp"]
    },
    "page_size": 10,
    "response": {
      "fields": ["id", "contactName", "topic", "snippet", "score", "sources"]
    }
  }
}

To create a file without filling context with results:

{
  "name": "search_workspace_conversations",
  "arguments": {
    "query": "cancellation request",
    "response": { "include_results": false },
    "export_csv": {
      "fields": ["id", "contactName", "phoneNumber", "topic", "lastUpdate"],
      "max_rows": 500
    }
  }
}

The preview adds a download link when export.url exists. The tool is not annotated as read-only because export_csv and create_search_cache are opt-in writes; search itself does not modify conversations.

Exports with snippet or messages support up to 100 rows; without those fields they support up to 1000, always within candidate_limit.

totalRelation: "exact" only appears for an untruncated lexical search. Hybrid and semantic results use lower_bound; inspect truncated and warnings as well. If one branch is unavailable, the other can continue.

See the complete endpoint contract for every field, limit, and response detail.

list_conversations

Lists workspace conversations. Each result includes the thread's unique id, which should be used to retrieve or update it.

id is the canonical document ID, conversationId identifies the chat thread, and clientId identifies the client. One client can have several threads. canSendDirectMessage can only be false on WhatsApp, Instagram, and Messenger/Facebook and is calculated from the latest user message; it is always true for internal Platica chats.

get_conversation

Fetches one conversation by its canonical id, including the full message history. The conversationId argument keeps the legacy phone/shared-identifier behavior and may return several threads. Use list_client_conversations to group by client.

¹ Send either id or conversationId.

update_conversation

Updates owners (owners) and/or status (status) of one exact conversation. Use id; the legacy conversationId fallback remains available and may affect several threads.

¹ Send either id or conversationId.

For internal chats, status: "active" reopens the thread. It also reactivates automatically when send_chat_message receives another message for its chat_* conversationId.

Example

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