Today I am so pleased to introduce my first CRAN package for sending
formatted messages to Microsoft Teams,
teamr
.
Motivation is simple here. For years I have been using Slack and built
many slash commands and apps using incoming webhooks with R, but ever
since I started to use Teams, I found that we will have the same needs
for communicating with R as well. So with some inspiration from the
Python package pymsteams
. I
created teamr
package with the hope that this package will provide a
simple and clean way to talk to Teams from R.
Installation
You can install the released version of teamr from CRAN with:
install.packages("teamr")
And the development version from GitHub with:
# install.packages("devtools")
devtools::install_github("wwwjk366/teamr")
Example
This is a basic example of send a simple titled message to MS Teams:
library(teamr)
# initiate new connector card object
cc <- connector_card$new(hookurl = "https://outlook.office.com/webhook/...")
# add text
cc$text("This is text of main body.")
# add title
cc$title("This is message title")
# add hyperlink button
cc$add_link_button("Read more", "https://www.google.com")
# change theme color
cc$color("#008000")
We can print out the payload that will be sending to given webhook using
print
method
# print out the payload for checking
cc$print()
Card:
hookurl: https://outlook.office.com/webhook/...
payload: {"text":"This is text of main body.","title":"This is message title","potentialAction":[{"@context":"http://schema.org","@type":"ViewAction","name":"Read more","target":["https://www.google.com"]}],"themeColor":"#008000"}
Our JSON
payload looks good, time to send it out :)
# send to Teams
cc$send()
[1] TRUE
send
menthod will return TRUE
if send was successful (status code
200). If it failed, it will return the reponse object for further
investigation. Our message with a link button will looks like this:
You probably noticed now that this package is built using R6
class(very nice tutorial by Hadley
here). I decide to do this way
because by using OOP concept, it will give use a feeling that you are
“building” your message by adding something piece by piece. At the same
time the code will be highly readable and easy to understand. teamr
has 3 main classes as of today — connector_card
, card_section
and
action_card
. For example, let’s add a section to our message:
Message with sections
#initiate new card section object
sec <- card_section$new()
sec$text(sec_text = "2018-19 Finals MVP")
sec$add_fact(fname = "Position", fvalue = "Forward")
sec$title(sec_title = "Player Info")
sec$activity_image(sec_activitiy_image = "https://d2cwpp38twqe55.cloudfront.net/req/201905091/images/players/leonaka01.jpg")
sec$activity_title(sec_activity_title = "Kawhi Leonard")
sec$activity_sub_title(sec_activitiy_subtitle = "LA Clippers")
sec$activity_text(sec_activitiy_text = "Activity text")
cc$add_section(new_section = sec)
cc$send()
[1] TRUE
This is what you will get on your Teams channel:
Message with action cards
Teams also support sending actionable messages. You can add a button to your message which can send HTTP reqeust to a certain URL with different type of inputs.
In the following example, I will add a multilined text input, a date
selector and a multiple choice input to our message. Simply changing
target = "http://..."
in add_actions
method to the URL you want the
reponse payload to be sent to:
# create new action card
pa <- action_card$new(type = "ActionCard", name = "Add comment")
# add default actions to card
pa$add_actions(type = "HttpPOST", name = "Save", target = "http://...")
# add text inputs
pa$add_text_inputs(id = "comment", title = "Add comment for this task", is_multi_line = TRUE)
# save to the card object
cc$add_potential_action(pa)
pa2 <- action_card$new(type = "ActionCard", name = "Add Date")
pa2$add_actions(type = "HttpPOST", name = "Save", target = "http://...")
pa2$add_date_inputs(id = "date", title = "Add Date for this task")
cc$add_potential_action(pa2)
pa3 <- action_card$new(type = "ActionCard", name = "Add Options")
pa3$add_actions(type = "HttpPOST", name = "Save", target = "http://...")
# add multiple choices. note that choices must be a nested named list
pa3$add_mchoice_inputs(id = "mchoice",
title = "Choice one",
is_multi_select = TRUE,
choices = list(
list(display="In Progress", value=1),
list(display="Active", value=2),
list(display="Close", value=3))
)
cc$add_potential_action(pa3)
cc$send()
[1] TRUE
If you want to learn more regarding Microsoft Connectors, you check out the offical doc here.
Summary
This is my very first package on CRAN so if you found any bugs please report here https://github.com/wwwjk366/teamr/issues. I do have plan to add more functionality to the package so stay tuned!