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 on the right side of the screen.

note

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

Authentication

Choose an authentication type according to your 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.

You must have a user account with Microsoft Teams with the necessary permissions. See more at 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.

Bearer token

Select Bearer token in the Type dropdown in the Authentication section and enter your bearer token value. Use Camunda secrets to avoid exposing sensitive credentials.

note

Bearer tokens expire after 60–90 minutes. The connector cannot refresh them automatically, so you must provide a new valid access token before expiry.

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

Client credentials

Select Client credentials in the Type dropdown in the Authentication section and provide the following fields:

• Tenant ID: Your Microsoft Entra tenant ID (also called "Directory ID"). Learn more about how to find a tenant ID.
• Client ID: The application ID that the Azure app registration portal assigned to your app.
• Client Secret: The client secret you created in the app registration portal for your app.

Create a client secret

1. In the Azure app registration portal, navigate to your registered application.
2. Go to Certificates & secrets.
3. Click New client secret.
4. Enter a description (for example, Camunda Connector Secret).
5. Select an expiration period. You will need to rotate the secret before it expires.
6. Click Add.
7. Copy the secret value immediately. This value is only displayed once and cannot be retrieved later.

Store your credentials securely using Camunda secrets.

Refresh token

Select Refresh token in the Type dropdown in the Authentication section and provide the following fields:

• Refresh Token: Your refresh token value. Learn more about how to get a refresh token.
• Tenant ID: Your Microsoft Entra tenant ID (also called "Directory ID"). Learn more about how to find a tenant ID.
• Client ID: The application ID that the Azure app registration portal assigned to your app.
• Client Secret (optional): The client secret for your app. Required for confidential clients, not required for public clients.

note

Refresh tokens expire after 90 days by default. The connector cannot persist updated refresh tokens when stored as a secret or hardcoded value, so the originally configured token will expire regardless of usage. You must obtain and configure a new refresh token before the 90-day expiry.

See Microsoft's documentation on refresh token lifetimes for details.

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
Documents	List of documents to attach to a message	No	List of documents	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
}