Microsoft Teams Connector

The Microsoft Teams Connector is an outbound Connector that allows you to connect your BPMN process with Microsoft Teams to manage interactions.

Prerequisites

To use the Microsoft Teams Connector, you need to have a Microsoft Teams account and relevant permissions or the registered application in the Azure Active Directory (visit how to register the app for more information) alongside the relevant Microsoft Graph API permissions.

note

Use Camunda secrets to store credentials so you don't expose sensitive information directly from the process. See managing secrets to learn more.

Create a Microsoft Teams Connector task

You can apply a Connector to a task or event via the append menu. For example:

• From the canvas: Select an element and click the Change element icon to change an existing element, or use the append feature to add a new element to the diagram.
• From the properties panel: Navigate to the Template section and click Select.
• From the side palette: Click the Create element icon.

After you have applied a Connector to your element, follow the configuration steps or see using Connectors to learn more.

Make your Microsoft Teams Connector executable

To work with Microsoft Teams, choose the required connection type in the Authentication section and complete the mandatory fields highlighted in red in the Connector properties panel:

note

All the mandatory and non-mandatory fields depending on the authentication selection you choose are covered in the upcoming sections.

Authentication

Choose among the available Microsoft Teams Connectors according to your authentication requirements. The Microsoft Teams Connector uses the Microsoft Graph API. Visit the Microsoft Graph auth overview for more information on the Microsoft Graph API authentication.

First, you must have a user account with Microsoft Teams with the necessary permissions. See more at in Microsoft Teams overview. If you don't have administration roles and permissions, ask your Microsoft Teams administrator to add required permissions to work with the Microsoft Teams Connector.

Next, you will choose the type of connection.

Bearer Token type authentication

For a Bearer Token type authentication, take the following steps:

1. Click the Bearer Token connection type in the Authentication section.
2. Set Bearer Token to Bearer Token.

Visit Microsoft Teams Access Token for more information.

Options to obtain an access token

• Via the Graph Explorer:

  1. Visit developer.microsoft.com/graph/graph-explorer.
  2. Log in with your Microsoft account.
  3. Click the Access Token tab and copy the bearer token.

• Register your app with the Microsoft identity platform and send a POST request to the /token identity platform endpoint to acquire an access token.

  • How to register your app
  • How to get access on behalf of a user
  • How to get access without a user

Refresh Token type authentication

For a Refresh Token type authentication, take the following steps:

1. Click the Refresh token connection type in the Authentication section.
2. Set Refresh token to Refresh Token. Read more on how to get a refresh token.
3. Set Tenant ID to Tenant ID. Your Microsoft Teams tenant ID is a unique identifier. Read more on how to find a tenant ID.
4. Set the Client ID field: the application ID that the Azure app registration portal assigned to your app.
5. Set the Secret ID field: the client secret that you created in the app registration portal for your app.

Client credentials type authentication

For a Client credentials type authentication, take the following steps:

1. Click the Client credentials connection type in the Authentication section.
2. Set Tenant ID to Tenant ID. Your Microsoft Teams tenant ID is a unique identifier. See more on how to find a tenant ID.
3. Set the Client ID field: the application ID that the Azure app registration portal assigned to your app.
4. Set the Secret ID field: the client secret that you created in the app registration portal for your app.

note

With Client credentials type authentication, some methods of the Microsoft Teams Connector may not be available. Find more details in the chat methods table and channel methods table.

Conversation type and method

In the Operation section, choose a conversation type of either Chat or Channel. Then, choose one of the suggested methods.

For example, if you want to send a message in a Microsoft Teams channel, choose the conversation type Channel and method Send message in channel.

Data section

Chat conversation type

Properties

Property	Methods	Required	Type	Description
Chat ID	Get chat by ID List chat members Send message in chat List messages in chat Get message in chat List chat members	Yes	string	Microsoft Teams chat ID
Content	Send message in chat	Yes	text	Content that will be sent to chat
Content Type	Send message in chat	Yes	dropdown	Content type of body message
Chat type	Create a new chat	Yes	dropdown	Click one on one to create a one-on-one chat or group to create a group chat.
Topic	Create a new chat	No	string	Topic of chat
Members	Create a new chat	Yes	FEEL expression	See members property to learn more.
Top	List messages in chat	No	numbers	Controls the number of items per response; maximum allowed top value is 50.
Order by	List messages in chat	Yes	dropdown	Can order by 'lastModifiedDateTime' and 'createdDateTime'.
Expand response	Get chat by ID	Yes	dropdown	Choose
Filter	List messages in chat	No	string	Sets the date range filter for the lastModifiedDateTime and createdDateTime properties. Learn more about filtering.
Message ID	Get message in chat	Yes	string	Microsoft Teams chat message ID

Expand response

For method Get chat by ID, you can get more information in the response by using the dropdown property Expand response. You can choose one of the following values:

• select With chat members, to get information about chat members.
• select With last message preview, to get last message in chat. Note: This function doesn't work with client credentials type authentication, make sure that you use another authentication type.
• select Without expand, to get main information about chat.

Members property

The members property must contain a list of members:

Property	Type	Required
userId	string	Yes, if 'userPrincipalName' is not set
userPrincipalName	string	Yes, if 'userId' is not set
roles	string array	Yes

[
  {
    "userId": "abc01234-0c7f-012c-9876-&812dsfw2",
    "roles": ["owner"]
  },
  {
    "principalName": "john.dou@mail.com",
    "roles": ["owner"]
  }
]

Chat methods

Method	Use protected APIs	Available for client credentials type authentication	Link to method documentation with required permissions and return value
Create a new chat	false	true	https://learn.microsoft.com/en-us/graph/api/chat-post
Get chat by ID	false	true	https://learn.microsoft.com/en-us/graph/api/chat-get
List chats	false	true	https://learn.microsoft.com/en-us/graph/api/chat-list
List chat members	false	false	https://learn.microsoft.com/en-us/graph/api/chat-list-members
Send message in chat	false	false	https://learn.microsoft.com/en-us/graph/api/chat-post-messages
Get message in chat	false	true	https://learn.microsoft.com/en-us/graph/api/chatmessage-get
List messages in chat	true	true	https://learn.microsoft.com/en-us/graph/api/chat-list-messages

Channel conversation type

Properties

Property	Methods	Required	Type	Description
Group ID	Create channel Get channel List channels Send message to channel Get channel message List channel messages List message replies List members	Yes	string	Microsoft Teams group ID
Channel ID	Get channel List channels Send message to channel Get channel message List channel messages List message replies List members	Yes	string	Microsoft Teams channel ID
Display name	Create channel	No	string	Displayed name of new Microsoft Teams channel
Description	Create channel	No	text	Description of new Microsoft Teams channel
Channel membership type	Create channel	Yes	dropdown	See teams-channels-overview for more information
Owner	Create channel (if Channel membership type != STANDARD)	Yes	string	Channel owner; Microsoft Teams user ID or Microsoft Teams principal name
Filter	List channels	No	string	The search filter. Learn more about filtering
Content	Send message to channel	Yes	text	Content that will be sent to chat
Content Type	Send message to channel	Yes	dropdown	Content type of body message
Message ID	Get channel message	Yes	string	Message ID of Microsoft Teams in channel
Top	List channel messages	No	numbers	Controls the number of items per response
With replies	List channel messages	Yes	boolean	Choose FALSE for get messages without replies Choose FALSE for get messages without replies
Message ID	List message replies	Yes	string	Microsoft Teams channel message ID

Channel methods

Method	Use protected APIs	Available for client credentials type authentication	Link to method documentation with required permissions and return value
Create channel	false	true	https://learn.microsoft.com/en-us/graph/api/channel-post
Get channel	false	true	https://learn.microsoft.com/en-us/graph/api/channel-get
List channels	false	true	https://learn.microsoft.com/en-us/graph/api/channel-list
Send message to channel	false	false	https://learn.microsoft.com/en-us/graph/api/channel-post-messages
Get channel message	true	true	https://learn.microsoft.com/en-us/graph/api/chatmessage-get
List channel messages	true	true	https://learn.microsoft.com/en-us/graph/api/channel-list-messages
List message replies	true	true	https://learn.microsoft.com/en-us/graph/api/chatmessage-list-replies
List members	false	true	https://learn.microsoft.com/en-us/graph/api/channel-list-members

Microsoft Teams Connector response

The Microsoft Teams Connector returns the Microsoft Graph API response in result wrapper:

{
  "result": {
    "chatType": "ONE_ON_ONE",
    "createdDateTime": {
      "dateTime": {
        "date": {
          "year": 2022,
          "month": 11,
          "day": 29
        },
        "time": {
          "hour": 18,
          "minute": 10,
          "second": 33,
          "nano": 361000000
        }
      },
      "offset": {
        "totalSeconds": 0
      }
    },
    "lastUpdatedDateTime": {
      "dateTime": {
        "date": {
          "year": 2022,
          "month": 11,
          "day": 29
        },
        "time": {
          "hour": 18,
          "minute": 10,
          "second": 33,
          "nano": 361000000
        }
      },
      "offset": {
        "totalSeconds": 0
      }
    },
    "tenantId": "0000000-0000-0000-0000-000000000",
    "webUrl": "https://teams.microsoft.com/l/chat/19%3Aefb08ac3-0000f-0000-0000-example-chat-id_fe35bf61-0000-0000-0000-ddc97d8903d4%40unq.gbl.spaces/0?tenantId=00000-0000-0000-0000-00000000",
    "id": "19%3Aefb08ac3-0000f-0000-0000-example-chat-id_fe35bf61-0000-0000-0000-ddc97d8903d4%40unq.gbl.spaces"
  }
}

See channel resource type to find the response for the required method for a channel conversation type, or see chat resource type to find the response for the required method for a chat conversation type.

You can use an output mapping to map the response:

1. Use Result Variable to store the response in a process variable. For example, myResultVariable.
2. Use Result Expression to map fields from the response into process variables. For example:

= {
  "chatId": result.id,
  "tenantId": result.tenantId
}