Implement Conversation Insights

To produce conversation data as XDM Experience Events and ensure that these conversation experience events end up in Adobe Experience Platform as datasets, instrument your agent application or service to use Conversation Insights.

This article documents the required implementation steps.

Schema and datasets

Configure datasets for the primary conversation events: prompt, response, feedback. The prompt, response, and feedback datasets must extend the XDM Experience Event base schema with the Conversation Event field group and can optionally include the Agentic Information field group and other additional field groups.

You can define separate datasets for prompts, responses, and feedback or combine data into datasets. For example, use one dataset for prompts and responses and another dataset for feedback. Or use a separate dataset for each type of conversation event as illustrated in How it works.

To illustrate, use:

Dataset layout and the delivery of conversation events into these datasets are separate concerns. Send each conversation event as soon as data is available to ensure stable conversation identifiers and turn identifiers. Stable identifiers facilitate proper correlation by the Conversation Blender service across datasets.

Conversation Event field group

The Conversation Event field group is a required field group and uses the conversation object.

The conversation object captures data for:

Conversation

A unique conversationID identifies a conversation. For example: conversationID = "conv-001". The conversationID allows all related turns events to be grouped into the same conversational experience.

The schema also supports conversationName. A human-readable name that describes the overall context of the conversation, such as: France Geography Q&A. The conversation name is auto generated but you can update the generated name. The conversation name is also populated to signals[].name. Adobe populates the conversationName with the same value as the signals[].name = “title” signal. You can set the conversation.conversationName on any dataset you populate and overwrite the Adobe provided value.

Turn

A turn is one interaction cycle within a conversation.

turnID A unique turnID identifies a turn. For example:

conversationID = "conv-001"
turnID = "turn-001"

The same conversationID and turnID are used to correlate the prompt, response, and feedback associated with that turn. That correlation works across records that are delivered separately or end up in different datasets. A turnId only needs to be unique within the same conversation but can be reused across conversations. For example, you can have both turn-001 as the turnID in conversations with conversationID conv-001 and conv-002.

Prompt

A prompt is the input submitted to the agent. In most customer scenarios, this input is the user’s question, request, instruction, or message.

The prompt uses the following representation: conversation.prompt

Important prompt fields include:

A prompt can contain multiple raw segments. For example, a user enters text and includes a URL.

Response

A response is the content returned by the agent or another responding party.

conversation.response A unique responseID represents the response.

Important response fields include:

The documented source types include:

Feedback

Feedback is the user’s explicit evaluation or reaction to the interaction.

The feedback structure includes: conversation.feedback.

Examples:

The documented rating score range is from -1.0 to 1.0.

A feedback event can be represented as a feedback-only event using: eventType = "conversation.feedback".

When feedback applies to a particular turn, preserve the appropriate conversationID and turnID so that the conversation blender can associate the feedback with the relevant interaction.

Signal

A signal is a structured analytical observation about conversation content. The Signal extraction service provides out of the box signals. No action is required to provide signals, but you can add signals as part of the integration.

A signal has the following fields.

The signal extraction service populates the signals object for the signals dataset.

The previous signals[].attributes.{subjects,intents,tones,sentiment} container is deprecated.

Source type

You need to set a value for source for each prompt, response, or feedback object in an event. Any value is acceptable. Use values that help you to understand where data originates from. For example:

Purpose type (raw text)

You need to set a value for the purpose attribute on any element of the raw object in a prompt, response, or feedback object. Any string value is acceptable. This field is used to differentiate what is stored in the raw text. Useful values are below, other values are equally valid:

Conversation

See below for the full details of a conversation object.

Agentic Information field group

The Agentic Information field group is an optional field group and uses the agenticExperience object. Consider using this field group if you want to track agentic information.

To implement events propagating the Agentic Information field group with data, you should ensure:

{
  "_id":"a33e1068-3966-468b-8682-e5e493827ffe",
  "timestamp":"2026-09-11T00:03:15Z",
  "eventType":"agent.interaction",
  "identityMap":{
    "ECID":[
      {
        "id": "12345678901234567890123456789012345678",
        "primary": true
      }
    ]
  },
  "agenticExperience":{
    "conciergeID":"concierge-abc123",
    "name":"Customer Support Experience",
    "version":"1.0.0",
    "environment":"dev",
    "mode":"preview",
    "agents":[
      {
        "agentID":"agent-001",
        "name":"Chatbot Assistant",
        "version":"2.1.3",
        "score":0.92
      },
      {
        "agentID":"agent-002",
        "name":"Voice Assistant",
        "version":"3.0.0",
        "score":0.88
      }
    ],
    "skills":[
      {
        "skillID":"skill-intent-recognition",
        "skillInvocationID":"inv-9f2a-001",
        "name":"Intent Recognition",
        "version":"1.0.0",
        "agentID":"agent-001",
        "invocationSource":"main",
        "score":0.95,
        "failed":false,
        "sequenceNumber":1,
        "timestamp":"2026-09-11T00:03:14Z",
        "skillSource":"inline",
        "executionContext":"inline",
        "reasoning":{
          "narration":"Recognized an intent to verify a geography fact"
        },
        "parameters":[
          { "key":"language", "value":"en-US" },
          { "key":"confidenceThreshold", "value":"0.8" }
        ]
      },
      {
        "skillID":"skill-faq-retrieval",
        "skillInvocationID":"inv-9f2a-002",
        "name":"FAQ Retrieval",
        "version":"1.2.0",
        "agentID":"agent-001",
        "invocationSource":"main",
        "score":0.89,
        "failed":false,
        "sequenceNumber":2,
        "timestamp":"2026-09-11T00:03:15Z",
        "skillSource":"inline",
        "executionContext":"forked",
        "parameters":[
          { "key":"maxResults", "value":"5" }
        ]
      },
      {
        "skillID":"skill-speech-recognition",
        "skillInvocationID":"inv-9f2a-003",
        "name":"Speech Recognition",
        "version":"2.0.1",
        "agentID":"agent-002",
        "invocationSource":"main",
        "score":0.91,
        "failed":false,
        "sequenceNumber":1,
        "timestamp":"2026-09-11T00:03:15Z",
        "skillSource":"deferred",
        "executionContext":"inline",
        "parameters":[
          { "key":"languageModel", "value":"general" },
          { "key":"noiseSuppression", "value":"true" }
        ]
      }
    ]
  }
}

Additional field groups

You can add optional field groups to the schema you use for prompt, response, and feedback datasets. For example:

The customer is responsible for producing the source conversation events. Adobe performs signal extraction and data blending. The customer does not need to implement the signal-extraction or blending services.

Event type

You need to set one of the following values for eventType (String) for each conversation event:

Example

See below for example usage of the Conversation Event field group in various scenarios.

{
  "_id":"a33e1068-3966-468b-8682-e5e493827fff",
  "timestamp":"2026-09-11T00:03:15Z",
  "eventType":"conversation.turn",
  "identityMap":{
    "ECID":[
      { "id": "12345678901234567890123456789012345678", "primary": true }
    ]
  },
  "web": {
    "webPageDetails": { "URL": "https://www.adobe.com", "name": "Home Page" }
  },
  "agenticExperience":{
    "conciergeID":"concierge-abc123",
    "name":"Customer Support Experience",
    "version":"1.0.0",
    "environment":"dev",
    "mode":"preview",
    "agents":[
      { "agentID":"agent-001", "name":"Chatbot Assistant", "version":"2.1.3", "score":0.92 }
    ]
  },
  "conversation": {
    "conversationID": "conv-001",
    "conversationName": "France Geography Q&A",
    "turnID": "int-001",
    "prompt": {
      "source": "end-user",
      "raw": [
        { "text": "What is the capital of France? This link says it is Lyon.", "purpose": "User Input" },
        { "text": "https://wrong.geography.com/france", "purpose": "link" }
      ]
    }
  }
}

{
  "_id":"a33e1068-3966-468b-8682-e5e493827ffd",
  "timestamp":"2026-09-11T00:03:16Z",
  "eventType":"conversation.turn",
  "identityMap":{
    "ECID":[
      { "id": "12345678901234567890123456789012345678", "primary": true }
    ]
  },
  "web": {
    "webPageDetails": { "URL": "https://www.adobe.com", "name": "Home Page" }
  },
  "agenticExperience":{
    "conciergeID":"concierge-abc123",
    "name":"Customer Support Experience",
    "version":"1.0.0",
    "environment":"dev",
    "mode":"preview",
    "agents":[
      { "agentID":"agent-001", "name":"Chatbot Assistant", "version":"2.1.3", "score":0.92 }
    ]
  },
  "conversation": {
    "conversationID": "conv-001",
    "conversationName": "France Geography Q&A",
    "turnID": "int-001",
    "response": {
      "source": "concierge",
      "raw": [
        { "text": "The capital of France is Paris.", "purpose": "main" },
        { "text": "Would you like to plan a trip to Paris?", "purpose": "advertisement" },
        { "text": "https://en.wikipedia.org/wiki/France", "purpose": "citation" }
      ]
    }
  }
}

{
  "_id":"a33e1068-3966-468b-8682-e5e493827ffb",
  "timestamp":"2026-09-12T00:03:15Z",
  "eventType":"conversation.feedback",
  "identityMap":{
    "ECID":[
      { "id": "12345678901234567890123456789012345678", "primary": true }
    ]
  },
  "web": {
    "webPageDetails": { "URL": "https://www.adobe.com", "name": "Home Page" }
  },
  "conversation": {
    "conversationID": "conv-001",
    "conversationName": "France Geography Q&A",
    "feedback": {
      "source": "end-user",
      "raw": [
        { "text": "Great help", "purpose": "text box" }
      ],
      "rating": {
        "score": 1,
        "classification": "Thumbs Up",
        "reasons": ["Accurate", "Quick response"]
      }
    }
  }
}

{
  "_id":"a33e1068-3966-468b-8682-e5e493827ffa",
  "timestamp":"2026-09-11T00:03:15Z",
  "eventType":"conversation.recommendation",
  "identityMap":{
    "ECID":[
      { "id": "12345678901234567890123456789012345678", "primary": true }
    ]
  },
  "web": {
    "webPageDetails": { "URL": "https://www.adobe.com", "name": "Home Page" }
  },
  "agenticExperience":{
    "conciergeID":"concierge-xyz789",
    "name":"Product Concierge",
    "version":"1.0.0",
    "environment":"prod",
    "mode":"release",
    "agents":[
      { "agentID":"agent-010", "name":"Product Advisor", "version":"1.0.0", "score":0.92 }
    ]
  },
  "conversation": {
    "conversationID": "conv-001",
    "turnID": "int-099",
    "prompt": {
      "source": "end-user",
      "raw": [
        { "text": "What product do you recommend for a new user trying to create a poster?", "purpose": "User Input" }
      ]
    },
    "response": {
      "source": "concierge",
      "raw": [
        { "text": "To create a poster, we would recommend Adobe Express - https://express.adobe.com.", "purpose": "main" },
        { "text": "https://express.adobe.com", "purpose": "link" }
      ]
    }
  },
  "productListItems": [
    { "SKU": "express" }
  ]
}

Data collection

Use the following data collection strategy for Conversation Insights.

Event types

Your agent application or service sends an event as soon as possible. Ensure the app or service does not wait for a response before sending the prompt across with the information available at the time of the event.

This recommendation implies that:

Event correlation

The agent application or service must preserve stable identifiers across all related events.

The agent application or service generates IDs that remain stable during retries or redelivery. This allows downstream processing to associate events correctly and avoid unintended duplicate events.

Signal extraction

Signal extraction takes place after data collection. Your agent application or service can populate additional signals.

Signal name

You need to set a value for signals[].name. Any string value is acceptable; however, Adobe populates the following names during the signal extraction process. Avoid using these values for name for any signals you send in because these values will be overwritten.

Signal scope

Any string value is acceptable; however, Adobe populates the following scopes during the signal extraction process. Avoid using these values for scope for any signals you send in because these values will be overwritten.

{
  "_id":"a33e1068-3966-468b-8682-e5e493827fff",
  "timestamp":"2026-09-11T00:03:15Z",
  "eventType":"conversation.turn",
  "identityMap":{
    "ECID":[
      { "id":"12345678901234567890123456789012345678", "primary":true }
    ]
  },
  "web":{
    "webPageDetails":{ "URL":"https://www.adobe.com", "name":"Home Page" }
  },
  "agenticExperience":{
    "conciergeID":"concierge-abc123",
    "name":"Customer Support Experience",
    "version":"1.0.0",
    "environment":"dev",
    "mode":"preview",
    "agents":[
      { "agentID":"agent-001", "name":"Chatbot Assistant", "version":"2.1.3", "score":0.92 }
    ],
    "skills":[
      {
        "skillID":"skill-intent-recognition",
        "skillInvocationID":"inv-9f2a-001",
        "name":"Intent Recognition",
        "version":"1.0.0",
        "agentID":"agent-001",
        "invocationSource":"main",
        "score":0.95,
        "sequenceNumber":1,
        "timestamp":"2026-09-11T00:03:14Z",
        "skillSource":"inline",
        "executionContext":"inline"
      }
    ]
  },
  "conversation":{
    "conversationID":"conv-001",
    "conversationName":"France Geography Q&A",
    "turnID":"int-001",
    "signals":[
      {
        "scope":"turn",
        "name":"subjects",
        "type":"string",
        "values":[
          { "stringValue":"capital of France", "confidence":0.93, "qualifiers":["geographical","factual-question"] },
          { "stringValue":"Lyon", "confidence":0.87, "qualifiers":["incorrect","misinformation"] }
        ]
      },
      {
        "scope":"turn",
        "name":"intents",
        "type":"string",
        "values":[
          { "stringValue":"seek-information" },
          { "stringValue":"verify-facts" }
        ]
      },
      {
        "scope":"turn",
        "name":"tones",
        "type":"string",
        "values":[
          { "stringValue":"curious" },
          { "stringValue":"uncertain" }
        ]
      },
      {
        "scope":"turn",
        "name":"sentiment",
        "type":"number",
        "values":[
          { "numberValue":0.1 }
        ]
      },
      {
        "scope":"conversation-to-date",
        "name":"subjects",
        "type":"string",
        "values":[
          { "stringValue":"unreliable source", "qualifiers":["external-link","potentially-misleading"] },
          { "stringValue":"geography knowledge", "qualifiers":["educational","basic-facts"] }
        ]
      },
      {
        "scope":"conversation-to-date",
        "name":"intents",
        "type":"string",
        "values":[
          { "stringValue":"fact-checking" },
          { "stringValue":"learn-correct-information" }
        ]
      },
      {
        "scope":"conversation-to-date",
        "name":"tones",
        "type":"string",
        "values":[
          { "stringValue":"questioning" },
          { "stringValue":"seeking-clarification" }
        ]
      },
      {
        "scope":"conversation-to-date",
        "name":"sentiment",
        "type":"number",
        "values":[
          { "numberValue":0.3 }
        ]
      }
    ],
    "prompt":{
      "source":"end-user",
      "raw":[
        { "text":"What is the capital of France? This link says it is Lyon.", "purpose":"User Input" },
        { "text":"https://wrong.geography.com/france", "purpose":"link" }
      ]
    }
  }
}

Data blending

The conversation blender service merges events from prompt, response, feedback, and signal events datasets into a dedicated blended conversation events dataset. That dataset is used in Customer Journey Analytics as part of a connection. The components within that dataset are added to the data views you have specified for a Conversation Insights configuration.