{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://github.com/api-search/microsoft-copilot/json-schema/microsoft-copilot-interaction-schema.json", "title": "Microsoft 365 Copilot Interaction", "description": "Schema representing an interaction between a user and Microsoft 365 Copilot, including prompts, responses, attachments, contexts, links, and mentions. Based on the microsoft.graph.aiInteraction resource type from the Microsoft Graph Copilot namespace.", "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the interaction message." }, "appClass": { "type": "string", "description": "The data source for Copilot data. Indicates which Microsoft 365 application hosted the interaction. Examples include IPM.SkypeTeams.Message.Copilot.Excel, IPM.SkypeTeams.Message.Copilot.Loop, IPM.SkypeTeams.Message.Copilot.Word, IPM.SkypeTeams.Message.Copilot.PowerPoint, IPM.SkypeTeams.Message.Copilot.Teams.", "examples": [ "IPM.SkypeTeams.Message.Copilot.Excel", "IPM.SkypeTeams.Message.Copilot.Loop", "IPM.SkypeTeams.Message.Copilot.Word", "IPM.SkypeTeams.Message.Copilot.PowerPoint", "IPM.SkypeTeams.Message.Copilot.Teams" ] }, "body": { "$ref": "#/$defs/itemBody", "description": "The body of the message, including the text content and its body type." }, "interactionType": { "type": "string", "enum": [ "userPrompt", "aiResponse", "unknownFutureValue" ], "description": "Indicates whether the interaction is a user prompt or a Copilot response. userPrompt represents a user's input; aiResponse represents Copilot's reply." }, "conversationType": { "type": "string", "description": "The type of the conversation. Common values include appchat (in-app Copilot interactions) and bizchat (Business Chat / Microsoft 365 Chat interactions).", "examples": [ "appchat", "bizchat" ] }, "requestId": { "type": "string", "description": "The identifier that groups a user prompt with its corresponding Copilot response. Both the prompt and response in a single exchange share the same requestId." }, "sessionId": { "type": "string", "description": "The thread ID or conversation identifier that maps to all Copilot sessions for the user. Groups all interactions within a single conversation session." }, "createdDateTime": { "type": "string", "format": "date-time", "description": "The ISO 8601 date and time when the interaction was created." }, "etag": { "type": "string", "description": "The timestamp of when the interaction was last modified. Used for concurrency control." }, "locale": { "type": "string", "description": "The locale of the sender, in BCP 47 language tag format.", "examples": [ "en-US", "fr-FR", "de-DE" ] }, "from": { "$ref": "#/$defs/identitySet", "description": "The user, application, or device that is associated with this interaction." }, "attachments": { "type": "array", "description": "The collection of documents attached to the interaction, such as cards and images.", "items": { "$ref": "#/$defs/aiInteractionAttachment" } }, "contexts": { "type": "array", "description": "The identifiers that map to all contexts associated with the interaction, such as the file or application in which the interaction occurred.", "items": { "$ref": "#/$defs/aiInteractionContext" } }, "links": { "type": "array", "description": "The collection of links that appear in the interaction, including citation links and reference links.", "items": { "$ref": "#/$defs/aiInteractionLink" } }, "mentions": { "type": "array", "description": "The collection of entities that were mentioned in the interaction, including users, bots, and other entities.", "items": { "$ref": "#/$defs/aiInteractionMention" } } }, "required": [ "id", "interactionType", "createdDateTime" ], "$defs": { "itemBody": { "type": "object", "title": "Item Body", "description": "The body of a message, including the text of the body and its content type.", "properties": { "contentType": { "type": "string", "enum": [ "text", "html" ], "description": "The type of the content. Values include text for plain text content and html for HTML-formatted content." }, "content": { "type": "string", "description": "The content of the body. For userPrompt interactions, this contains the user's question or instruction. For aiResponse interactions, this contains Copilot's generated answer." } }, "required": [ "contentType", "content" ] }, "identitySet": { "type": "object", "title": "Identity Set", "description": "Represents the user, application, or device associated with the interaction. At least one identity property is typically present.", "properties": { "user": { "$ref": "#/$defs/identity", "description": "The user identity associated with the interaction." }, "application": { "$ref": "#/$defs/identity", "description": "The application identity associated with the interaction." }, "device": { "$ref": "#/$defs/identity", "description": "The device identity associated with the interaction." } } }, "identity": { "type": "object", "title": "Identity", "description": "Represents an identity of a user, application, or device.", "properties": { "id": { "type": "string", "description": "The unique identifier of the identity." }, "displayName": { "type": "string", "description": "The display name of the identity." } } }, "aiInteractionAttachment": { "type": "object", "title": "AI Interaction Attachment", "description": "Represents a message attachment such as cards, images, or file references within a Copilot interaction.", "properties": { "attachmentId": { "type": "string", "description": "The identifier for the attachment. This identifier is only unique within the message scope." }, "content": { "type": "string", "description": "The content of the attachment, which may be structured content such as an Adaptive Card JSON payload." }, "contentType": { "type": "string", "description": "The type of the content. Common values include reference, file, and image types such as image/png.", "examples": [ "reference", "file", "image/png", "image/jpeg" ] }, "contentUrl": { "type": "string", "format": "uri", "description": "The URL of the content, pointing to the location of the attached resource." }, "name": { "type": "string", "description": "The display name of the attachment." } } }, "aiInteractionContext": { "type": "object", "title": "AI Interaction Context", "description": "Represents a context associated with a Copilot interaction, identifying the file or resource where the interaction occurred.", "properties": { "contextReference": { "type": "string", "description": "The full file URL where the interaction happened." }, "contextType": { "type": "string", "description": "The type of the file or resource providing context." }, "displayName": { "type": "string", "description": "The human-readable name of the file or resource." } } }, "aiInteractionLink": { "type": "object", "title": "AI Interaction Link", "description": "Represents a link that appears in a Copilot interaction, such as citation links or reference links in responses.", "properties": { "displayName": { "type": "string", "description": "The display name of the link." }, "linkType": { "type": "string", "description": "The type of link, providing information about a link in an app chat or Business Chat (BizChat) interaction." }, "linkUrl": { "type": "string", "format": "uri", "description": "The URL of the link." } } }, "aiInteractionMention": { "type": "object", "title": "AI Interaction Mention", "description": "Represents a mention of an entity (user, bot, or other entity) within a Copilot interaction.", "properties": { "mentioned": { "$ref": "#/$defs/aiInteractionMentionedIdentitySet", "description": "The entity mentioned in the message." }, "mentionId": { "type": "integer", "description": "The numeric identifier for the mention within the interaction." }, "mentionText": { "type": "string", "description": "The text representation of the mention as it appears in the message body." } } }, "aiInteractionMentionedIdentitySet": { "type": "object", "title": "AI Interaction Mentioned Identity Set", "description": "Represents the identity of an entity mentioned in a Copilot interaction.", "properties": { "user": { "$ref": "#/$defs/identity", "description": "A mentioned user identity." }, "application": { "$ref": "#/$defs/identity", "description": "A mentioned application identity." } } } }, "examples": [ { "id": "1234567890", "appClass": "IPM.SkypeTeams.Message.Copilot.Word", "body": { "contentType": "html", "content": "

Summarize this document for me.

" }, "interactionType": "userPrompt", "conversationType": "appchat", "requestId": "req-abc-123", "sessionId": "session-xyz-456", "createdDateTime": "2025-03-15T10:30:00Z", "etag": "1710502200000", "locale": "en-US", "from": { "user": { "id": "user-001", "displayName": "Jane Doe" } }, "attachments": [], "contexts": [ { "contextReference": "https://contoso.sharepoint.com/sites/Sales/Shared Documents/Q4Report.docx", "contextType": "docx", "displayName": "Q4Report.docx" } ], "links": [], "mentions": [] }, { "id": "1234567891", "appClass": "IPM.SkypeTeams.Message.Copilot.Word", "body": { "contentType": "html", "content": "

Here is a summary of the document: The Q4 report outlines revenue growth of 15% year-over-year, driven primarily by the enterprise segment. Key highlights include expansion into three new markets and a 20% increase in customer retention.

" }, "interactionType": "aiResponse", "conversationType": "appchat", "requestId": "req-abc-123", "sessionId": "session-xyz-456", "createdDateTime": "2025-03-15T10:30:05Z", "etag": "1710502205000", "locale": "en-US", "from": { "application": { "id": "copilot-app-001", "displayName": "Microsoft 365 Copilot" } }, "attachments": [], "contexts": [ { "contextReference": "https://contoso.sharepoint.com/sites/Sales/Shared Documents/Q4Report.docx", "contextType": "docx", "displayName": "Q4Report.docx" } ], "links": [ { "displayName": "Q4Report.docx", "linkType": "citation", "linkUrl": "https://contoso.sharepoint.com/sites/Sales/Shared Documents/Q4Report.docx" } ], "mentions": [] } ] }