Conversation schemas overview

AI-generated summary

Genesys Cloud provides administrators with comprehensive conversation schema management capabilities to define and maintain custom attributes at the conversation level, capturing dynamic, interaction-specific context such as incident types, booking references, product categories, and claim priorities through a JSON-based framework. Conversation attributes are distinct from persistent customer profile data, allowing organizations to manage temporary, interaction-specific information that varies between conversations. Implementation requires CX 2, CX 2 Digital, or CX 3 Digital licensing with appropriate permissions (schemaView, schemaAdd, schemaEdit). The setup process follows three primary steps: defining schemas and attributes through the Conversation Schema Management UI or APIs; updating conversation attribute records via Conversation Attributes APIs, Architect flows with native Create, Update, Get, and Get Attributes actions, or agent scripts; and querying attributes using the Conversation Attribute Search API to filter conversations by custom attributes. The Conversation Schema Management UI provides an accessible interface for creating, editing, and organizing schemas without requiring extensive technical resources. Conversation attribute records contain actual values for attributes defined in a schema and can include nested data structures, with multiple records from different schemas associable to a single conversation. The Get Conversation Data action in workflows retrieves conversation attributes using conversation ID and optional participant ID, storing values in flow variables and enabling branching logic based on retrieval success or failure. Conversation attribute records maintain a rolling 365-day retention period that extends upon each system update. Multiple methods support updating records, including Conversation Attribute APIs, Architect flows with native actions, and agent scripts, with future releases planned to include native read, write, and update capabilities in agent scripts and native querying capabilities in analytics and other Genesys Cloud features. Organizations must consider GDPR compliance requirements when implementing conversation attributes, as detailed in Genesys Cloud's privacy documentation. Related functionality encompasses custom data management, conversation schema creation and management, participant data handling, knowledge fabric integration, context filtering capabilities in Genesys Agent Copilot, and inbound message and email flow processing.

Conversation schemas in Genesys Cloud enable administrators to define properties of custom conversation attributes and associate these attributes to conversations through the unique conversation ID of each conversation.

Similar to how custom field types allow organizations to define business-specific schemas for external contacts—enabling capturing of persistent customer profile context, conversation attributes provide a flexible mechanism to capture dynamic interaction level context that varies from one interaction to another. For example, in an insurance use case, an external contact record stores long-term profile information like policy number, coverage tier, or risk classification. In contrast, a specific claim-related interaction requires capturing temporary context such as incident type, property damage estimate, or a claim reference number—all of which are best classified as conversation attributes. This approach maintains a clear distinction between persistent customer identity and conversation-level context, while supporting schema-based consistency across both.

Genesys Cloud provides a JSON-based schema framework that allows administrators to define and manage custom data models tailored to their business needs across supported Genesys Cloud features. A schema acts as a blueprint for the types of business-specific data that can be attached to a conversation such as incident type, booking reference, product category, or claim priority. Administrators can create and manage schema definitions by either using the Conversation Schemas UI in Genesys Cloud or through the Conversation schema management APIs.

Conversation schema management interface

The Conversation Schema Management interface in Genesys Cloud offers administrators a simpler and more accessible way to define and manage custom conversation data. With the user-friendly UI, administrators can create, edit, and organize these schemas easily. This feature provides an admin-friendly schema management tool, reduces reliance on technical resources, and helps ensure data consistency across the platform. By making schema management easier and more intuitive, Genesys Cloud is helping organizations better align their custom data structures with their business needs, while minimizing manual effort and reducing the chance of error.

Conversation attributes and records

A conversation attribute is a piece of information about an interaction. In contrast to participant data, which is linked to individual participants, conversation attributes are created and stored at the conversation level. Administrators can define such custom attributes within a conversation schema and store structured, interaction-specific metadata that is not part of the default conversation model.

Conversation attribute records hold the actual values about the specific conversation for the attributes defined in a schema. For example, in an insurance claim related interaction, a record based on the “InsuranceClaim” schema contains:

{ 
...
	incidentType: "Water Damage" 
	claimReferenceNumber: "CLM-56789" 
	propertyDamageEstimate: 
	{ 
		"amount": "9500", 
		"currencyType": "USD" 
	} 
}

Get started with conversation schemas

Add the required license and permissionsClick to expand

Step 1: Define conversation schemas and attributesClick to expand

Step 2: Update conversation attribute recordsClick to expand

Step 3: Query conversation attributesClick to expand

Methods to update field data

These methods enable you to update conversation attribute records:

Method	Natively or data actions?	Additional information
Conversation attribute APIs		Shown in contact sidebar during interactions.
Architect flows	Natively	The following actions are available in Architect: Create Conversation Attribute action Update Conversation Attribute action Get Conversation Attribute action Get Conversation Attributes action
Agent scripts	Natively	In a future release, Scripter will include native actions to read, write, and update data in conversation attributes.

Method

Natively or data actions?

Additional information

Conversation attribute APIs

Shown in contact sidebar during interactions.

Architect flows

Natively

The following actions are available in Architect:

Agent scripts

Natively

In a future release, Scripter will include native actions to read, write, and update data in conversation attributes.

Notes:

You can update and store conversation attribute records associated with conversations with a rolling 365-day retention period. Whenever the system updates a record, it extends the record’s expiration date to 365 days from the time of that update.
You can associate multiple conversation attribute records with a single conversation. These records can come from one or more different schemas.

For important considerations on privacy and GDPR compliance pertaining to conversation attributes, see Genesys Cloud and GDPR compliance.

[NEXT] Was this article helpful?

Get user feedback about articles.