Conversation schemas overview

AI-generated summary

Genesys Cloud's conversation schemas enable administrators to define and manage custom attributes at the conversation level, distinct from persistent customer profile data stored in external contact records. These schemas use a JSON-based framework to structure interaction-level context such as incident type, booking reference, product category, or claim priority, capturing dynamic information that varies between interactions—such as claim reference numbers or property damage estimates in insurance scenarios. The Conversation Schema Management UI provides administrators with an accessible interface to create, edit, and organize schemas without requiring extensive technical resources, thereby reducing manual effort and errors while ensuring data consistency. Implementation requires CX 2, CX 2 Digital, or CX 3 Digital licensing and specific permissions for viewing, adding, and editing schema definitions. The three-step setup process involves defining schemas and attributes through the conversation schemas UI or APIs, updating conversation attribute records via Conversation Attributes APIs (with future native support planned for Architect and agent scripts), and querying attributes using the Conversation Attribute Search API for filtering conversations by custom attributes. Multiple methods enable field data updates, including Conversation Attribute APIs displayed in contact sidebars, Architect flows through data actions, and agent scripts with planned native functionality. The Get Conversation Data action in workflows retrieves conversation attributes using conversation ID and optional participant ID, storing values in flow variables and branching logic based on successful retrieval (Found path) or failure (Not Found path). Conversation attribute records maintain a rolling 365-day retention period that extends upon each system update, and multiple records from different schemas can associate with a single conversation. GDPR compliance considerations apply to conversation attributes and are detailed in Genesys Cloud's privacy documentation.

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	Data actions	In a future release, Architect will include native actions to read, write, and update data in conversation attributes.
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.

Conversation schemas overview View summary