The msteams
plugin supports interaction with the Microsoft Teams
messaging platform.
To be able to use the MSTeams
task in a Concord flow, it must be added as a
dependency:
configuration:
dependencies:
- mvn://com.walmartlabs.concord.plugins:msteams-task:1.32.3
This adds the task to the classpath and allows you to invoke the MSTeams
task.
Possible operations are:
We recommend users to use or move to msteamsV2
for following reasons:
V1
, adding concord-bot
to a team, makes it available
for all public channels in a team.replyToConversation
action.V2
.Add concord-bot
to your MS Team/channel. Follow below steps
to add it from MS Teams UI.
Apps
tab and then click on More Apps
button.concord-bot
.open
dropdown and select Add to a team
.Set up a bot
.Private channels do not support bots. Make sure your channel is not marked as
private
. For more details check here.
The MSTeams
task uses a number of input parameters that are common for all
operations:
task
- determines name of task. Should be msteamsV2
if you are using
version 2;action
- determines the operation to be performed with the current
invocation of the MSTeams
task.ignoreErrors
- boolean value, if true
any errors that occur during
the execution are ignored and stored in the result
variable. Defaults to
false
.The tenantId
, useProxy
, proxyAddress
, proxyPort
,clientId
,
clientSecret
, rootApi
, and accessTokenApi
variables
configure the connection to the MS Teams server. They are
best configured globally as [default process configuration]
(../getting-started/configuration.html#default-process-variable)
with an msteamsParams
argument.
configuration:
arguments:
msteamsParams:
tenantId: "myTenantID"
useProxy: true
proxyAddress: "proxy.example.com"
proxyPort: 8080
clientId: "botId"
clientSecret: "botSecret"
rootApi: "https://smba.trafficmanager.net/amer/v3/conversations"
accessTokenApi: "https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token"
useProxy
- boolean value, if true
uses the proxyAddress
and proxyPort
set in default vars. Defaults to false
.clientId
- determines the id associated with bot.clientSecret
- determines the secret associated with bot.Note: your Concord environment may provide other defaults using the default variables.
The createConversation
action allows users to create a new conversation in a specific MSTeams
channel. It uses input parameters listed below for the operation.
channelId
: string, required - the Id of the MS teams channel. It can be seen
in the URL opened by clicking 3 dots -> Get link to channel
link next to your channel.activity
: map, required - initial message to send to the conversation when it is created.
More details about activity
object can be found here,
but a simple example can look like as shown below.flows:
default:
- task: msteamsV2
in:
action: createConversation
activity:
type: message
text: "My First Message"
channelId: "myChannelId"
ignoreErrors: true
- log: "Result status: ${result.ok}"
- if: "${!result.ok}"
then:
- throw: "Error occured while sending a message: ${result.error}"
...
The task returns a result
object with following fields:
ok
- true
if the operation is succeeded.data
- string - response body, if the operation is succeeded.error
- error message if the operation failed.coversationId
- ID of the conversation that was posted, can be used,
in the following msteams task to reply to a conversation.activityId
- ID of the activity, if sent.The replyToConversation
action allows users to reply to an existing
conversation in a specific MSTeams channel. It uses input parameters
listed below for the operation.
coversationId
: string, required - the Id of the conversation that was previously posted.activity
: map, required - message used to reply to a conversation.- task: msteamsV2
in:
action: replyToConversation
conversationId: ${result.conversationId}
activity:
type: message
text: "This replies to a previosuly posted conversation"
Possible operations:
Configure an Incoming Webhook
on your Teams channel. Follow below steps to
configure it from MS Teams UI.
https://outlook.office.com/webhook/{teamID}@{tenantID}/IncomingWebhook/{webhookID}/{webhookTypeID}
The MSTeams
task allows users to trigger operations on a Microsoft Teams server
as a step in a Concord flow. It uses a number of required input parameters that are
common for all operations:
action
- determines the operation to be performed with the current invocation
of the MSTeams
task.ignoreErrors
- boolean value, if true
any errors that occur during the
execution are ignored and stored in the result
variable. Defaults to false
.The webhookTypeId
, tenantId
, rootWebhookUrl
, proxyAddress
, and
proxyPort
variables configure the connection to the MS Teams server. They are
best configured globally as
default process configuration
with an msteamsParams
argument.
webhookTypeId
: unique GUID of webhook type Incoming Webhook
tenantId
: unique GUID representing the Azure ActiveDirectory TenantrootWebhookUrl
: root URL of webhookproxyAddress
: proxy server to useproxyPort
: proxy server port to useExtract webhookTypeId
and tenantId
from webhook URL from step 4 of Prerequisite
configuration:
arguments:
msteamsParams:
webhookTypeId: "myWebhookTypeID"
tenantId: "myTenantID"
rootWebhookUrl: "https://outlook.office.com/webhook/"
proxyAddress: "proxy.example.com"
proxyPort: 8080
The sendMessage
action allows users to send messages to a specific MSTeams
channel. It uses input parameters listed below for the operation.
webhookUrl
: URL, required - webhook URL from step 4 of Prerequisite.title
: string, optional - title of the message.text
: string, required - body of the message.themeColor
: string, optional - theme color of the message. Defaults to
11B00A
. More theme colors can be found here
to pick from.sections
: array, optional - a collection of sections to include in a message.
See sections
for more details.potentialAction
: array, optional - a collection of actions that can be
invoked on a message. See potentialAction
for more details.Initiate sendMessage
action using webhookUrl
flows:
default:
- task: msteams
in:
action: sendMessage
webhookUrl: https://outlook.office.com/webhook/{teamID}@{tenantID}/IncomingWebhook/{webhookID}/{webhookTypeID}
title: "My message title"
text: "My message text"
ignoreErrors: true
- if: "${!result.ok}"
then:
- throw: "Error while sending a message: ${result.error}"
else:
- log: "Data: ${result.data}"
Initiate sendMessage
action using teamId
and webhookId
extracted from
webhook URL from step 4 of Prerequisite
teamId
: string, required - team IDwebhookId
: string, required - webhook IDflows:
default:
- task: msteams
in:
action: sendMessage
teamId: "myTeamID"
webhookId: "myWebhookID"
title: "My message title"
text: "My message text"
ignoreErrors: true
- if: "${!result.ok}"
then:
- throw: "Error while sending a message: ${result.error}"
else:
- log: "Data: ${result.data}"
The task returns a result
object with three fields:
ok
- true
if the operation is succeeded.data
- string - response body, if the operation is succeeded.error
- error message if the operation failed.