Teams

Hong Ooi

Microsoft365R is a simple yet powerful R interface to Microsoft 365 (formerly known as Office 365), leveraging the facilities provided by the AzureGraph package. This vignette describes how to interact with Microsoft Teams.

See the “Authenticating to Microsoft 365” vignette for more details on authentication if required.

Teams

To access a team in Microsoft Teams, use the get_team() function and provide the team name or ID. You can also list the teams you’re in with list_teams(). These return objects of R6 class ms_team.

list_teams()
team <- get_team("My team")

The ms_team class has methods for working with channels and drives. Each team will generally have at least one drive, and possibly two: the default “Documents” drive, which is where uploaded files are stored, and the “Teams Wiki Data” drive, if the team has a wiki. Each team channel will have an associated folder in each drive, if at least one file has been uploaded to it.

# list the channels in a team (including private channels you're a member of)
team$list_channels()

# get the primary channel for a team
team$get_channel()

# get a specific channel
team$get_channel("My channel")

# drives for a team
team$list_drives()
team$get_drive()

A drive is an ms_drive object, so the same methods apply as for OneDrives and SharePoint document libraries—see the “OneDrive and SharePoint” vignette for more information.

drv <- team$get_drive()

# one folder per channel
drv$list_files()

# upload will appear in the Files tab of "My channel" in the Teams client
drv$upload_file("myfile.csv", "My channel/myfile.csv")

Note that the drives mentioned here are actually the document libraries of an underlying SharePoint site: as far as file storage is concerned, you can think of Teams as simply an alternative interface to functionality provided by SharePoint. The ms_team class in fact has a get_sharepoint_site() method to retrieve the backing site, and you can access the same files via the site’s drive.

site <- team$get_sharepoint_site()
site_drv <- site$get_drive()

# the previous upload will also appear in this file listing
site_drv$list_files("My channel")

You can also retrieve the team members with the list_members() and get_member() methods. For the latter, you can retrieve a member using either their display name, email address, or internal ID.

team$list_members()
team$get_member("Joe Smith")
team$get_member(email="joesmith@mytenant.com")

Channels

A team object has methods for listing, retrieving, creating and deleting channels. However you should not create and delete channels unnecessarily, since Teams tracks all channels ever created, even after you delete them. In turn, a channel object has methods for retrieving members, listing and sending messages, and uploading and deleting files.

Channel messages

Teams channels are semi-threaded. Getting the list of messages for a channel retrieves only the first message in each thread; to get an entire thread, you get the starting message and then retrieve the replies to it. Note that channels don’t have nested replies, so you can’t reply to a reply—only to the starting message.

The body of a message is part of the list of properties returned from the host, and can be found in the properties field of the object. Other properties include metadata such as the author, date, list of attachments, etc.

chan <- team$get_channel()

# by default, retrieve only the 50 most recent messages
msgs <- chan$list_messages()

# retrieve the 100 most recent messages
chan$list_messages(n=100)

# retrieve all messages: set n = infinity
chan$list_messages(n=Inf)

# get the latest message by ID
msg <- chan$get_message(msgs[[1]]$properties$id)

# body of the message
msg$properties$body

# 10 most recent replies
repl_list <- msg$list_replies(n=10)

# body of an individual reply
repl_list[[1]]$properties$body

You can send a message to a channel as plain text (the default) or HTML. For the latter, Teams imposes security restrictions on which HTML tags are allowed; you should limit your message to contain only basic formatting and no embedded scripts. You can also include files as attachments, or as inline images (JPEG or PNG only). Similarly, you can @mention a team, channel, or an individual team or channel member. For the latter, the message must be HTML and not plain text.

# sending messages to a channel
chan$send_message("Hello from R")
chan$send_message("<div>Hello from <em>R</em></div>", content_type="html")

# send attachments by including a vector of filenames
chan$send_message("Hello with attachments", attachments=c("intro.md", "myfile.csv"))

# images can be sent inline rather than as attachments: set content_type to 'html'
chan$send_message("", content_type="html", inline="graph.png")

# send a reply to a message
msg <- chan$send_message("Starting a new thread in R")
msg$send_reply("Reply from R")

# send a reply with an attachment
msg$send_reply("See attached file", attachments="reply.md")

# mention a channel member
usr <- chan$get_member("Joe Smith")
msg$send_message("FYI Joe", mentions=usr, content_type="html")

Channel files

Uploading a file to a channel will place it in the channel’s drive folder. Note that message attachments are actually uploaded to the channel’s folder with the message then including a link to the uploaded file.

The channel object itself provides convenience functions to list, upload and download files. It also provides a get_folder() method to retrieve the folder for the channel, as an ms_drive_item object; this object has more general methods for working with files. Again, see the “OneDrive and SharePoint” vignette for more information on drive item objects.

# files for the channel
chan$list_files()

# upload a file to the channel
chan$upload_file("myfile.docx")

# open the uploaded document for editing in Word Online, then download it again
chan_folder <- chan$get_folder()
item <- chan_folder$get_item("myfile.docx")
item$open()
item$download(overwrite=TRUE)

# create a shareable link (read-only, expires in 7 days)
item$create_share_link()

Private channels

Private channels function much the same way as regular public channels, and the methods described above should also work with them. The main difference is that a private channel’s files are stored in a separate SharePoint site to the public channels, so any files you upload to the private channel won’t appear in the file listings for the main site.

Chats

Microsoft365R also supports messaging in chats. There are three types of chats: group, meeting and one-on-one, but the same interface applies to all types. To access the chats that you are part of, use the list_chats() function. You can also retrieve a specific chat with get_chat(), passing it the chat ID.

chats <- list_chats()
chat_id <- chats[[1]]$properties$id
chat <- get_chat(chat_id)

In general, the functionality is very similar to messaging in channels:

# by default, retrieve only the 50 most recent messages
msgs <- chat$list_messages()

# retrieve the 100 most recent messages
chat$list_messages(n=100)

# retrieve all messages: set n = infinity
chat$list_messages(n=Inf)

# sending messages to a chat
chat$send_message("Hello from R")
chat$send_message("<div>Hello from <em>R</em></div>", content_type="html")

# send attachments by including a vector of filenames
chat$send_message("Hello with attachments", attachments=c("intro.md", "myfile.csv"))

# images can be sent inline rather than as attachments: set content_type to 'html'
chat$send_message("", content_type="html", inline="graph.png")

# send a reply to a message
msg <- chat$send_message("Starting a new thread in R")
msg$send_reply("Reply from R")

# list participants in a chat
chat$list_members()

# mention someone
usr <- chat$get_member("Joe Smith")
msg$send_message("FYI Joe", mentions=usr, content_type="html")

Note that unlike a team channel, there is no drive folder associated with a chat.