Observation activity query endpoints

Observation activity queries show the current state of a queue, user, flow or team. The query syntax is similar to the existing queue and user observation endpoints but allows more flexible filtering.

Query endpoints

We currently offer the following activity query endpoints:

/api/v2/analytics/conversations/activity/query: Query for ongoing (oInteracting) and waiting (oWaiting) queue interactions
/api/v2/analytics/flows/activity/query: Query for ongoing flows (oFlow)
/api/v2/analytics/users/activity/query: Query for ongoing user queue membership (oMemberQueues, oActiveQueues)
/api/v2/analytics/routing/activity/query: Query for users in a queue (oMemberUsers, oActiveUsers) and their current presence ( oOnQueueUsers, oUserPresences) and routing statuses (oUserRoutingStatuses, oOffQueueUsers)
/api/v2/analytics/teams/activity/query: Query for users in a teams current presence ( oTeamOnQueueUsers, oTeamPresences) and routing statuses (oTeamRoutingStatuses, oTeamOffQueueUsers)

Query syntax

All query endpoints support the same query syntax.

Example query:

POST https://api.mypurecloud.com/api/v2/analytics/routing/activity/query

{
  "metrics": [{
      "name": "oUserRoutingStatuses",
      "details": true
    },
    {
      "name": "oUserPresences"
    }
  ],
  "groupBy": ["queueId"],
  "filter": {
    "type": "and",
    "clauses": [{
      "type": "and",
      "predicates": [{
          "dimension": "queueId",
          "value": "b8626ee0-c21d-4895-bc43-15262f356fdc"
        },
        {
          "dimension": "routingStatus",
          "value": "INTERACTING"
        }
      ]
    }]
  },
  "order": "asc"
}

Query filtering and grouping

Query filtering works the same way as for the existing observation endpoints - only with much more flexibility. Any dimension that is included in the data can be used for filtering, e.g. routingStatus or userId for routing activity. Results are grouped based on the specified groupBy. All endpoints require at least on group-by. A routing query must include a grouping by queueId and a users query must include a grouping by userId.

Metrics

Metrics have to be specified or the query will be rejected. You can optionally request metric details which will add a section with matching entities to the query response. If you request details, these will be paged with a default page size of 50 and a maximum page size of 100. Page size and page number can be specified via the optional path parameters pageSize and pageNumber. The ordering can be changed by setting order to asc for ascending (default) by timestamp and desc for descending.

Example response

Query response

{
  "results": [{
    "group": {
      "queueId": "b8626ee0-c21d-4895-bc43-15262f356fdc"
    },
    "data": [{
        "metric": "oUserRoutingStatuses",
        "qualifier": "INTERACTING",
        "entityIds": [
          "cfdac4c8-4985-4f15-8541-9d20b6bcfca3"
        ],
        "count": 1
      },
      {
        "metric": "oUserPresences",
        "qualifier": "ccf3c10a-aa2c-4845-8e8d-f59fa48c58e5",
        "secondaryQualifier": "ON_QUEUE",
        "count": 1
      }
    ],
    "truncated": false,
    "entities": [{
      "activityDate": "2020-08-19T19:25:35.927Z",
      "systemPresence": "ON_QUEUE",
      "presenceDate": "2020-08-19T19:25:35.927Z",
      "queueMembershipStatus": "active",
      "organizationPresenceId": "ccf3c10a-aa2c-4845-8e8d-f59fa48c58e5",
      "routingStatus": "INTERACTING",
      "userId": "1111c4c8-4985-4f15-8541-9d20b6bc1111",
      "routingStatusDate": "2020-08-19T19:08:57.040Z"
    }]
  }],
  "entityIdDimension": "userId"
}

If metric details are requested, the metric data will include a list of entitiyIds that link to the included entity details. The entity id dimension depends on the endpoint and is included in the query result under entityIdDimension.

Furthermore, routing status metrics (oUserRoutingStatuses, oOffQueueUsers) include the routing status as a metric qualifier. Presence metrics (oOnQueueUsers, oUserPresences) include the organization presence id as a qualifier and the system presence as a secondaryQualifier.

Supported dimensions

Conversation Activity Dimensions

Dimension	Type	Description	Preview
activeRouting	Enum (Bullseye, Conditional, Direct, Last, Manual, Predictive, Preferred, Standard, Vip)	Active routing method.	✔
addressFrom	String	The address that initiated an action.
addressTo	String	The address receiving an action.
agentScore	Integer	Assigned agent score for this conversation (0 - 100, higher being better).
ani	String	Automatic Number Identification (caller's number).
conversationId	UUID	Unique identifier for the conversation.
convertedFrom	String	Session media type that was converted from in case of a media type conversion.
convertedTo	String	Session media type that was converted to in case of a media type conversion.
direction	Enum (inbound, outbound)	The direction of the communication.
dnis	String	Dialed number identification service (number dialed by the calling party).
mediaType	Enum (callback, chat, cobrowse, email, internalmessage, message, screenshare, unknown, video, voice)	The session media type.
participantName	String	A human readable name identifying the participant.
queueId	UUID	Queue identifier.
requestedLanguageId	UUID	Unique identifier for the language requested for an interaction.
requestedRouting	Enum (Bullseye, Conditional, Direct, Last, Manual, Predictive, Preferred, Standard, Vip)	Routing type(s) for requested/attempted routing methods.
requestedRoutingSkillId	UUID	Unique identifier(s) for skill(s) requested for an interaction.
routingPriority	Long	Routing priority for the current interaction.
scoredAgentId	UUID	Unique identifier for the agent that was scored for this conversation.
sessionId	UUID	The unique identifier of this session.
teamId	UUID	The team ID the user is a member of.
usedRouting	Enum (Bullseye, Conditional, Direct, Last, Manual, Predictive, Preferred, Standard, Vip)	Complete routing method.
userId	UUID	Unique identifier for the user.

Flow Activity Dimensions

Dimension	Type	Description	Preview
activeRouting	Enum (Bullseye, Conditional, Direct, Last, Manual, Predictive, Preferred, Standard, Vip)	Active routing method.	✔
addressFrom	String	The address that initiated an action.
addressTo	String	The address receiving an action.
agentScore	Integer	Assigned agent score for this conversation (0 - 100, higher being better).
ani	String	Automatic Number Identification (caller's number).
conversationId	UUID	Unique identifier for the conversation.
convertedFrom	String	Session media type that was converted from in case of a media type conversion.
convertedTo	String	Session media type that was converted to in case of a media type conversion.
direction	Enum (inbound, outbound)	The direction of the communication.
dnis	String	Dialed number identification service (number dialed by the calling party).
flowType	Enum (bot, commonmodule, digitalbot, inboundcall, inboundchat, inboundemail, inboundshortmessage, inqueuecall, inqueueemail, inqueueshortmessage, outboundcall, securecall, speech, surveyinvite, voice, voicemail, voicesurvey, workflow, workitem)	The type of this flow.
mediaType	Enum (callback, chat, cobrowse, email, internalmessage, message, screenshare, unknown, video, voice)	The session media type.
participantName	String	A human readable name identifying the participant.
queueId	UUID	Queue identifier.
requestedLanguageId	UUID	Unique identifier for the language requested for an interaction.
requestedRouting	Enum (Bullseye, Conditional, Direct, Last, Manual, Predictive, Preferred, Standard, Vip)	Routing type(s) for requested/attempted routing methods.
requestedRoutingSkillId	UUID	Unique identifier(s) for skill(s) requested for an interaction.
routingPriority	Long	Routing priority for the current interaction.
scoredAgentId	UUID	Unique identifier for the agent that was scored for this conversation.
sessionId	UUID	The unique identifier of this session.
teamId	UUID	The team ID the user is a member of.
usedRouting	Enum (Bullseye, Conditional, Direct, Last, Manual, Predictive, Preferred, Standard, Vip)	Complete routing method.
userId	UUID	Unique identifier for the user.

User Activity Dimensions

Dimension	Type	Description	Preview
organizationPresenceId	UUID	Organization presence identifier.
presenceDate	DateTime	Date of the latest presence change.
queueId	UUID	Queue identifier.
queueMembershipStatus	String	Queue membership status (e.g. active or inactive).
routingStatus	String	Agent routing status.
routingStatusDate	DateTime	Date of the latest routing status change.
systemPresence	String	System presence.
teamId	UUID	The team ID the user is a member of.
userId	UUID	Unique identifier for the user.

Routing Activity Dimensions

Dimension	Type	Description	Preview
organizationPresenceId	UUID	Organization presence identifier.
presenceDate	DateTime	Date of the latest presence change.
queueId	UUID	Queue identifier.
queueMembershipStatus	String	Queue membership status (e.g. active or inactive).
routingStatus	String	Agent routing status.
routingStatusDate	DateTime	Date of the latest routing status change.
systemPresence	String	System presence.
teamId	UUID	The team ID the user is a member of.
userId	UUID	Unique identifier for the user.

Frequent use cases

Longest waiting/interacting conversation

You can determine the longest waiting or interacting conversation on a queue with a conversation activity query with details enabled.

Example query for longest waiting:

POST https://api.mypurecloud.com/api/v2/analytics/conversation/activity/query?pageSize=1

{
"metrics": [{
"name": "oWaiting",
"details": true
}
],
"groupBy": ["queueId"],
"filter": {
"type": "and",
"clauses": [{
"type": "and",
"predicates": [{
"dimension": "queueId",
"value": "12345678-c21d-4895-bc43-15262f356fdc"
}
]
}]
}
}

If this queue has waiting conversations, the activityDate can be used to calculate how long the oldest conversation has been waiting. If you are interested in interacting conversations, substitute oWaiting with oInteracting.

Longest idle agent on queue

You can determine which agent has been idle for the longest amount of time with a routing activity query by filtering on routingStatus IDLE.

POST https://api.mypurecloud.com/api/v2/analytics/routing/activity/query?pageSize=1

{
"metrics": [{
"name": "oUserRoutingStatuses",
"details": true
}
],
"groupBy": ["queueId"],
"filter": {
"type": "and",
"clauses": [{
"type": "and",
"predicates": [{
"dimension": "queueId",
"value": "12345678-c21d-4895-bc43-15262f356fdc"
},
{
"dimension": "routingStatus",
"value": "IDLE"
}
]
}]
}
}