From 0a2971f6e1b7441727b269f974269901f2b8c5c1 Mon Sep 17 00:00:00 2001 From: pwseg Date: Mon, 25 Mar 2024 21:25:23 -0500 Subject: [PATCH 1/4] Add to sidenav and puuush it --- src/_data/sidenav/main.yml | 2 + src/connections/spec/copilot.md | 309 ++++++++++++++++++++++++++++++++ 2 files changed, 311 insertions(+) create mode 100644 src/connections/spec/copilot.md diff --git a/src/_data/sidenav/main.yml b/src/_data/sidenav/main.yml index b99c85da4f..d94423c7bc 100644 --- a/src/_data/sidenav/main.yml +++ b/src/_data/sidenav/main.yml @@ -114,6 +114,8 @@ sections: title: 'Spec: Identify' - path: /connections/spec/alias title: 'Spec: Alias' + - path: /connections/spec/copilot + title: 'Spec: AI Copilot' - path: /connections/spec/common title: 'Spec: Common Fields' - path: /connections/spec/mobile diff --git a/src/connections/spec/copilot.md b/src/connections/spec/copilot.md new file mode 100644 index 0000000000..42e4fcd8c4 --- /dev/null +++ b/src/connections/spec/copilot.md @@ -0,0 +1,309 @@ +--- +title: 'Spec: AI Copilot' +--- + +This page is a guide for developers who want to track interactions with AI copilots using Segment. It explains what data to send to Segment, letting you understand customer interactions with with AI copilots. + +## Overview + +AI copilots are like virtual assistants that help customers in conversations. + +Each conversation starts when a customer sends their first message or question. Throughout the conversation, Segment can track various events that capture key moments, like messages sent and received, tools invoked, and media generated. + +While some copilot conversations have clear ending points, which occur when the customer explicitly indicates that the conversation is over, the tracked events provide valuable insights into the entire conversation flow. + +## Tracked events + +In this section, you'll find the tracked semantic events that serve as a starting point for AI copilot events. You can extend them based on your own requirements. + +This table lists the events that you can track from any conversation: + +| Event | Definition | Fields | +| -------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | +| Conversation Started | When a new conversation begins | `conversationId` | +| Message Sent | When the first message is added to a thread by user | `conversationId`, `messageId`, `message_body` | +| Message Received | Non-custom response (text/voice) to user prompt by copilot | `conversationId`, `messageId`, `message_body` | +| Conversation Ended | When a conversation is completed | `conversationId`, `message_count` | +| Tool Invoked | When the model or user invokes a capability or tool | `conversationId`, `messageId`, `type`, `action` | +| Media Generated | When the model generates an image/video/audio | `conversationId`, `messageId`, `type`, `sub_type` | +| Component Loaded | When a new custom (non-text/voice) component is shown to user | `conversationId`, `messageId`, `type` | +| Feedback Submitted | When a user rates a conversation or message | `conversationId`, `messageId`, `rating` | +| Identify | When a new user is identified anonymously or known | `userId` and/or `anonymousId` | +| Standard Track Calls | For all events sent to Segment based on user actions taken, like `items purchased`, `support requested` | `conversationId`, `messageId`, `...` | + +### Live chat events + +Segment can also track the following live chat events: + +- Conversation Started +- Message Sent +- Message Received +- Custom Component Loaded +- Tool Invoked +- Media Generated +- Conversation Ended + +## Event details + +This section contains the structure and properties of each AI copilot tracked event. + +### Conversation Started + +The Conversation Started event should be sent when a customer sends their first message. + +This event supports the following semantic properties: + +| Property | Type | Description | +| ---------------- | ------ | ------------------------------------- | +| `conversationId` | string | The conversation's unique identifier. | + + +Here's an example of a Conversation Started call: + +```json +{ + "userId": "123", + "action": "track", + "event": "Conversation Started", + "properties": { + "conversationId": "1238041hdou" + } +} +``` + +### Message Sent + +The Message Sent event should be sent when a user adds a new message to a thread. + +This event supports the following semantic properties: + +| Property | Type | Description | +| ---------------- | ------ | ------------------------------------- | +| `conversationId` | string | The conversation's unique identifier. | +| `messageId` | string | The message's unique identifier. | +| `message_body` | string | The message's content. | + +Here's an example of a Message Sent call: + +```json +{ + "userId": "123", + "action": "track", + "event": "Message Sent", + "properties": { + "conversationId": "1238041hdou", + "messageId": "msg123", + "message_body": "What's the best stock in the Nasdaq right now?" + } +} +``` + +### Message Received + +The Message Received event should be sent when the copilot gives a non-customer response (either text or voice) to something the user asked. + +This event supports the following semantic properties: + +| Property | Type | Description | +| ---------------- | ------ | ------------------------------------- | +| `conversationId` | string | The conversation's unique identifier. | +| `messageId` | string | The message's unique identifier. | +| `message_body` | string | The received message's content. | + +```json +{ + "userId": "123", + "action": "track", + "event": "Message Received", + "properties": { + "conversationId": "1238041hdou", + "messageId": "msg124", + "message_body": "Thank you for reaching out. How can I assist you today?" + } +} +``` + +### Conversation Ended + +The Conversation Ended event should be sent when a customer or agent explicitly indicates that the conversation has ended or deletes the chat. + +This event supports the following semantic property: + +| Property | Type | Description | +| ---------------- | ------ | ------------------------------------- | +| `conversationId` | string | The conversation's unique identifier. | + +Here's an example of a Conversation Ended call: + +```json +{ + "userId": "123", + "action": "track", + "event": "Conversation Ended", + "properties": { + "conversationId": "1238041hdou" + } +} +``` + +### Tool Invoked + +The Tool Invoked event should be sent when the copilot or user uses a customer capability or tool, like making a call to an external API. + +This event supports the following semantic properties: + +| Property | Type | Description | +| ---------------- | ------ | ---------------------------------------- | +| `conversationId` | string | The conversation's unique identifier. | +| `messageId` | string | The message's unique identifier. | +| `type` | string | The type of tool invoked. | +| `action` | String | The specific action taken with the tool. | + +Here's an example of a Tool Invoked call: + +```json +{ + "userId": "123", + "action": "track", + "event": "Tool Invoked", + "properties": { + "conversationId": "1238041hdou", + "messageId": "msg125", + "type": "Inventory Request", + "action": "check stock level" + } +} +``` + +### Media Generated + +This event should be sent when an image, video, or custom audio is generated by the model. + +This event supports the following semantic properties: + +| Property | Type | Description | +| ---------------- | ------ | ------------------------------------------------------- | +| `conversationId` | string | The conversation's unique identifier. | +| `messageId` | string | The message's unique identifier. | +| `type` | string | The type of media generated (like `"image"`, `"video"`) | +| `sub_type` | String | Media data type (like `"gif"`, `"mp4"`, `"wav"`) | + +Here's an example of a Media Generated call: + +```json +{ + "userId": "123", + "action": "track", + "event": "Media Generated", + "properties": { + "conversationId": "1238041hdou", + "messageId": "msg126", + "type": "image", + "sub_type": "gif" + } +} +``` + +### Component Loaded + +This event should be sent when a new, custom component is shown to the user that isn't text or voice. + +This event supports the following semantic properties: + +| Property | Type | Description | +| ---------------- | ------ | ------------------------------------- | +| `conversationId` | string | The conversation's unique identifier. | +| `messageId` | string | The message's unique identifier. | +| `type` | string | The type of custom component loaded. | + +Here's an example of a Component Loaded call: + +```json +{ + "userId": "123", + "action": "track", + "event": "Component Loaded", + "properties": { + "conversationId": "1238041hdou", + "messageId": "msg127", + "type": "Stock Price Chart" + } +} +``` + +### Feedback Submitted + +This event should be sent when a user rates a conversation or message. + +This event supports the following semantic properties: + +| Property | Type | Description | +| ---------------- | ------ | ------------------------------------- | +| `conversationId` | string | The conversation's unique identifier. | +| `messageId` | string | The message's unique identifier. | +| `rating` | number | The rating given by the user. | + +Here's an example of a Feedback Submitted call: + +```json +{ + "userId": "123", + "action": "track", + "event": "Feedback Submitted", + "properties": { + "conversationId": "1238041hdou", + "messageId": "msg128", + "rating": 5 + } +} +``` + +### Identify + +This event should be sent when a new user is identified, either anonymously or as a known user. + +This event supports the following semantic properties: + +| Property | Type | Description | +| ------------- | ------ | ------------------------------------------------ | +| `userId` | string | The user's unique identifier. | +| `anonymousId` | string | The user's anonymous identifier (if applicable). | + +Here's an example of an Identify call: + +```js +{ + "userId": "123" || "anonymousId" : "768923ihuy32", + "action": "identify", + "properties": +} +``` + +### Standard Track calls + +When sending events to Segment based on user actions, like items purchased or support requested, make sure to include relevant identifiers for accurate tracking and analysis. + +These identifiers include `conversationId` and `messageId`, among others, depending on the specific tracked action: + +| Identifier | Description | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `conversationId` | The conversation's unique identifier. This identifier is crucial to tracking actions within a messaging or support context. | +| `messageId` | The message's unique identifier. This identifier is especially important for actions like messages read, media generated, or feedback submitted. | + +For example, to track an event where a user makes a purchase, the standard Track call could look like this: + +```json +{ + "userId": "user123", + "action": "track", + "event": "Item Purchased", + "properties": { + "conversationId": "conv456", + "messageId": "msg789", + "itemId": "item101112", + "itemName": "Super Widget", + "itemPrice": 19.99, + "currency": "USD" + } +} +``` \ No newline at end of file From 12f32bcc2556510ebae52b26c71f220db474a52a Mon Sep 17 00:00:00 2001 From: pwseg Date: Mon, 25 Mar 2024 21:25:50 -0500 Subject: [PATCH 2/4] Remove whitespace [netlify-build] --- src/connections/spec/copilot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/spec/copilot.md b/src/connections/spec/copilot.md index 42e4fcd8c4..0adb5d5459 100644 --- a/src/connections/spec/copilot.md +++ b/src/connections/spec/copilot.md @@ -306,4 +306,4 @@ For example, to track an event where a user makes a purchase, the standard Track "currency": "USD" } } -``` \ No newline at end of file +``` From 5218189fc0a986e32db4d12c9117cb3ec5c28ed5 Mon Sep 17 00:00:00 2001 From: pwseg Date: Mon, 25 Mar 2024 21:35:38 -0500 Subject: [PATCH 3/4] typo fixes --- src/connections/spec/copilot.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/connections/spec/copilot.md b/src/connections/spec/copilot.md index 0adb5d5459..a54e7e8307 100644 --- a/src/connections/spec/copilot.md +++ b/src/connections/spec/copilot.md @@ -2,7 +2,7 @@ title: 'Spec: AI Copilot' --- -This page is a guide for developers who want to track interactions with AI copilots using Segment. It explains what data to send to Segment, letting you understand customer interactions with with AI copilots. +This page is a guide for developers who want to track interactions with AI copilots using Segment. It explains what data to send to Segment, letting you understand customer interactions with AI copilots. ## Overview @@ -100,7 +100,7 @@ Here's an example of a Message Sent call: ### Message Received -The Message Received event should be sent when the copilot gives a non-customer response (either text or voice) to something the user asked. +The Message Received event should be sent when the copilot gives a non-custom response (either text or voice) to something the user asked. This event supports the following semantic properties: From af33e0f95c193446ce29134a58e6f55e86128ee2 Mon Sep 17 00:00:00 2001 From: pwseg Date: Mon, 25 Mar 2024 21:39:39 -0500 Subject: [PATCH 4/4] Final touch up --- src/connections/spec/copilot.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/connections/spec/copilot.md b/src/connections/spec/copilot.md index a54e7e8307..740e1d06e4 100644 --- a/src/connections/spec/copilot.md +++ b/src/connections/spec/copilot.md @@ -26,7 +26,7 @@ This table lists the events that you can track from any conversation: | Conversation Ended | When a conversation is completed | `conversationId`, `message_count` | | Tool Invoked | When the model or user invokes a capability or tool | `conversationId`, `messageId`, `type`, `action` | | Media Generated | When the model generates an image/video/audio | `conversationId`, `messageId`, `type`, `sub_type` | -| Component Loaded | When a new custom (non-text/voice) component is shown to user | `conversationId`, `messageId`, `type` | +| Component Loaded | When a new custom (non-text/voice) component is shown to a user | `conversationId`, `messageId`, `type` | | Feedback Submitted | When a user rates a conversation or message | `conversationId`, `messageId`, `rating` | | Identify | When a new user is identified anonymously or known | `userId` and/or `anonymousId` | | Standard Track Calls | For all events sent to Segment based on user actions taken, like `items purchased`, `support requested` | `conversationId`, `messageId`, `...` | @@ -148,7 +148,7 @@ Here's an example of a Conversation Ended call: ### Tool Invoked -The Tool Invoked event should be sent when the copilot or user uses a customer capability or tool, like making a call to an external API. +The Tool Invoked event should be sent when the copilot or user uses a custom capability or tool, like making a call to an external API. This event supports the following semantic properties: