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.
To access a team in Microsoft Teams, use the
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
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
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
get_member() methods. For
the latter, you can retrieve a member using either their display name,
email address, or internal ID.
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.
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[]$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[]$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")
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
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 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.
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
get_chat(), passing it the 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.