Cli-microsoft365: New command: Get all the Microsoft Teams messages for the given user

[rabwill]

Usage

m365 teams user message list [options]

Description

Get all Microsoft Teams messages for the given user

Options

| Option | Description |
| ----------------------- | ----------------------------------------- |
| --userName<userName> | The UPN of the user whose messages are to be retrieved |
| --fromDateTime[fromDateTime] |The start of time range to query |
| --toDateTime[toDateTime] |The end of time range to query |
| -p, --pageSize[pageSize] | Number of objects to return |
| -n, --pageNumber[pageNumber] |Page number to return if pageSize is specified (first page is indexed as value of 0) |

Additional Information

https://docs.microsoft.com/en-us/microsoftteams/export-teams-content#how-to-access-teams-export-apis

Prerequisites to access this API

https://docs.microsoft.com/en-us/microsoftteams/export-teams-content#prerequisites-to-access-teams-export-apis

[rabwill]

@pnp/cli-for-microsoft-365-maintainers here is a new command for review of spec, please let me know if this is okay and then we can put it in the backlog and label it appropriately. Thanks 😊

[waldekmastykarz]

Thanks for the suggestion.

1. I wouldn't call the command export. As it retrieves all items, we should name it Get all Microsoft Teams messages for the given user
2. To make the command easier to use, I'd suggest that we allow specifying user's UPN rather than ID, which users would need to retrieve separately first
3. Are filter, pageSize and pageNumber meant to be required? If not, let's denote them as optional using [] rather than <>
4. What can be specified in the filter?
5. What is the default behavior if pageSize and pageNumber are not specified?

[rabwill]

Good catch on point # 3! thanks @waldekmastykarz.
In the filter they can specify the date range or messageType etc. See sample response here

{
"id": "string (identifier)",
"replyToId": "string (identifier)",
"from": {"@odata.type": "microsoft.graph.identitySet"},
"etag": "string",
"messageType": "string",
"createdDateTime": "string (timestamp)",
"lastModifiedDateTime": "string (timestamp)",
"deletedDateTime": "string (timestamp)",
"subject": "string",
"from": {
                "application": null,
                "device": null,
                "conversation": null,
                "user": {
                    "id": "string (identifier)",
                    "displayName": "string",
                    "userIdentityType": "aadUser"                }
            },
"body": {"@odata.type": "microsoft.graph.itemBody"},
"summary": "string",
"chatId": "string (identifier)"
"attachments": \[{"@odata.type": "microsoft.graph.chatMessageAttachment"}\],
"mentions": \[{"@odata.type": "microsoft.graph.chatMessageMention"}\],
"importance": "string",
"locale": "string",
}

The API gives back @odata.nextlink in case there are multiple values similar to other commands or this sort.

[plamber]

Not sure if we will be able to use this command at a large scale. I fell into this already a couple of times with some other interesting endpoints.

Microsoft Teams APIs in Microsoft Graph that access sensitive data are considered protected APIs. Export APIs require that you have additional validation, beyond permissions and consent, before you can use them. To request access to these protected APIs, complete the request form.

The command will throw a 401 exception until you got an approval from Microsoft and your AppId has been enabled.
@waldekmastykarz I do not believe that MS will enable our PnP CLI app with these permissions due to security reasons. I tried to get the approval already a couple of times but failed in the past.

Is this something we want to clarify before? Maybe have some discussions with the Microsoft responsible parties to see how we can proceed here?

[waldekmastykarz]

@rabwill rather than having a catch-all filter property, I'd suggest we introduce specific options for the specific values so that we can apply validation to it.

@plamber I wouldn't expect getting clearance for our app, especially as it doesn't support app-only auth. Instead, users would get clearance for their own app and use it in combination with CLI. In the past, I requested and got approval so the process is working given proper justification. I agree that the required clearance will likely limit the usage of this command. Perhaps if we can describe a number of usage scenarios and the justification, it could help users get approvals and use this command.

[rabwill]

@waldekmastykarz so just the date range to start off now, and we can add any as we please?

[waldekmastykarz]

@rabwill is date the most common filter?

[rabwill]

Since it is already mentioned as a filter example in the doco, perhaps it's a good start? ☺️

[waldekmastykarz]

Good point 👍

[rabwill]

Shall we move this to backlog then? Do we need more discussion @plamber @waldekmastykarz ?

[waldekmastykarz]

I think we're good to go 👍