Implementing Interaction History Stitching across Identity Merges and Account Migrations

How-To-Articles
1

Implementing Interaction History Stitching across Identity Merges and Account Migrations

What This Guide Covers

This guide details the architectural implementation of persistent interaction history stitching in Genesys Cloud CX when customer identities undergo merging or account migration. You will configure the Customer Identity framework to handle merge and unmerge operations, implement the necessary API orchestration to consolidate interaction timelines, and design the Agent Desktop experience to present a unified view. The result is a system where an agent sees the complete history of a customer regardless of whether the interaction originated from a legacy account, a secondary email, or a merged household record.

Prerequisites, Roles & Licensing

  • Licensing: CX 1 or higher for basic Identity management. CX 2 or higher is required for advanced Identity merging capabilities and the full Customer Identity dashboard.
  • Permissions:
    • Customer Identity > Identity > Edit
    • Customer Identity > Identity > Delete
    • Customer Identity > Identity Group > Edit
    • Customer > Interaction > Read
  • OAuth Scopes:
    • identity:read
    • identity:write
    • interaction:read
    • interaction:write
  • External Dependencies:
    • A source-of-truth Customer Relationship Management (CRM) system that supports account merging events.
    • An integration middleware (e.g., MuleSoft, Azure Logic Apps) capable of handling asynchronous event processing.

The Implementation Deep-Dive

1. Establishing the Identity Hierarchy and Merge Logic

The foundation of interaction stitching is the correct configuration of the Identity hierarchy. Genesys Cloud separates the concept of an Identity (a specific contact method, such as a phone number or email) from an Identity Group (the logical container representing the customer or household). When a merge occurs in your CRM, you are not deleting identities; you are re-parenting them under a single, authoritative Identity Group.

Configuring the Identity Schema

Before implementing merges, you must ensure your Identity schema supports the attributes required for deduplication. Navigate to Admin > Customer Identity > Identity Schema.

  1. Define Primary Identifiers: Ensure fields such as email, phone, and externalId are marked as unique constraints. This prevents the creation of duplicate identities that should have been merged.
  2. Add Merge Attributes: Create custom attributes that track the merge lineage. For example, add a String attribute named mergedFromExternalIds. This allows you to store a comma-separated list of legacy external IDs if your CRM does not maintain a full audit trail accessible via API.

The Trap: Overwriting vs. Appending

The most common failure mode in identity merging is the PUT operation on the Identity Group endpoint. Many integrations attempt to update the Identity Group by sending a full payload that replaces all existing identities. This causes the immediate loss of interaction history associated with the removed identities.

Correct Approach: Use the PATCH method or the specific POST /api/v2/customers/identity-groups/{groupId}/identities endpoint to add new identities to an existing group. Never replace the entire group payload unless you are performing a full data migration with a backup strategy.

Architectural Reasoning

We use the Identity Group as the anchor for history because interactions are linked to the identityId at the time of creation. By moving multiple identityIds into a single identityGroupId, the Genesys Cloud Interaction Search API can retrieve all interactions associated with any identity within that group. This decouples the contact method from the customer entity, allowing a customer to change their phone number without losing their history.

2. Orchestrating the Merge Event via API

The merge process must be triggered by an event from your source system. This is typically handled by an integration middleware that listens for a “Customer Merged” event from the CRM.

Step 2.1: Identify the Target Identity Group

First, determine if the target customer already exists in Genesys Cloud.

GET Request:

GET /api/v2/customers/identities?identityType=EMAIL&identityValue=john.doe@example.com&expand=identityGroup

If an identity is found, extract the identityGroup.id. If no identity is found, you must create a new Identity Group.

Step 2.2: Create or Retrieve the Source Identity

Retrieve the identity associated with the legacy account or secondary contact method.

GET Request:

GET /api/v2/customers/identities?identityType=EMAIL&identityValue=old.john@example.com&expand=identityGroup

Step 2.3: Execute the Merge

If both identities exist and belong to different Identity Groups, you must move the source identity to the target Identity Group. This is done by updating the identityGroupId of the source identity.

PATCH Request:

PATCH /api/v2/customers/identities/{sourceIdentityId}
Content-Type: application/json

{
  "identityGroupId": "targetIdentityGroupId"
}

The Trap: Circular References and Orphaned Groups
If you merge Identity Group A into Identity Group B, you must ensure that all identities in Group A are moved to Group B. If you leave any identity in Group A, that group becomes an orphan. Orphaned groups break the “single view” experience because interactions tied to the orphaned identities will not appear in the search results for Group B.

Solution: Always perform a GET /api/v2/customers/identity-groups/{sourceGroupId}/identities before the merge to ensure you are moving all identities. If the source group is empty after the move, delete it using DELETE /api/v2/customers/identity-groups/{sourceGroupId} to maintain data hygiene.

Step 2.4: Handling Interaction History Linkage

Genesys Cloud automatically links interactions to the Identity Group based on the identity used during the interaction. However, if you are migrating historical data from an external system, you must explicitly link past interactions to the new Identity Group.

Use the POST /api/v2/customers/interactions endpoint to create interaction records for historical data. Ensure the customer.identityId matches one of the identities in the target Identity Group.

{
  "customer": {
    "identityId": "newlyMergedIdentityId",
    "name": "John Doe"
  },
  "type": "VOICE",
  "direction": "INBOUND",
  "startTimestamp": "2023-01-15T10:00:00.000Z",
  "endTimestamp": "2023-01-15T10:05:00.000Z"
}

Architectural Reasoning: By linking historical interactions to the specific identityId that is now part of the merged group, you preserve the context of the original contact method. This allows agents to see not just what happened, but how the customer contacted them (e.g., “This complaint was originally filed via the legacy phone number”).

3. Designing the Agent Experience for Unified History

Once the data is stitched, the Agent Desktop must present this unified view. The default Interaction Timeline widget shows interactions based on the current context. If the agent is viewing a customer card, the timeline should reflect all interactions across the Identity Group.

Configuring the Interaction Timeline

  1. Navigate to Admin > Digital Engagement > Agent Desktop.
  2. Open the Interaction Timeline configuration.
  3. Ensure the Data Source is set to Customer Identity.
  4. In the Filter Criteria, set the Identity Group ID to the dynamic variable {{customer.identityGroup.id}}.

The Trap: Context Switching Lag
If an agent switches from a customer with a merged identity to a new customer, the timeline may briefly show stale data. This is caused by caching in the Agent Desktop UI.

Solution: Implement a refresh trigger in your custom widgets or ensure the default widget is configured to re-query the API on customerContextChange. In Genesys Cloud, this is often handled automatically, but custom implementations using the Genesys Cloud SDK must explicitly call customerService.getInteractions() with the new identityGroupId.

Building a Custom “Merge History” Widget

For advanced visibility, create a custom widget that displays the merge lineage. This helps agents understand why a customer might have multiple phone numbers or emails.

  1. Fetch Identity Group Details:
    const identityGroup = await customerService.getIdentityGroup(identityGroupId);
const identities = identityGroup.identities;
  2. Render the Lineage:
    Display a table showing each identity, its type, and the date it was added to the group (if tracked). This provides transparency into the customer’s contact evolution.

Architectural Reasoning: Providing merge lineage builds trust with the agent. If a customer claims they never used a certain phone number, the agent can see that the number was merged from a legacy account three years ago, providing context for the customer’s confusion.

Validation, Edge Cases & Troubleshooting

Edge Case 1: The “Zombie” Interaction

The Failure Condition:
An agent searches for a customer by their primary email. The timeline shows interactions from the last 6 months, but the customer insists they called last year. The call logs exist in the telephony system but are missing from the Genesys Cloud timeline.

The Root Cause:
The identity associated with the old phone number was not properly merged into the current Identity Group. Instead, it was left in an orphaned group or deleted. When the identity is deleted, the interaction history remains in the system but is no longer accessible via the standard Customer Identity search because the link is broken.

The Solution:

  1. Search for the interaction directly using the Interaction Search API with the old phone number as a filter.
    GET /api/v2/interactions/search?filter=customer.phone:oldPhoneNumber
  2. Identify the identityId used in that interaction.
  3. Check if that identityId exists. If it does, move it to the correct Identity Group using the PATCH method described in Step 2.3.
  4. If the identityId was deleted, you must restore it from backup or manually create a new identity with the same external ID and move it to the group. Note that creating a new identity with the same external ID will not automatically link old interactions; you must manually associate the interactions or accept that the history is fragmented.

Edge Case 2: The Duplicate Merge Loop

The Failure Condition:
Your integration middleware attempts to merge Customer A into Customer B. However, due to a race condition or idempotency failure, the middleware retries the merge. The second attempt tries to merge Customer B back into Customer A, or it attempts to merge an already merged identity, causing API errors.

The Root Cause:
The integration lacks idempotency checks. The PATCH request to move an identity is not inherently idempotent if the target group changes between retries.

The Solution:
Implement a pre-merge check in your middleware.

  1. Before initiating a merge, query the current identityGroupId of the source identity.
  2. Compare it to the target identityGroupId.
  3. If they are already the same, skip the merge operation and log a success status.
  4. Use the Idempotency-Key header in your API requests to prevent duplicate processing if the middleware retries.

Edge Case 3: Search Performance Degradation

The Failure Condition:
After a large-scale migration involving thousands of merges, the Agent Desktop timeline loads slowly or times out when viewing customers with many merged identities.

The Root Cause:
The Interaction Search API queries all interactions for all identities in the group. If a group has 50+ identities (e.g., a household with many members or a corporate account with many contacts), the query complexity increases exponentially.

The Solution:

  1. Limit Identity Group Size: Enforce business rules to limit the number of identities per group. For households, consider using a “Household” Identity Group and separate “Member” Identity Groups linked via a custom attribute.
  2. Paginate Results: Ensure your Agent Desktop widget uses pagination (pageSize and pageToken) when fetching interactions. Do not attempt to load all history at once.
  3. Use Time Filters: Default the timeline to show only the last 12 months of interactions. Provide a “Load More” button for older history.

Official References