Filtering factor in payload for conversation details /api/v2/analytics/conversations/details/query

[Urvish]

I have need to get all conversations records specific to one Contact list id & all segments within it which type is "wrapup"
I.e outboundContactListId="XXX" and segmentType="wrapup"

What is diff between predicates vs clauses?

I m getting all records where segment type is not "wrapup" also. What am I missing?

Also is it possible to get only specific property in result? for example I m not interested in "metrics","mediaEndpointStats" under "sessions" node.

in SQL terminology like select only specific fields from result based on where condition.

Select A,B,C 
From 
Table conversation_details_tables
Where outboundContactListId="XXX" and segmentType="wrapup"

I m testing at https://developer.genesys.cloud/devapps/api-explorer

following is 2 separate payload that I have tried.

{
  "segmentFilters": [
    {
      "clauses": [
        {
          "type": "and",
          "predicates": [
            {
              "type": "dimension",
              "dimension": "segmentType",
              "operator": "matches",
              "value": "wrapup"
            },
            {
              "type": "dimension",
              "dimension": "outboundContactListId",
              "operator": "matches",
              "value": "<contactlist id here>"
            }
          ]
        }
      ],
      "type": "and"
    }
  ],
  "interval": "2024-03-05T00:00:00.000/2024-03-05T23:59:00.000",
  "orderBy": "conversationEnd",
  "order": "asc",
  "paging": {
    "pageNumber": 1
  }
}

===OR
{
  "segmentFilters": [
    {
      "predicates": [
        {
          "type": "dimension",
          "dimension": "outboundContactListId",
          "operator": "matches",
          "value": "<contact list id here>"
        },
        {
          "type": "dimension",
          "dimension": "segmentType",
          "operator": "matches",
          "value": "wrapup"
        },
        {
              "type": "dimension",
              "dimension": "mediaType",
              "operator": "matches",
              "value": "voice"
            }
      ],
      "type": "and"
    }
    
  ],
  "interval": "2024-03-05T00:00:00.000/2024-03-05T23:59:00.000",
  "orderBy": "conversationEnd",
  "order": "asc",
  "paging": {
    "pageNumber": 1
  }
}

[Eos_Rios]

You are making the fundamental mistake of thinking the API behaves like SQL or a similar database concept.
It does not, cannot, and will not.

You're not providing that endpoint the criteria for what you want; You're providing it the criteria by which it will retrieve conversation objects. The entire conversation object. All of it.

To use your own example, you're not asking for segments that have a type a wrapup like you think you are, you're asking for conversations that include a wrapup segment in any of the segments. Because this is a conversation API and conversations are what are it does. It's on you to pare down to the pieces you care about.

Aggregate APIs are pretty much the only ones you get to pick and chooses pieces, and those as the name implies have to have an aggregate metric in them somewhere to work and have extreme limits on degree of granularity you can get to, making it often easier to ask for the full conversation and do your own logic than to try to make an aggregate give you something it wasn't made for.

[Urvish]

thank u for reply.
I was giving analogy to explain what I want to do and understand that what API can do to filter on that factors.
In that context...

1. What is diff between predicates vs clauses ?

2. interval parameter is apply on conversation StartDate or Enddate? does it return records between 2 conversation Start dates or between 2 end dates OR act as start of interval as conversation start and end of interval apply on Enddate?

3. how segmentFilters play role on response of API?

4. based on API signature I got that I can pass dimension & value to filter the result.
   if that is not the case in which condition all this param take in consideration?

[Eos_Rios]

1.) predicates can go inside clauses. But maybe don't have to? It's a mystery I gave up trying to understand and just do what the API says to.
2.) Read Differences to conversation detail queries
3) Let's go back to your analogy with some reality checking. The "Conversations" table the API hits is a single column table with a varchar(max) field named Conversation. Each row contains the full text of a single Conversation's JSON. Your segment filter is the equivalent of

select Conversation 
from Conversations 
where Conversation like '%segment.field = ''whatever'' %'. 

You get the entirety of every conversation that includes your criteria somewhere.

4. This will return the full conversation of every conversion with any of it's metrics meeting the filter criteria, in this case 1 or more Consult Transfer;

{
  "conversationFilters": [
    {
      "type": "and",
      "clauses": [
        {
          "type": "and",
          "predicates": [
            {
              "metric": "nConsultTransferred",
              "type": "metric",
              "range": {
                "gte": 1
              }
            }
          ]
        }
      ]
    }
  ],
  "interval": "2024-03-14T00:00:00/2024-03-15T00:00:00",
  "paging": {
    "pageSize": 10,
    "pageNumber": 1
  }
}

So again think of it as;

select Conversation 
from Conversations 
where Conversation like '%metrics.nConsultTransferred%'

Only its more like regex than a basic like because it actually checks the values against the operator & ranges.

A more specific one would be;

{
  "conversationFilters": [
    {
      "type": "and",
      "clauses": [
        {
          "type": "and",
          "predicates": [
            {
              "metric": "tTalkComplete",
              "type": "metric",
              "range": {
                "gte": 60,
                "lt": 300
              }
            }
          ]
        }
      ]
    }
  ],
  "interval": "2024-03-14T00:00:00/2024-03-15T00:00:00",
  "paging": {
    "pageSize": 10,
    "pageNumber": 1
  }
}

Which is every conversation that contains an interaction where there was at least 60 seconds of talk time but less than 5 minutes.