--- title: "Teams" author: Hong Ooi output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Teams} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{utf8} --- Microsoft365R is a simple yet powerful R interface to [Microsoft 365](https://www.microsoft.com/en-us/microsoft-365) (formerly known as Office 365), leveraging the facilities provided by the [AzureGraph](https://cran.r-project.org/package=AzureGraph) package. This vignette describes how to interact with [Microsoft Teams](https://www.microsoft.com/en-au/microsoft-teams/group-chat-software). 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`. ```r 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. ```r # 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. ```r 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. ```r 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. ```r 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. ```r 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. ```r # sending messages to a channel chan$send_message("Hello from R") chan$send_message("
Hello from R
", 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. ```r # 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. ```r 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: ```r # 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("
Hello from R
", 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.