Microsoft Graph Teams

Overview

Important:  PROTECTED API USAGE
Due to the potentially sensitive nature of Teams' content, Microsoft has restricted the usage of APIs that can retrieve chat messages. In order to use these APIs, an additional approval process is required. The form is found here. The response will usually take 1 to 2 business days.

Important:  LICENSING AND PAYMENT REQUIREMENTS FOR MICROSOFT TEAMS APIS
In order to retrieve private chat messages, a payment model is required after a certain number of messages. See this link. 3Sixty uses the Get messages across all chats for user method.

Note:  THE RELATIONSHIP BETWEEN TEAMS AND SHAREPOINT
Microsoft Teams file storage for a team is actually just a SharePoint site, with each channel being a folder in the Documents library. You can view your teams files in SharePoint by going to https://[tenant].sharepoint.com/sites/[teamName].

Authentication Connection

This connector requires a standard Microsoft Graph Authentication Connection.

The application will require the following permissions:

• TeamSettings.Read.Group

• Channel.ReadBasic.All

• User.Read.All

• ChannelMessage.Read.All

• Chat.ReadBasic.All

Discovery Connector

The Teams connector has some static content types. The Teams Discovery connector does not require authenticating to the service, so you can simply create the schema instance and hit Run. The three types are:

• Chat Message: Represents any message sent privately or in a channel

• Attachment: Represents a file associated with chat messages

• Chat Log: A chat log generated by 3Sixty which contains all messages sent in a channel during a time period.

Integration Connector

Note:  RUNNING ERRORS
As of the 3.1.1 release, MSGraph connectors cannot rerun errored documents. We are aware of the issue, and it will be addressed in the next release.

The Teams connectors has two modes of operation. Public Chats and Private The first mode allows you to export a teams files, but crawling the backing SharePoint site. It also lets you extract messages from the public channels

The second mode allows you to pull the private chats for a user.

Job Configuration

• Team Name: Required for either mode. The name of the team.

• What would you like to retrieve? This will select the mode, and will change available options.

Team Chats or Files

• Channels to migrate: Tag input to list channels to migrate.

• Retrieve files associated with the team (will retrieve files for all channels): This is essentially identical to migrating the Documents library of the team's SharePoint site. These files will appear in their SharePoint folder structure, sites/<TeamName>/Shared Documents/<Channelname>

• Get messages from listed channels from between configured times: Retrieve chat messages in the form of a single text file. The chat log will be in /<TeamName>/<Channelname>/ChatLog

• Break down each chat message into an individual document: Instead of a single chat log, each message and its direct replies will become an html document. Attachments will be added to the document as additional binaries, if they are being retrieved.

• Select a format for chat messages: If you are breaking down chat messages, this will determine the format. There are two options:

• Plain Text: Each message will be a simple text file with no additional formatting. See below for export structure

• HTML: Each message and its direct replies will become an html document. Attachments will be added to the document as additional binaries, if they are being retrieved.

• Only retrieve chats from the listed users. Leave blank to retrieve all messages: Will filter chat messages based on the sender. Use the same as it would appear in the 'from' line of a message.

• Retrieve attachments attached to chat logs: If only retrieving a single chat log the attachments will appear in /<TeamName>/<ChannelName>/ChatLog/Attachments. See the export structure below for how they are handled when retrieving individual chats

Plain Text Export Structure

<ChannelName>/
├─ <MessageId>/
│  ├─ <MessageId>.txt
│  ├─ attachments/
│  │  ├─ attachment.pdf
│  ├─ replies/
│  │  ├─ <ReplyId>/
│  │  │  ├─ attachments/
│  │  │  │  ├─ replyattachment.pdf
│  │  ├─ <ReplyId1>.txt
│  │  ├─ <ReplyId2>.txt

Get Private Chat

• The display name of user's whose chats to pull: List of user's to pull. Each private chat thread will be output under its own folder.

• Preferred licensing and payment requirement model. The API used to retrieve private messages has limited usage. Usage beyond certain amounts require payment. For testing, stick to the default, but note that you will run out after 500 messages.

• Retrieve attachments attached to chat logs: Will attach documents as additional binaries for each message.

Note:  EVENT JOB LIMITATIONS
If you wish to process a message via push event, there are some restrictions.

* Private Chats are not available. Attempting to execute the push event against private chats will cause an error.
* The output for an event chat will always be in html format.
* If attachments are included, they will be additional binaries on the document.

Content Service Connector

The Content Service Connector for Teams is an extension of the one for SharePoint. The configuration simply points the connector at the team you wish to manage. Alternatively you can use the SharePoint connector with a site path of sites/[teamName] and a list name of Documents. Not that Content services cannot update, create or change chat messages at this time.

Content Service Configuration

• Connector ID: Give your connector a unique name

• Description: Provide a description for this connection

• Type: Select the Filesystem Content Service Connector

• Keep Connection Alive: Keep this connection active

• Keep alive in Milliseconds (300000 is 5 minutes): How long until connection expires if unused

• Connection URL: The web address for your connection

• Security Mode: None needed for this connection

• Mapping Type: Choose single map or group mapping if you are using mapping for jobs

• Tenant Name: The name of the tenant. All O365 SharePoint instances use the structure [tenant].sharepoint.com. We use this to construct urls and gather site IDs. If you do not know your tenant follow the steps below about retrieving your tenant name.

• Team Name: The name of the team you wish to manage with this connector.

Supported Methods

• checkIn

• checkOut

• createFile

• createFolder

• deleteACL

• deleteFolder

• deleteObjectByID

• findTypeDefinition

• getACLs

• getFileContent

• getObjectProperties

• getTypes

• listFolderItems

• listVersions

• lockDocument

• setACLs

• unlockDocument

• updateFile

• updateProperties

Retrieving your tenant name

If you do not know your tenant name (it's usually your organisations name), you can retrieve it in teams.

• Go to Files

• Click the ellipses ... next to any file

• Click Copy Link

• This will produce a SharePoint url in the format https://[tenant].sharepoint.com

API Keys

Microsoft Graph Teams Connector: Read=true: Write=false: MIP=false

Repo (Read) Specs

Need help integrating Microsoft Graph Teams? We can help.