Microsoft

Microsoft Graph: Teams chats

List and create one-on-one and group chats, send and read chat messages, manage chat members, tabs and pinned messages. This listing is one area of Microsoft…

Communication#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

List and create one-on-one and group chats, send and read chat messages, manage chat members, tabs and pinned messages.

This listing is one area of Microsoft Graph, the single REST API for Microsoft 365, Outlook, OneDrive, Teams and Microsoft Entra ID. It holds 108 of the area's requests, the most direct ones first, generated from Microsoft's own OpenAPI description of Graph v1.0. The other areas (mail, calendar, files, Teams, users and more) are listed separately on the Microsoft page.

Get an access token

  1. Sign in to the Microsoft Entra admin center and open App registrations > New registration. For a quick test, the Graph Explorer signs you in and shows a token without registering anything.
  2. Under API permissions, add the Microsoft Graph permissions this area needs, for example: Chat.Read, Chat.ReadWrite, ChatMessage.Send. Delegated permissions act as the signed-in user; application permissions act as the app itself and need an administrator's consent.
  3. Under Certificates & secrets, create a client secret (keep it out of shared collections).
  4. Get a token from https://login.microsoftonline.com/ /oauth2/v2.0/token: the authorization-code flow for a user, or grant_type=client_credentials with scope=https://graph.microsoft.com/.default for an app. Send it as Authorization: Bearer .

Using these requests

  • Base URL: https://graph.microsoft.com/v1.0. /me/... paths act on the signed-in user; with an application token use /users/{id or userPrincipalName}/... instead.
  • Shape responses with OData query parameters: $select (fields), $filter, $orderby, $top, $expand and $search (some need the ConsistencyLevel: eventual header). Long lists are paged: follow @odata.nextLink.
  • Combine up to 20 requests in one call with POST /$batch.

Common errors

StatusCodeWhat to do
401InvalidAuthenticationTokenThe token is missing, expired or for another resource: get a new one for https://graph.microsoft.com.
403Authorization_RequestDenied / ErrorAccessDeniedAdd the permission listed in the request's docs and grant consent.
404ResourceNotFound / itemNotFoundCheck the id; ids from another user or tenant are not found.
429TooManyRequestsThrottled: wait the Retry-After seconds, then retry.

Docs: Teams chats overview · Permissions reference · Throttling

Endpoints 108

Chats

  • GETList chats/chatsRetrieve 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…
  • POSTCreate chat/chatsCreate a new chat object.
  • GETGet all messages (chat)/chats/getAllMessages()Get all messages from all chats in which a user is a participant, including one-on-one chats, group chats, and meeting chats. To learn more about how to use…
  • GETGet all retained messages (chat)/chats/getAllRetainedMessages()Get all retained messages from all chats that a user is a participant in, including one-on-one chats, group chats, and meeting chats. To learn more about how…
  • GETGet chat/chats/:chat-idRetrieve 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…
  • DELETEDelete chat/chats/:chat-idSoft-delete a chat. When invoked with delegated permissions, this operation only works for tenant admins and Teams service admins.
  • PATCHUpdate chat/chats/:chat-idUpdate the properties of a chat object.
  • POSTHide for user (chat)/chats/:chat-id/hideForUserHide a chat for a user.
  • POSTUnhide for user (chat)/chats/:chat-id/unhideForUserUnhide a chat for a user.
  • POSTStart migration (chat)/chats/:chat-id/startMigrationStart the migration of external messages by enabling migration mode in an existing chat. Import operations were limited to newly created standard channels…
  • POSTComplete migration (chat)/chats/:chat-id/completeMigrationComplete the migration of external messages by removing migration mode from a chat. Complete migration operations were initially restricted to newly created…
  • POSTMark chat read for user (chat)/chats/:chat-id/markChatReadForUserMark a chat as read for a user.
  • POSTMark chat unread for user (chat)/chats/:chat-id/markChatUnreadForUserMark a chat as unread for a user.
  • POSTRemove all access for user (chat)/chats/:chat-id/removeAllAccessForUserRemove access to a chat for a user.
  • POSTSend activity notification (chat)/chats/:chat-id/sendActivityNotificationSend an activity feed notification in scope of a chat. For more information about sending notifications and the requirements for doing so, see sending Teams…

Chats: tabs

  • GETList tabs/chats/:chat-id/tabsRetrieve the list of tabs in the specified chat.
  • POSTCreate tab/chats/:chat-id/tabsAdd (pin) a tab to the specified chat. The corresponding app must already be installed in the chat.
  • GETGet tab/chats/:chat-id/tabs/:teamsTab-idRetrieve the properties and relationships of the specified tab in a chat.
  • DELETEDelete tab/chats/:chat-id/tabs/:teamsTab-idRemove (unpin) a tab from the specified chat.
  • PATCHUpdate tab/chats/:chat-id/tabs/:teamsTab-idUpdate the properties of the specified tab in a chat. This can be used to configure the content of the tab.
  • GETGet teams app/chats/:chat-id/tabs/:teamsTab-id/teamsAppThe application that is linked to the tab. This can't be changed after tab creation.

Chats: members

  • GETList members/chats/:chat-id/membersList all conversation members in a chat or channel.
  • POSTCreate member/chats/:chat-id/membersAdd a conversationMember to a chat.
  • POSTAdd member/chats/:chat-id/members/addAdd multiple members in a single request to a team. The response provides details about which memberships could and couldn't be created.
  • POSTRemove member/chats/:chat-id/members/removeRemove multiple members from a team in a single request. The response provides details about which memberships could and couldn't be removed.
  • GETGet member/chats/:chat-id/members/:conversationMember-idRetrieve a conversationMember from a chat.
  • DELETEDelete member/chats/:chat-id/members/:conversationMember-idRemove a conversationMember from a chat.
  • PATCHUpdate member/chats/:chat-id/members/:conversationMember-id

Chats: messages

  • GETList messages/chats/:chat-id/messagesRetrieve the list of messages in a chat. This method supports federation. To list chat messages in application context, the request must be made from the…
  • POSTCreate message/chats/:chat-id/messagesSend a new chatMessage in the specified chat. This API can't create a new chat; you must use the list chats method to retrieve the ID of an existing chat…
  • GETTrack changes to messages (delta)/chats/:chat-id/messages/delta()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. When you use delta…
  • POSTReply with quote (message)/chats/:chat-id/messages/replyWithQuoteReply with quote to a single chat message or multiple chat messages in a chat.
  • GETGet message/chats/:chat-id/messages/:chatMessage-idRetrieve a single message or a message reply in a channel or a chat.
  • DELETEDelete message/chats/:chat-id/messages/:chatMessage-id
  • PATCHUpdate message/chats/:chat-id/messages/:chatMessage-id
  • GETList replies/chats/:chat-id/messages/:chatMessage-id/repliesReplies for a specified message. Supports $expand for channel messages.
  • POSTCreate reply/chats/:chat-id/messages/:chatMessage-id/replies
  • POSTCreate soft delete/chats/:chat-id/messages/:chatMessage-id/softDeleteDelete a single chatMessage or a chat message reply in a channel or a chat.
  • POSTSet reaction (message)/chats/:chat-id/messages/:chatMessage-id/setReaction
  • POSTCreate unset reaction/chats/:chat-id/messages/:chatMessage-id/unsetReaction
  • GETList hosted contents/chats/:chat-id/messages/:chatMessage-id/hostedContentsRetrieve the list of chatMessageHostedContent objects from a message. This API only lists the hosted content objects. To get the content bytes, see get…
  • POSTCreate hosted content/chats/:chat-id/messages/:chatMessage-id/hostedContents
  • POSTCreate undo soft delete/chats/:chat-id/messages/:chatMessage-id/undoSoftDeleteUndo soft deletion of a single chatMessage or a chat message reply in a channel or a chat.
  • GETTrack changes to replies (delta)/chats/:chat-id/messages/:chatMessage-id/replies/delta()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. When you use delta…
  • POSTReply with quote (reply)/chats/:chat-id/messages/:chatMessage-id/replies/replyWithQuoteReply with quote to a single chat message or multiple chat messages in a chat.
  • GETGet reply/chats/:chat-id/messages/:chatMessage-id/replies/:chatMessage-id1Replies for a specified message. Supports $expand for channel messages.
  • DELETEDelete reply/chats/:chat-id/messages/:chatMessage-id/replies/:chatMessage-id1
  • PATCHUpdate reply/chats/:chat-id/messages/:chatMessage-id/replies/:chatMessage-id1
  • GETGet hosted content/chats/:chat-id/messages/:chatMessage-id/hostedContents/:chatMessageHostedContent-idRetrieve the properties and relationships of chatMessageHostedContent object.
  • DELETEDelete hosted content/chats/:chat-id/messages/:chatMessage-id/hostedContents/:chatMessageHostedContent-id
  • PATCHUpdate hosted content/chats/:chat-id/messages/:chatMessage-id/hostedContents/:chatMessageHostedContent-id
  • POSTCreate soft delete/chats/:chat-id/messages/:chatMessage-id/replies/:chatMessage-id1/softDeleteDelete a single chatMessage or a chat message reply in a channel or a chat.
  • POSTSet reaction (reply)/chats/:chat-id/messages/:chatMessage-id/replies/:chatMessage-id1/setReaction
  • POSTCreate unset reaction/chats/:chat-id/messages/:chatMessage-id/replies/:chatMessage-id1/unsetReaction
  • GETList hosted contents/chats/:chat-id/messages/:chatMessage-id/replies/:chatMessage-id1/hostedContentsContent in a message hosted by Microsoft Teams - for example, images or code snippets.
  • POSTCreate hosted content/chats/:chat-id/messages/:chatMessage-id/replies/:chatMessage-id1/hostedContents
  • POSTCreate undo soft delete/chats/:chat-id/messages/:chatMessage-id/replies/:chatMessage-id1/undoSoftDeleteUndo soft deletion of a single chatMessage or a chat message reply in a channel or a chat.
  • GETDownload message content/chats/:chat-id/messages/:chatMessage-id/hostedContents/:chatMessageHostedContent-id/$valueRetrieve the list of chatMessageHostedContent objects from a message. This API only lists the hosted content objects. To get the content bytes, see get…
  • PUTUpload message content/chats/:chat-id/messages/:chatMessage-id/hostedContents/:chatMessageHostedContent-id/$valueThe unique identifier for an entity. Read-only.
  • DELETEUpload message content/chats/:chat-id/messages/:chatMessage-id/hostedContents/:chatMessageHostedContent-id/$valueThe unique identifier for an entity. Read-only.

Chats: installed apps

  • GETList installed apps/chats/:chat-id/installedAppsList all app installations within a chat.
  • POSTCreate installed app/chats/:chat-id/installedAppsInstall a teamsApp to the specified chat.
  • GETGet installed app/chats/:chat-id/installedApps/:teamsAppInstallation-idGet an app installed in a chat.
  • DELETEDelete installed app/chats/:chat-id/installedApps/:teamsAppInstallation-idUninstall an app installed within a chat.
  • PATCHUpdate installed app/chats/:chat-id/installedApps/:teamsAppInstallation-id
  • POSTUpgrade installed app/chats/:chat-id/installedApps/:teamsAppInstallation-id/upgradeUpgrade an app installation within a chat.
  • GETGet teams app/chats/:chat-id/installedApps/:teamsAppInstallation-id/teamsAppThe app that is installed.
  • GETGet teams app definition/chats/:chat-id/installedApps/:teamsAppInstallation-id/teamsAppDefinitionThe details of this version of the app.

Chats: pinned messages

  • GETList pinned messages/chats/:chat-id/pinnedMessagesGet a list of pinnedChatMessages in a chat.
  • POSTCreate pinned message/chats/:chat-id/pinnedMessagesPin a chat message in the specified chat. This API cannot create a new chat; you must use the list chats method to retrieve the ID of an existing chat before…
  • GETGet pinned message/chats/:chat-id/pinnedMessages/:pinnedChatMessageInfo-idA collection of all the pinned messages in the chat. Nullable.
  • DELETEDelete pinned message/chats/:chat-id/pinnedMessages/:pinnedChatMessageInfo-idUnpin a message from a chat.
  • PATCHUpdate pinned message/chats/:chat-id/pinnedMessages/:pinnedChatMessageInfo-id
  • GETGet message/chats/:chat-id/pinnedMessages/:pinnedChatMessageInfo-id/messageRepresents details about the chat message that is pinned.

Chats: permission grants

  • GETList permission grants/chats/:chat-id/permissionGrantsList all resource-specific permission grants on the chat. This list specifies the Microsoft Entra apps that have access to the chat, along with the…
  • POSTCreate permission grant/chats/:chat-id/permissionGrants
  • GETGet permission grant/chats/:chat-id/permissionGrants/:resourceSpecificPermissionGrant-idA collection of permissions granted to apps for the chat.
  • DELETEDelete permission grant/chats/:chat-id/permissionGrants/:resourceSpecificPermissionGrant-id
  • PATCHUpdate permission grant/chats/:chat-id/permissionGrants/:resourceSpecificPermissionGrant-id

Chats: targeted messages

  • GETList targeted messages/chats/:chat-id/targetedMessagesA collection of targeted messages in the chat that are visible only to specific users. Nullable. You can't expand this relationship using $expand. Targeted…
  • POSTCreate targeted message/chats/:chat-id/targetedMessages
  • GETGet targeted message/chats/:chat-id/targetedMessages/:targetedChatMessage-idA collection of targeted messages in the chat that are visible only to specific users. Nullable. You can't expand this relationship using $expand. Targeted…
  • DELETEDelete targeted message/chats/:chat-id/targetedMessages/:targetedChatMessage-id
  • PATCHUpdate targeted message/chats/:chat-id/targetedMessages/:targetedChatMessage-id
  • GETList replies/chats/:chat-id/targetedMessages/:targetedChatMessage-id/repliesReplies for a specified message. Supports $expand for channel messages.
  • POSTCreate reply/chats/:chat-id/targetedMessages/:targetedChatMessage-id/replies
  • GETList hosted contents/chats/:chat-id/targetedMessages/:targetedChatMessage-id/hostedContentsContent in a message hosted by Microsoft Teams - for example, images or code snippets.
  • POSTCreate hosted content/chats/:chat-id/targetedMessages/:targetedChatMessage-id/hostedContents
  • GETTrack changes to replies (delta)/chats/:chat-id/targetedMessages/:targetedChatMessage-id/replies/delta()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. When you use delta…
  • POSTReply with quote (reply)/chats/:chat-id/targetedMessages/:targetedChatMessage-id/replies/replyWithQuoteReply with quote to a single chat message or multiple chat messages in a chat.
  • GETGet reply/chats/:chat-id/targetedMessages/:targetedChatMessage-id/replies/:chatMessage-idReplies for a specified message. Supports $expand for channel messages.
  • DELETEDelete reply/chats/:chat-id/targetedMessages/:targetedChatMessage-id/replies/:chatMessage-id
  • PATCHUpdate reply/chats/:chat-id/targetedMessages/:targetedChatMessage-id/replies/:chatMessage-id
  • GETGet hosted content/chats/:chat-id/targetedMessages/:targetedChatMessage-id/hostedContents/:chatMessageHostedContent-idContent in a message hosted by Microsoft Teams - for example, images or code snippets.
  • DELETEDelete hosted content/chats/:chat-id/targetedMessages/:targetedChatMessage-id/hostedContents/:chatMessageHostedContent-id
  • PATCHUpdate hosted content/chats/:chat-id/targetedMessages/:targetedChatMessage-id/hostedContents/:chatMessageHostedContent-id
  • POSTCreate soft delete/chats/:chat-id/targetedMessages/:targetedChatMessage-id/replies/:chatMessage-id/softDeleteDelete a single chatMessage or a chat message reply in a channel or a chat.
  • POSTSet reaction (reply)/chats/:chat-id/targetedMessages/:targetedChatMessage-id/replies/:chatMessage-id/setReaction
  • POSTCreate unset reaction/chats/:chat-id/targetedMessages/:targetedChatMessage-id/replies/:chatMessage-id/unsetReaction
  • GETList hosted contents/chats/:chat-id/targetedMessages/:targetedChatMessage-id/replies/:chatMessage-id/hostedContentsContent in a message hosted by Microsoft Teams - for example, images or code snippets.
  • POSTCreate hosted content/chats/:chat-id/targetedMessages/:targetedChatMessage-id/replies/:chatMessage-id/hostedContents
  • POSTCreate undo soft delete/chats/:chat-id/targetedMessages/:targetedChatMessage-id/replies/:chatMessage-id/undoSoftDeleteUndo soft deletion of a single chatMessage or a chat message reply in a channel or a chat.
  • GETDownload targeted message content/chats/:chat-id/targetedMessages/:targetedChatMessage-id/hostedContents/:chatMessageHostedContent-id/$valueThe unique identifier for an entity. Read-only.
  • PUTUpload targeted message content/chats/:chat-id/targetedMessages/:targetedChatMessage-id/hostedContents/:chatMessageHostedContent-id/$valueThe unique identifier for an entity. Read-only.
  • DELETEUpload targeted message content/chats/:chat-id/targetedMessages/:targetedChatMessage-id/hostedContents/:chatMessageHostedContent-id/$valueThe unique identifier for an entity. Read-only.

Chats: last message preview

  • GETGet last message preview/chats/:chat-id/lastMessagePreviewPreview 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.
  • DELETEDelete last message preview/chats/:chat-id/lastMessagePreview
  • PATCHUpdate last message preview/chats/:chat-id/lastMessagePreview

API details

Base URL
https://graph.microsoft.com/v1.0
Authentication
OAuth 2.0 (authorization code, client credentials flows)
Operations
108 operations on 64 pathsPOST 40GET 38DELETE 15PATCH 13PUT 2
Main resources
Chats: messages 32Chats: targeted messages 26Chats 15Chats: installed apps 8Chats: members 7Chats: pinned messages 6Chats: tabs 6Chats: permission grants 5Chats: last message preview 3
Description format
OpenAPI 3.0.4, API version v1.0

How to test the Microsoft Graph: Teams chats in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Microsoft Graph: Teams chats collection, without the publisher's secrets.
  3. Add your credentialsThis API uses OAuth 2.0 (authorization code, client credentials flows). Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “List chats” (GET /chats), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Microsoft Graph: Teams chats?

List and create one-on-one and group chats, send and read chat messages, manage chat members, tabs and pinned messages. This listing is one area of Microsoft… It is listed under Communication and has 108 endpoints.

Who publishes the Microsoft Graph: Teams chats?

It is listed from Microsoft's public API description (an OpenAPI document), not published by Microsoft on Swastik Codes. Anyone who controls microsoft.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Microsoft Graph: Teams chats?

Requests go to https://graph.microsoft.com/v1.0. Endpoint paths are added to this base URL.

How do I authenticate with the Microsoft Graph: Teams chats?

With OAuth 2.0 (authorization code, client credentials flows).

How many endpoints does the Microsoft Graph: Teams chats have?

108 operations on 64 paths (40 POST, 38 GET, 15 DELETE, 13 PATCH, 2 PUT). The largest groups are Chats: messages, Chats: targeted messages, Chats, Chats: installed apps.

Is forking the Microsoft Graph: Teams chats free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.