Genesys Cloud - Developer Community!

Hello,

I've reviewed the documentation and forum discussions but couldn't find a clear explanation of how a single participant can have multiple call entries in the calls array within the GET /api/v2/conversations/{conversationId} API response.

The response schema defines participants as an array, where each participant has a calls array. Under what scenarios can a participant have multiple calls within the same conversation? Should I handle any edge cases for this in my implementation?

Any insights or official documentation references would be greatly appreciated!

Thanks in advance.

Hi David,

The key concept is that each entry in the calls array represents a distinct call leg or segment that the participant was involved in during the lifecycle of that specific conversation.

A single voice conversation isn't always a simple A-to-B connection. It can involve multiple connection segments for any given participant.

Here are the common scenarios where a participant (Agent, Customer, IVR, External Contact, etc.) can accumulate multiple call entries:

1. Transfers (Blind/Warm/Consult):

   • Consult Transfer (Warm): An agent (Agent A) is talking to a customer. Agent A initiates a consult call to Agent B.
     • Agent A will have their initial call leg with the customer.
     • Agent A will get a second call entry representing the consult leg to Agent B.
     • When Agent A merges the call or completes the transfer, the states and end times of these legs will update accordingly. Agent B will also get their own call entry when they answer the consult.

2. Conferencing:

   • An agent conferences in another agent, supervisor, or external number.
   • The agent initiating the conference will maintain their original call leg (e.g., to the customer) and gain a new call entry for the leg connecting to the newly added conference participant.
   • Each participant in the conference (original customer, agent, added party) will have at least one call entry representing their connection to the conference bridge.

Handling Edge Cases in Your Implementation:

Yes, you absolutely should design your implementation to handle the possibility of multiple calls entries per participant:

1. Iterate: Always loop through the calls array for each participant rather than assuming there will only be one entry (participant.calls[0]).
2. State Aggregation: Determine how you want to represent the participant's overall status if they have multiple active or recently disconnected legs (e.g., during a consult transfer, an agent is connected on two legs simultaneously). You might need custom logic based on the state and disconnectType of the different legs.
3. Timeline Reconstruction: If you need a precise timeline of a participant's involvement, you'll need to consider the startTime and endTime of all their call legs, potentially sorting them and merging overlapping periods if required.
4. Identify Primary vs. Secondary Legs: Depending on your use case (e.g., calculating agent talk time with the customer), you might need logic to identify the "primary" leg (e.g., the one connected to the customer) versus secondary legs (like consults). This often involves looking at the direction, disconnectType, or related participant IDs.

In summary, multiple calls entries per participant are a standard part of how Genesys Cloud models complex voice interactions involving multiple connection segments like transfers and conferences. Your code should anticipate and correctly process this structure.

For more information see the response section of the POST /api/v2/analytics/conversations/details/query 30 API call.
You can read up on the Conversation detail query 38 and Conversation Detail Data Model 56 for some more detailed information on conversations.

The overview of Conversation Detail Data Model gives the following information:

Hello,

I've reviewed the documentation and forum discussions but couldn't find a clear explanation of how a single participant can have multiple call entries in the calls array within the GET /api/v2/conversations/{conversationId} API response.

The response schema defines participants as an array, where each participant has a calls array. Under what scenarios can a participant have multiple calls within the same conversation? Should I handle any edge cases for this in my implementation?

Any insights or official documentation references would be greatly appreciated!

Thanks in advance.