chat resource type

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Represents a chat that is a collection of chatMessages between one or more participants. Participants can be users or apps.

Note: If the chat is associated with an onlineMeeting instance, some of the listed methods transitively impact the meeting.

Methods

Method Return Type Description
Chat management
List chats chat collection Get the list of chats a user is part of.
Create chat chat Create a new chat.
Get chat chat Read properties and relationships of the chat.
Update chat chat Update properties of the chat.
Delete None Delete a chat.
Remove all access for user None Remove access to a chat for a user.
List members conversationMember collection Get the list of all users in the chat.
Add member Location header Add a user to the chat.
Get member conversationMember Get a single user in the chat.
Remove member None Remove a user from the chat.
Get chat between user and app chat Get one-on-one chat between user and the app.
Mark chat as read None Mark chat as read for a user.
Mark chat as unread None Mark chat as unread for a user.
Hide chat None Hide a chat for a user.
Unhide chat None Unhide a chat for a user.
Messages
List messages in a chat chatMessage Get messages in a chat.
Get message reply chatMessage Get a single message in a chat.
Get messages across all chats chat collection Get messages from all chats that a user is a participant in.
Get retained messages across all chats chatMessage collection Get all retained messages from all chats that a user is a participant in, including one-on-one chats, group chats, and meeting chats.
Get delta chat messages for user chatMessage collection Get the list of messages from all chats in which a user is a participant, including one-on-one chats, group chats, and meeting chats.
Apps
List apps in chat teamsAppInstallation collection List apps installed in a chat (and associated meeting).
Get app installed in chat teamsAppInstallation Get a specific app installed in a chat (and associated meeting).
Add app in chat Add (install) an app in a chat (and associated meeting).
Upgrade app installed in chat None Update to the latest version of the app installed in chat (and associated meeting).
Remove app from chat None Remove (uninstall) app from a chat (and associated meeting).
List permission grants resourceSpecificPermissionGrant collection List permissions granted to the apps in this chat.
Tabs
List tabs in chat teamsTab List tabs pinned to a chat (and associated meeting).
Get tab in chat teamsTab Get a specific tab pinned to a chat (and associated meeting).
Add tab to chat teamsTab Add (pin) a tab to a chat (and associated meeting).
Update tab in chat teamsTab Update the properties of a tab in a chat (and associated meeting).
Remove tab from chat None Remove (unpin) a tab from a chat (and associated meeting).
Operations
List operations teamsAsyncOperation collection Get the list of async operations that ran or are running on the chat.
Get operation on chat teamsAsyncOperation Get a single async operation that ran or is running on the chat.
Pinned messages
List pinned messages pinnedChatMessageInfo collection Get a list of pinned messages in a chat.
Pin message pinnedChatMessageInfo Pin a chat message in a chat.
Unpin message None Unpin a message from a chat.

Note: When using application permissions, be sure you know how to get the chat ID. Because listing chats with application permissions is not supported, not all scenarios are possible. It is possible to get chat IDs with delegated permissions, and from change notifications for /chats/getAllMessages with application permissions.

Properties

Property Type Description
chatType chatType Specifies the type of chat. Possible values are: group, oneOnOne, meeting, unknownFutureValue.
createdBy identitySet The user or application that created the chat. Read-only.
createdDateTime dateTimeOffset Date and time at which the chat was created. Read-only.
id String The chat's unique identifier. Read-only.
isHiddenForAllMembers Boolean Indicates whether the chat is hidden for all its members. Read-only.
lastUpdatedDateTime dateTimeOffset Date and time at which the chat was renamed or list of members were last changed. Read-only.
onlineMeetingInfo teamworkOnlineMeetingInfo Represents details about an online meeting. If the chat isn't associated with an online meeting, the property is empty. Read-only.
tenantId String The identifier of the tenant in which the chat was created. Read-only.
topic String (Optional) Subject or topic for the chat. Only available for group chats.
viewpoint chatViewpoint Represents caller-specific information about the chat, such as last message read date and time. This property is populated only when the request is made in a delegated context.
webUrl String The URL for the chat in Microsoft Teams. The URL should be treated as an opaque blob, and not parsed. Read-only.

chatType values

Member Description
oneOnOne Indicates that the chat is a 1:1 chat. The roster size is fixed for this type of chat; members can't be removed/added.
group Indicates that the chat is a group chat. The roster size (of at least two people) can be updated for this type of chat. Members can be removed/added later.
meeting Indicates that the chat is associated with an online meeting. This type of chat is only created as part of the creation of an online meeting.
unknownFutureValue Evolvable enumeration sentinel value. Don't use.

Relationships

Relationship Type Description
installedApps teamsAppInstallation collection A collection of all the apps in the chat. Nullable.
lastMessagePreview chatMessageInfo Preview of the last message sent in the chat. Null if no messages are sent in the chat. Currently, only the list chats operation supports this property.
members conversationMember collection A collection of all the members in the chat. Nullable.
messages chatMessage collection A collection of all the messages in the chat. Nullable.
operations teamsAsyncOperation collection A collection of all the Teams async operations that ran or are running on the chat. Nullable.
permissionGrants resourceSpecificPermissionGrant collection A collection of permissions granted to apps for the chat.
pinnedMessages pinnedChatMessageInfo collection A collection of all the pinned messages in the chat. Nullable.
tabs teamsTab collection A collection of all the tabs in the chat. Nullable.

JSON representation

The following JSON representation shows the resource type.

{
  "chatType": "String",
  "createdBy": {"@odata.type": "microsoft.graph.identitySet"},
  "createdDateTime": "String (timestamp)",
  "id": "string (identifier)",
  "isHiddenForAllMembers": "Boolean",
  "lastUpdatedDateTime": "String (timestamp)",  
  "onlineMeetingInfo": {
    "@odata.type": "microsoft.graph.teamworkOnlineMeetingInfo"
  },
  "tenantId": "String",  
  "topic": "String",
  "viewpoint": {
    "@odata.type": "microsoft.graph.chatViewpoint"
  },
  "webUrl": "String"
}