ChatMessage.Read | Graph Permissions

Permission Details

Delegated Permission

Read user chat messages

Allows an app to read one-to-one and group chat messages, on behalf of the signed-in user.

Permission ID: cdcdac3a-fd45-410d-83ef-554db620e5c7

Properties

Microsoft Graph v1.0 exact-category-docs

Properties is shown from stable Microsoft Graph v1.0 metadata.

Property	Type	Description
`attachments`	`chatMessageAttachment collection`	References to attached objects like files, tabs, meetings etc.
`body`	`itemBody`	Plaintext/HTML representation of the content of the chat message. Representation is specified by the contentType inside the body. The content is always in HTML if the chat message contains a chatMessageMention.
`chatId`	`string`Nullable	If the message was sent in a chat, represents the identity of the chat.
`channelIdentity`	`channelIdentity`	If the message was sent in a channel, represents identity of the channel.
`createdDateTime`	`dateTimeOffset`Nullable	Timestamp of when the chat message was created.
`deletedDateTime`	`dateTimeOffset`Nullable	Read-only. Timestamp at which the chat message was deleted, or null if not deleted.
`etag`	`string`Nullable	Read-only. Version number of the chat message.
`eventDetail`	`eventMessageDetail`	Read-only. If present, represents details of an event that happened in a chat, a channel, or a team, for example, adding new members. For event messages, the messageType property will be set to systemEventMessage.
`from`	`chatMessageFromIdentitySet`	Details of the sender of the chat message. Can only be set during migration.
`id`	`String`	Read-only. Unique ID of the message. IDs are unique within a chat/channel/reply-to-message, but might be duplicated in other chats/channels/reply-to-messages.
`importance`	`string`	The importance of the chat message. The possible values are: normal, high, urgent.
`lastModifiedDateTime`	`dateTimeOffset`Nullable	Read-only. Timestamp when the chat message is created (initial setting) or modified, including when a reaction is added or removed.
`lastEditedDateTime`	`dateTimeOffset`Nullable	Read-only. Timestamp when edits to the chat message were made. Triggers an "Edited" flag in the Teams UI. If no edits are made the value is null.
`locale`	`string`	Locale of the chat message set by the client. Always set to en-us.
`mentions`	`chatMessageMention collection`	List of entities mentioned in the chat message. Supported entities are: user, bot, team, channel, chat, and tag.

Showing 15 of 25 properties.

JSON Representation

Microsoft Graph v1.0 exact-category-docs

JSON representation is shown from stable Microsoft Graph v1.0 metadata.

JSON representation

{
  "attachments": [
    {
      "@odata.type": "microsoft.graph.chatMessageAttachment"
    }
  ],
  "body": {
    "@odata.type": "microsoft.graph.itemBody"
  },
  "channelIdentity": {
    "@odata.type": "microsoft.graph.channelIdentity"
  },
  "chatId": "String",
  "createdDateTime": "String (timestamp)",
  "deletedDateTime": "String (timestamp)",
  "etag": "String",
  "eventDetail": {
    "@odata.type": "microsoft.graph.eventMessageDetail"
  },
  "from": {
    "@odata.type": "microsoft.graph.chatMessageFromIdentitySet"
  },
  "id": "String (identifier)",
  "importance": "String",
  "lastEditedDateTime": "String (timestamp)",
  "lastModifiedDateTime": "String (timestamp)",
  "locale": "String",
  "mentions": [
    {
      "@odata.type": "microsoft.graph.chatMessageMention"
    }
  ],
  "messageHistory": [
    {
      "@odata.type": "microsoft.graph.chatMessageHistoryItem"
    }
  ],
  "messageType": "String",
  "policyViolation": {
    "@odata.type": "microsoft.graph.chatMessagePolicyViolation"
  },
  "reactions": [
    {
      "@odata.type": "microsoft.graph.chatMessageReaction"
    }
  ],
  "replyToId": "String (identifier)",
  "subject": "String",
  "summary": "String",
  "webUrl": "String"
}

Relationships

Microsoft Graph v1.0 exact-category-docs

Relationships is shown from stable Microsoft Graph v1.0 metadata.

Relationship	Type	Description
`hostedContents`	`chatMessageHostedContent collection`	Content in a message hosted by Microsoft Teams - for example, images or code snippets.
`replies`	`chatMessage collection`	Replies for a specified message. Supports $expand for channel messages.
`attachments`	`chatMessageAttachment collection`	References to attached objects like files, tabs, meetings etc.
`body`	`itemBody`	Related body data exposed by this resource.
`importance`	`chatMessageImportance`	Related importance data exposed by this resource.
`mentions`	`chatMessageMention collection`	List of entities mentioned in the chat message. Supported entities are: user, bot, team, channel, chat, and tag.
`messageHistory`	`chatMessageHistoryItem collection`	List of activity history of a message item, including modification time and actions, such as reactionAdded, reactionRemoved, or reaction changes, on the message.
`messageType`	`chatMessageType`	Related messageType data exposed by this resource.
`reactions`	`chatMessageReaction collection`	Reactions for this chat message (for example, Like).
`citations`	`chatMessageCitation collection`	Read-only. Inline citations that reference external sources cited in the message. Citations are system-generated for bot messages and appear as a typed collection.

Graph Methods

Delegated access App-only access

No Learn or OpenAPI mapping available

Microsoft Graph v1.0 endpoints are not available from refreshed Microsoft Learn or Microsoft Graph OpenAPI metadata for this permission.

No API methods available for this version.

No Learn or OpenAPI mapping available

Microsoft Graph beta endpoints are not available from refreshed Microsoft Learn or Microsoft Graph OpenAPI metadata for this permission.

No API methods available for this version.

No Microsoft Learn PowerShell mapping available

Microsoft Graph PowerShell v1.0 commands are not available from refreshed Microsoft Learn PowerShell snippets for this permission.

No deterministic PowerShell command map is available for this permission.

Browse PowerShell docs

No Microsoft Learn PowerShell mapping available

Microsoft Graph PowerShell beta commands are not available from refreshed Microsoft Learn PowerShell snippets for this permission.

No deterministic PowerShell command map is available for this permission.

Browse PowerShell docs

Code Examples

C# / .NET SDK

using Azure.Identity;
using Microsoft.Graph;

var scopes = new[] { "ChatMessage.Read" };
var credential = new InteractiveBrowserCredential(
    new InteractiveBrowserCredentialOptions
    {
        ClientId = "YOUR_CLIENT_ID",
        TenantId = "YOUR_TENANT_ID",
        RedirectUri = new Uri("http://localhost")
    });

var graphClient = new GraphServiceClient(credential, scopes);
var response = await graphClient
    .WithUrl("https://graph.microsoft.com/v1.0/chatmessage")
    .GetAsync();

JavaScript

import { Client } from "@microsoft/microsoft-graph-client";
import { InteractiveBrowserCredential } from "@azure/identity";

const credential = new InteractiveBrowserCredential({
  clientId: "YOUR_CLIENT_ID",
  tenantId: "YOUR_TENANT_ID",
  redirectUri: "http://localhost"
});

const token = await credential.getToken(["ChatMessage.Read"]);
const client = Client.init({
  authProvider: (done) => done(null, token.token)
});

const response = await client.api("/chatmessage").get();

PowerShell

Connect-MgGraph -Scopes "ChatMessage.Read"
Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/v1.0/chatmessage"

Python

from azure.identity import InteractiveBrowserCredential
import requests

credential = InteractiveBrowserCredential(
    client_id="YOUR_CLIENT_ID",
    tenant_id="YOUR_TENANT_ID"
)

token = credential.get_token("ChatMessage.Read")
response = requests.get(
    "https://graph.microsoft.com/v1.0/chatmessage",
    headers={"Authorization": f"Bearer {token.token}"}
)

print(response.json())

App Registration

1

Navigate to Azure Portal

Go to App registrations in Microsoft Entra admin center

2

Add API Permission

Select your app → API permissions → Add a permission → Microsoft Graph

3

Select Permission Type

Choose Delegated permissions and search for ChatMessage.Read

4

Grant Admin Consent

Users can consent to this permission during sign-in.

Frequently asked questions

What is the ChatMessage.Read Microsoft Graph permission?

ChatMessage.Read is a delegated permission in the Microsoft Graph API, grouped under the ChatMessage category. Allows an app to read one-to-one and group chat messages, on behalf of the signed-in user. It grants read-only access to resources. Users can consent to this permission during sign-in. It is mapped to the Microsoft Graph chatmessage resource type.

Is ChatMessage.Read an application or a delegated permission?

ChatMessage.Read is a delegated permission only. It grants access on behalf of a signed-in user and cannot be used for app-only access.

Does ChatMessage.Read require admin consent?

Users can consent to this permission during sign-in.

What is the permission ID (GUID) for ChatMessage.Read?

For ChatMessage.Read, the delegated (OAuth2 scope) ID is cdcdac3a-fd45-410d-83ef-554db620e5c7. These are the real Microsoft Graph identifiers and can be used directly in an app registration manifest.