Microsoft Graph Chats is the part of the Microsoft Graph API that lets developers build apps that read, create, and manage Microsoft Teams chats and chat messages. With it, you can list a user’s 1:1, group, and meeting chats; get chat details and members; create new chats; add or remove participants; and send or read messages.
openapi: 3.1.0
info:
title: Microsoft Graph Chats
description: Needs a description.
paths:
/chats:
description: Provides operations to manage the collection of chat entities.
get:
tags:
- Chats.chat
summary: Microsoft Graph List chats
description: >-
Retrieve the list of chats that the user is part of. This method
supports federation. When a user ID is provided, the calling application
must belong to the same tenant that the user belongs to.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/chat-list?view=graph-rest-1.0
operationId: chats.chat.ListChat
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: '#/components/responses/microsoft.graph.chatCollectionResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- Chats.chat
summary: Microsoft Graph Create chat
description: Create a new chat object.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/chat-post?view=graph-rest-1.0
operationId: chats.chat.CreateChat
requestBody:
description: New entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.chat'
required: true
responses:
2XX:
description: Created entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.chat'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/chats/{chat-id}:
description: Provides operations to manage the collection of chat entities.
get:
tags:
- Chats.chat
summary: Microsoft Graph Get chat
description: >-
Retrieve a single chat (without its messages). This method supports
federation. To access a chat, at least one chat member must belong to
the tenant the request initiated from.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/chat-get?view=graph-rest-1.0
operationId: chats.chat.GetChat
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.chat'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- Chats.chat
summary: Microsoft Graph Update chat
description: Update the properties of a chat object.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/chat-patch?view=graph-rest-1.0
operationId: chats.chat.UpdateChat
requestBody:
description: New property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.chat'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.chat'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- Chats.chat
summary: Microsoft Graph Delete chat
description: >-
Soft-delete a chat. When invoked with delegated permissions, this
operation only works for tenant admins and Teams service admins.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/chat-delete?view=graph-rest-1.0
operationId: chats.chat.DeleteChat
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: chat-id
in: path
description: The unique identifier of chat
required: true
schema:
type: string
x-ms-docs-key-type: chat
/chats/{chat-id}/installedApps:
description: >-
Provides operations to manage the installedApps property of the
microsoft.graph.chat entity.
get:
tags:
- chats.teamsAppInstallation
summary: Microsoft Graph List apps in chat
description: List all app installations within a chat.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/chat-list-installedapps?view=graph-rest-1.0
operationId: chats.ListInstalledApps
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.teamsAppInstallationCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- chats.teamsAppInstallation
summary: Microsoft Graph Add app to chat
description: Install a teamsApp to the specified chat.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/chat-post-installedapps?view=graph-rest-1.0
operationId: chats.CreateInstalledApps
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.teamsAppInstallation'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.teamsAppInstallation'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: chat-id
in: path
description: The unique identifier of chat
required: true
schema:
type: string
x-ms-docs-key-type: chat
/chats/{chat-id}/installedApps/{teamsAppInstallation-id}:
description: >-
Provides operations to manage the installedApps property of the
microsoft.graph.chat entity.
get:
tags:
- chats.teamsAppInstallation
summary: Microsoft Graph Get installed app in chat
description: Get an app installed in a chat.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/chat-get-installedapps?view=graph-rest-1.0
operationId: chats.GetInstalledApps
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.teamsAppInstallation'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- chats.teamsAppInstallation
summary: Microsoft Graph Update the navigation property installedApps in chats
operationId: chats.UpdateInstalledApps
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.teamsAppInstallation'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.teamsAppInstallation'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- chats.teamsAppInstallation
summary: Microsoft Graph Uninstall app in a chat
description: Uninstall an app installed within a chat.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/chat-delete-installedapps?view=graph-rest-1.0
operationId: chats.DeleteInstalledApps
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: chat-id
in: path
description: The unique identifier of chat
required: true
schema:
type: string
x-ms-docs-key-type: chat
- name: teamsAppInstallation-id
in: path
description: The unique identifier of teamsAppInstallation
required: true
schema:
type: string
x-ms-docs-key-type: teamsAppInstallation
/chats/{chat-id}/installedApps/{teamsAppInstallation-id}/upgrade:
description: Provides operations to call the upgrade method.
post:
tags:
- chats.teamsAppInstallation
summary: Microsoft Graph Invoke action upgrade
description: Upgrade an app installation within a chat.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/chat-teamsappinstallation-upgrade?view=graph-rest-1.0
operationId: chats.chat.installedApps.teamsAppInstallation.upgrade
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
consentedPermissionSet:
anyOf:
- $ref: >-
#/components/schemas/microsoft.graph.teamsAppPermissionSet
- type: object
nullable: true
required: true
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
parameters:
- name: chat-id
in: path
description: The unique identifier of chat
required: true
schema:
type: string
x-ms-docs-key-type: chat
- name: teamsAppInstallation-id
in: path
description: The unique identifier of teamsAppInstallation
required: true
schema:
type: string
x-ms-docs-key-type: teamsAppInstallation
/chats/{chat-id}/installedApps/{teamsAppInstallation-id}/teamsApp:
description: >-
Provides operations to manage the teamsApp property of the
microsoft.graph.teamsAppInstallation entity.
get:
tags:
- chats.teamsAppInstallation
summary: Microsoft Graph Get teamsApp from chats
description: The app that is installed.
operationId: chats.installedApps.GetTeamsApp
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.teamsApp'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: chat-id
in: path
description: The unique identifier of chat
required: true
schema:
type: string
x-ms-docs-key-type: chat
- name: teamsAppInstallation-id
in: path
description: The unique identifier of teamsAppInstallation
required: true
schema:
type: string
x-ms-docs-key-type: teamsAppInstallation
/chats/{chat-id}/installedApps/{teamsAppInstallation-id}/teamsAppDefinition:
description: >-
Provides operations to manage the teamsAppDefinition property of the
microsoft.graph.teamsAppInstallation entity.
get:
tags:
- chats.teamsAppInstallation
summary: Microsoft Graph Get teamsAppDefinition from chats
description: The details of this version of the app.
operationId: chats.installedApps.GetTeamsAppDefinition
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.teamsAppDefinition'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: chat-id
in: path
description: The unique identifier of chat
required: true
schema:
type: string
x-ms-docs-key-type: chat
- name: teamsAppInstallation-id
in: path
description: The unique identifier of teamsAppInstallation
required: true
schema:
type: string
x-ms-docs-key-type: teamsAppInstallation
/chats/{chat-id}/installedApps/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- chats.teamsAppInstallation
summary: Microsoft Graph Get the number of the resource
operationId: chats.installedApps.GetCount-3987
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: chat-id
in: path
description: The unique identifier of chat
required: true
schema:
type: string
x-ms-docs-key-type: chat
/chats/{chat-id}/lastMessagePreview:
description: >-
Provides operations to manage the lastMessagePreview property of the
microsoft.graph.chat entity.
get:
tags:
- chats.chatMessageInfo
summary: Microsoft Graph Get lastMessagePreview from chats
description: >-
Preview of the last message sent in the chat. Null if no messages were
sent in the chat. Currently, only the list chats operation supports this
property.
operationId: chats.GetLastMessagePreview
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.chatMessageInfo'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- chats.chatMessageInfo
summary: Microsoft Graph Update the navigation property lastMessagePreview in chats
operationId: chats.UpdateLastMessagePreview
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.chatMessageInfo'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.chatMessageInfo'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- chats.chatMessageInfo
summary: Microsoft Graph Delete navigation property lastMessagePreview for chats
operationId: chats.DeleteLastMessagePreview
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: chat-id
in: path
description: The unique identifier of chat
required: true
schema:
type: string
x-ms-docs-key-type: chat
/chats/{chat-id}/members:
description: >-
Provides operations to manage the members property of the
microsoft.graph.chat entity.
get:
tags:
- chats.conversationMember
summary: Microsoft Graph List conversationMembers
description: List all conversation members in a chat or channel.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/conversationmember-list?view=graph-rest-1.0
operationId: chats.ListMembers
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.conversationMemberCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- chats.conversationMember
summary: Microsoft Graph Add member to a chat
description: Add a conversationMember to a chat.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/chat-post-members?view=graph-rest-1.0
operationId: chats.CreateMembers
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.conversationMember'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.conversationMember'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: chat-id
in: path
description: The unique identifier of chat
required: true
schema:
type: string
x-ms-docs-key-type: chat
/chats/{chat-id}/members/{conversationMember-id}:
description: >-
Provides operations to manage the members property of the
microsoft.graph.chat entity.
get:
tags:
- chats.conversationMember
summary: Microsoft Graph Get conversationMember in a chat
description: Retrieve a conversationMember from a chat.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/chat-get-members?view=graph-rest-1.0
operationId: chats.GetMembers
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.conversationMember'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- chats.conversationMember
summary: Microsoft Graph Update the navigation property members in chats
operationId: chats.UpdateMembers
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.conversationMember'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.conversationMember'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- chats.conversationMember
summary: Microsoft Graph Remove member from chat
description: Remove a conversationMember from a chat.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/chat-delete-members?view=graph-rest-1.0
operationId: chats.DeleteMembers
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: chat-id
in: path
description: The unique identifier of chat
required: true
schema:
type: string
x-ms-docs-key-type: chat
- name: conversationMember-id
in: path
description: The unique identifier of conversationMember
required: true
schema:
type: string
x-ms-docs-key-type: conversationMember
/chats/{chat-id}/members/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- chats.conversationMember
summary: Microsoft Graph Get the number of the resource
operationId: chats.members.GetCount-9627
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: chat-id
in: path
description: The unique identifier of chat
required: true
schema:
type: string
x-ms-docs-key-type: chat
/chats/{chat-id}/members/add:
description: Provides operations to call the add method.
post:
tags:
- chats.conversationMember
summary: Microsoft Graph Invoke action add
description: >-
Add multiple members in a single request to a team. The response
provides details about which memberships could and couldn't be created.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/conversationmembers-add?view=graph-rest-1.0
operationId: chats.chat.members.add
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.conversationMember'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/BaseCollectionPaginationCountResponse'
- type: object
properties:
value:
type: array
items:
$ref: >-
#/components/schemas/microsoft.graph.actionResultPart
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
parameters:
- name: chat-id
in: path
description: The unique identifier of chat
required: true
schema:
type: string
x-ms-docs-key-type: chat
/chats/{chat-id}/members/remove:
description: Provides operations to call the remove method.
post:
tags:
- chats.conversationMember
summary: Microsoft Graph Invoke action remove
description: >-
Remove multiple members from a team in a single request. The response
provides details about which memberships could and couldn't be removed.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/conversationmember-remove?view=graph-rest-1.0
operationId: chats.chat.members.remove
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.conversationMember'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/BaseCollectionPaginationCountResponse'
# --- truncated at 32 KB (440 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-graph/refs/heads/main/openapi/chats-openapi-original.yml