Conversation Details from Analytics API

Platform API .NET SDK
1

Hi All.

I'm looking for the following conversation data, but it isn't obvious to me where in returned results I can find these out:

  1. Who the call was from, and to (related, whether the call was inbound to or outbound)
  2. Who answered/placed the call
  3. The reason for the call (IVR selection)
  4. Call duration, with breakdown if there are some phases that the call passes through
  5. Some information about how the call concluded – wrap up codes and notes

I think my biggest issue here is that I can’t find meaningful documentation about the returned fields. For example: on AnalyticsSession, but there is nothing for Description for all of the properties. Should I be looking elsewhere in the documentation to understand the returned conversation details?

2

You can read more about conversations in the Conversations Overview. To answer your specific questions:

Who the call was from, and to (related, whether the call was inbound to or outbound)

Look at the participants. Each participant will have sessions that indicate participation in a conversation. The purpose property tells you what the participant is (customer, user, agent, ivr, etc.). The direction property on the session tells you if the direction of that call. For example, a participant with purpose==customer and a session with direction==inbound tells you that an external caller called in. The session also contains properties for the ANI and DNIS.

Who answered/placed the call

This is determined by inspecting the participants and the properties mentioned above.

The reason for the call (IVR selection)

There isn't anything OOTB on the conversation that will tell you anything about what happened in the IVR. However, you can use Architect's Set Participant Data action to set some value on the participant that you can derive some meaning from later.

Call duration, with breakdown if there are some phases that the call passes through

Call duration is derived from looking at the segment start and end times for each participant. The "phases" of the call can also be determined by looking at the participants (ivr, queues, agents, etc.).

Some information about how the call concluded – wrap up codes and notes

The agent participant will have a segment with segmentType==wrapup with properties wrapUpCode and wrapUpNote.

I think my biggest issue here is that I can’t find meaningful documentation about the returned fields.

The conversations overview linked above has some overview information about conversations that may help here. Additionally, I just created API-2003 this morning to address the lack of documentation surrounding the specific parts of a conversation object and what they mean for real-world use.

4

Hi Tim,

I wanted to ask a follow up question here. If I set different attributes on a call throughout the flow in Architect, how exactly to I derive meaning from those later? Do they show up in the Conversion details somewhere? I see the "attributes": {}," field as part of the data returned...is that it?

If I'm able to report on specific custom attributes of a call, this would allow me to setup different attributes at different points in the IVR - so I can map out where calls are terminating in our IVR.

Thanks,
Jan

5

On the participant, yes. You can set whatever data you need in Architect and then retrieve it at any time in the future, whenever it's useful to you. Some common points would be when the agent has the call to do a screen pop or tell the agent something (you can get these in scripts also) or historically for custom data aggregation or detail reports.

6

Wow.. getting increasingly frustrated working with this API :confused:

On the details tab of a particular interaction, can you tell me exactly where / how these fields are populated? Sometimes the values I pull from either the Conversation or Analytics API differ than what is being reported on the call details tab.

7

Hi flyte, the conversation objects returned from analytics conversation details and the conversation calls endpoint are different. Their ids will be the same, but the information and view do vary.

From analytics convo details query:
https://developer.mypurecloud.com/api/rest/client-libraries/csharp/latest/AnalyticsConversation.html

From conversation api:
https://developer.mypurecloud.com/api/rest/client-libraries/chsarp/latest/CallConversation.html

The attributes can be retrieved from the conversation api -- you can use analytics to get the conversations list and then fetch each 'full' conversation (along with participant attributes) from conversation api. It does currently require more api calls, one per conversation, to retrieve this data. You should also be aware of some limits:

  • Conversation details analytics queries are limited to 7 days interval if no filter is specified. If a filter is specified, the interval is up to 32 days.
  • The API call rate limit is 300 calls / minute
  • The Conversations API only keeps the full calls objects for a limited amount of time (around 2 months currently). Analytics details conversations you retrieve from older periods may not be retrievable from the Conversations API, so users should plan ahead to archive these if needed.

Also note that Analytics conversation details query filters will include any conversation that touches a specified interval. For example, a call with segments that span 11:50 PM Monday to 12:10 AM Tuesday may appear in different queries for Monday and Tuesday. If you use multiple queries to get your full list of conversations, you may need to remove duplicate ids from the list your app fetches.

8

Thanks for your reply.

How are you determining a call direction of Inbound / Outbound?

Why does the AnalyticsConversation contain a ConversationStartTime, but not an end time? Are we supposed to find the last participant's last session with it's last segment and fetch the end time to get the conversation end time?

9

Looking at the JSON response body, response.conversations[x].participants[y].sessions[z].direction will tell you the direction of that session. For the external participant, the direction of their session will tell you if the external call was an inbound or outbound call.

There is a bug that's preventing that property from being sent, but the fix is currently in progress. Currently, you will have to find the latest disconnect time from the list of participants to determine when the conversation ended.

10

Thanks Tim.

The direction enum is Inbound or Outbound, and I know how to obtain the direction for a participant.

Refer to my screenshot, Direction sometimes has a value of "Inbound / Outbound". What exactly does this mean? How is this calculation done?

11

Regarding direction, the answer is complicated and largely contextual to the media type and the interaction scenario. The intent of direction is to characterize a sense of who initiated the interaction and was it done at/from the contact center.

For example, an agent proactively calling someone at their home phone to follow-up on a support case would have a direction of outbound.

Conversely, a customer sending an email to an email support queue for the first time would equate to a direction of inbound.

Where things get murkier though is if I, a PureCloud user, pick up my desk phone and call my coworker next door (also a PureCloud user). In that case, we are all still "inside" so there is no sense of in vs outbound. Without seeing the specific interactions you've mentioned, my guess is that you've come across these sorts of "sideways" (for lack of a better term--neither in nor out) interactions.

I hope this adds some clarity

12