MS Teams – Chats – Get Chats

Get a list of chats for a specific user.

Action details

Property	Value
Action label	MS Teams – Chats – Get Chats
Category	CloudTools
Apex class and method	GetMSTeamsChats.getChats
Input type	GetMSTeamsChats.GetMSTeamsChatsInput
Output type	List<List<MSTeamsChat>>
Authorization	Microsoft 365 connector; check endpoint support for delegated and application access.
Microsoft Graph request	GET /me/chats (delegated) or /users/{userId}/chats (application)

Prerequisites and permissions

Configure a CloudTools Connector with Connector Type set to Microsoft 365. Complete Microsoft sign-in for OAuth Delegated (Authorization Code). For endpoints supporting OAuth Application (Client Credentials), grant application permissions and administrator consent. The identity must have access to the selected resource. See Creating an Entra ID App and Integration Connectors for setup.

The action permission provider declares these alternatives; they are not cumulative requirements and not all are least privileged. Resource-specific permissions require consent for the relevant Teams resource.

Permission type	Declared alternatives
Delegated	Chat.ReadBasic, Chat.Read, Chat.ReadWrite
Application	Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Endpoints: /me/chats; /users/{idOrUserPrincipalName}/chats

See the Microsoft operation and permissions reference.

Inputs

Input	Apex field	Type	Required	Description
User Id	userId	String	No	User identifier
Top	topQuery	String	No	Max number of chats to return
Filter	filterQuery	String	No	OData filter expression
Order By	orderByQuery	String	No	OData order expression
Expand	expandQuery	String	No	Related entities to expand (for example: members,lastMessagePreview)
App Tenant Only	appTenantOnly	Boolean	No	When true, only chats in the app connector tenant are returned.

Supply a nonempty list with a non-null first request. This implementation processes only the first request and does not bulk-process Flow interviews. Global inputs do not expose connectorId; Flow and subscriber Apex use CloudTools connector selection. Use Microsoft Graph IDs, not Salesforce IDs or browser links. Resolve dynamic values before invoking this action.

Outputs

Returns an outer list containing one collection of MSTeamsChat items. A missing or unmappable collection produces an empty inner list. The outer list does not correspond to every input request.

Output	Apex field	Type	Description
Id	id	String	Unique identifier of the chat
Topic	topic	String	Topic of the chat (group or meeting chats)
Created Date Time	createdDateTime	String	Created timestamp for the chat
Last Updated Date Time	lastUpdatedDateTime	String	Last updated timestamp for the chat
Chat Type	chatType	String	Type of chat (oneOnOne, group, meeting)
Web URL	webUrl	String	Link to the chat in Teams
Is Hidden For All Members	isHiddenForAllMembers	Boolean	Whether the chat is hidden for all members
Viewpoint	chatViewpoint	MSTeamsChatViewpoint	Chat viewpoint data for the signed-in user
Members	members	List<MSTeamsConversationMember>	Members in the chat (available with $expand=members)
Last Message Preview	lastMessagePreview	MSTeamsMessagePreview	Preview details of the latest message
OData Type	odataType	String	OData type for the chat
OData ETag	odataEtag	String	OData ETag for the chat
Additional Properties	additionalProperties	List<DynamicObject>	Additional properties from user-defined query

Behavior and limits

Only the returned value collection is mapped; this action does not follow or expose @odata.nextLink. A result may contain only the first page.

Nonblank query values are forwarded to Microsoft. Query support and syntax depend on the endpoint; the connector does not make unsupported OData options valid.

MSTeamsAction uses /me/chats for delegated access, ignoring User Id in that path. Its application user-chat path is /users/{userId}/chats; message mutations instead use /chats/{chatId} where shown above. Check the Microsoft reference if a user-scoped path is rejected.

App Tenant Only defaults to true. The filter obtains the tenant from the default MSENTRA connector, rather than the selected request connector. It compares tenantId on the chat and expanded members; when a tenant is configured, chats without matching tenant metadata are excluded. Expand members where needed. User Id is required for application access. Disable App Tenant Only deliberately if cross-tenant results are needed.

Use in Flow

Add MS Teams – Chats – Get Chats where supported. Use a Microsoft 365 application connector configured as Set as default for Flow automations only if the endpoint supports the required application operation. Delegated connections are not supported for CloudTools Flow automation. Supply required values, retain outputs, and add fault handling.

Use in custom Apex

This subscriber-org example uses the Apptigent namespace. Replace example identifiers and values before use. Configure the connector, arrange authorization first, run in a context permitting callouts, and handle exceptions and empty results.

Apptigent.GetMSTeamsChats.GetMSTeamsChatsInput request =
    new Apptigent.GetMSTeamsChats.GetMSTeamsChatsInput();
request.userId = 'REPLACE_WITH_USER_ID';
request.topQuery = '20';
request.filterQuery = 'chatType eq \'group\'';
request.orderByQuery = 'createdDateTime desc';
request.expandQuery = 'members,lastMessagePreview';
request.appTenantOnly = true;

List<List<Apptigent.MSTeamsChat>> results =
    Apptigent.GetMSTeamsChats.getChats(
        new List<Apptigent.GetMSTeamsChats.GetMSTeamsChatsInput>{ request }
    );
System.debug(results);

Use in a Lightning Web Component

Use getMSTeamsChats from msTeamsConnectorLib through MSTeamsConnectorController. Set request.connectorId to select a configured connector. These c/ imports apply in the same namespace. The controller uses a shared request DTO; its field names differ from the global invocable input.

Global input	LWC request mapping
userId	request.userId
topQuery	request.topQuery
filterQuery	request.filterQuery
orderByQuery	request.orderByQuery
expandQuery	request.expandQuery
appTenantOnly	request.appTenantOnly

teamsActionExample.js

import { LightningElement } from 'lwc';
import { getMSTeamsChats } from 'c/msTeamsConnectorLib';

export default class TeamsActionExample extends LightningElement {
    result = null;
    errorMessage = '';
    isRunning = false;
    completed = false;

    async handleRun() {
        if (this.isRunning || this.completed) return;
        this.isRunning = true;
        this.errorMessage = '';
        try {
            const request = { connectorId: 'REPLACE_WITH_CONNECTOR_RECORD_ID' };
            request.userId = 'REPLACE_WITH_USER_ID';
            request.topQuery = '20';
            request.filterQuery = 'chatType eq \'group\'';
            request.orderByQuery = 'createdDateTime desc';
            request.expandQuery = 'members,lastMessagePreview';
            request.appTenantOnly = true;
            this.result = await getMSTeamsChats(request);
            this.completed = true;
        } catch (error) {
            this.errorMessage = error.requiresInteractiveAuthorization
                ? 'Sign in to Microsoft for the connector, then try again.'
                : error.message || 'The Teams action failed.';
        } finally {
            this.isRunning = false;
        }
    }
}

teamsActionExample.html

<template>
    <lightning-button label="Run action" onclick={handleRun}
        disabled={isRunning}></lightning-button>
    <p role="alert">{errorMessage}</p>
</template>

The library resolves to an array of mapped objects. rawJson serializes the mapped Apex model rather than the untouched Microsoft response. Message body, membership roles, and nested properties can be flattened or serialized in JavaScript DTOs.

Use getMSTeamsAuthorizationState, beginMSTeamsAuthorization, and createMSTeamsOAuthMessageHandler to arrange delegated sign-in. The library normalizes errors but does not automatically sign in or retry. Reset completed for a new deliberate operation. Inspect resource state before retrying a mutation with an uncertain outcome.

Error handling and troubleshooting

Symptom	What to check
Required fields error	Supply a nonempty request list, a non-null first request, and required or conditionally required values. For LWC, check controller mappings.
Authorization or access denied	Check selected connector, delegated versus application support, consent, Teams app installation where required, and access to the resource.
Resource not found	Check team, channel, chat, message, membership, and app installation IDs; these are distinct identifiers.
Missing data	Check pagination, query support, empty-response behavior, and documented model mapping.
Operation rejected	Inspect the Microsoft error, endpoint restrictions, supported properties, message authorization limits, and notification configuration.

See Teams connector introduction.