App Integrations connector

Send messages to Microsoft Teams, receive what people write back, and create channels, directly from your BPMN process.

About this connector

The App Integrations connector sends messages through your organization's Camunda app integrations. The connection is configured once for the environment, so the task itself carries no credentials and no endpoint.

A message can go to a Microsoft Teams channel, user, or conversation, or to a Camunda recipient — an assignee, candidate users, or candidate groups, which are resolved to the people who have connected the Camunda app. Alongside the text you can send an Adaptive Card or a Camunda form.

Your process can also listen. When someone writes to the Camunda app, a process can start from what they typed, and a running process can wait for their reply. See receive a chat message.

When to use this connector

Use this connector if your organization uses Camunda app integrations — the Camunda app for Microsoft Teams. Messages sent from a process travel through the same integration your users already have, so they arrive in the same channels and chats, alongside the task notifications those users already receive, rather than through a separate bot with its own identity.

If you do not use app integrations, and you would rather register your own app and supply its credentials in the process model, use the Microsoft Teams connector instead.

Prerequisites

Use this connector

New to using an outbound connector? Learn how to add and use this type of connector, apply element templates, use connector secrets, handle results and errors, and more.

Use an outbound connector

App integrations must be set up before this connector can be used. This is an administrator task, and it is done once per environment — there is nothing to configure on the task itself.

SaaS

An organization administrator must turn on Enable app integrations extensions in the cluster settings of every cluster that uses the connector.

Self-Managed

An administrator must install app integrations and configure the connector runtime to reach it:

1. Install and configure app integrations, as described in Install Camunda for Microsoft Teams. The same installation serves this connector and the Microsoft Teams app.
2. Point the connector runtime at that installation, as described in configure the App Integrations connection.

When the runtime authenticates with OAuth 2.0, it also needs the cluster's ID. This is the most common reason a fully installed environment still fails: without it, every job fails with APP_INTEGRATIONS_NOT_CONFIGURED. Runtimes that authenticate with an API key do not need it, and SaaS needs no equivalent setting.

Create an App Integrations 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.

In each of these menus, you can search by connector name or by the operation you want to perform, such as upload object or send email. Connectors that provide several operations list them as separate entries, and selecting an operation applies the connector with that operation preselected.

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

Send message

Send a message to one or more destinations. Choose the Recipient source first — it determines which targets and which content formats are available.

Recipient

Camunda

Address people by their Camunda identity, and let app integrations resolve where to deliver. At least one of the three fields is required.

Property	Type	Required	Description	Example
Assignee email	String	No*	Email address of the recipient.	= assigneeEmail
Candidate users	List	No*	Usernames to notify.	= ["alice", "bob"]
Candidate groups	List	No*	Group names to notify.	= ["approvers"]

* At least one of the three must be provided.

Microsoft Teams

Select a Teams target, then fill the field it reveals.

Teams target	Property	Required	Description	Example
Channel	Channel ID	Yes	The Microsoft Teams channel to post into.	19:xxx@thread.tacv2
User	User ID	Yes	Microsoft Entra object ID of the recipient. They must have connected the Camunda app.	6b1e0f9a-1f3d-4a2b-9d0e-4c1b2a3d4e5f
Conversation	Conversation	Yes	The conversation value returned by a previous send. The message is posted as a reply in it.	19:abc@thread.tacv2;messageid=17123456789

Message content

Message is plain text and always available. It is optional — leave it empty to send only the additional content, or fill both to send text and a card in one message.

Additional content offers different formats depending on the recipient:

Recipient	Additional content options
Camunda	None · Form
Microsoft Teams	None · Adaptive card · Form

You can select at most one, so a card and a form are mutually exclusive. You must provide a message, additional content, or both — an empty message with None is rejected before any call is made.

Additional content	Property	Type	Required	Description
Adaptive card	Adaptive card	Text	Yes	Adaptive Card as JSON.

The field accepts pasted JSON as well as a FEEL expression referencing a card built earlier in the process, such as = approvalCard. A JSON literal is valid FEEL, so pasting works without further quoting.

When additional content is Form, the connector renders a linked Camunda form as an Adaptive Card. Select the form and its binding in the properties panel:

Property	Type	Required	Description
Form binding	Dropdown	Yes	Latest, Deployment, or Version tag. Defaults to Latest.
Form ID	String	Yes	ID of the Camunda form to render alongside the message.
Version tag	String	Yes*	The version tag to bind to.

* Required when Form binding is Version tag.

Response

The connector reports every destination the message reached, and every one it did not:

{
  "deliveries": [
    {
      "platform": "teams",
      "conversation": "19:abc@thread.tacv2;messageid=17123456789",
      "messageId": "17123456789",
      "conversationKey": "teams:19:abc@thread.tacv2;messageid=17123456789"
    }
  ],
  "failures": [
    {
      "platform": "teams",
      "conversation": "19:def@thread.tacv2",
      "reason": "bot_not_in_channel"
    }
  ]
}

Field	Description
deliveries	Every destination the message was delivered to.
deliveries[].platform	Always teams.
deliveries[].conversation	The conversation the message landed in. Use it to reply later.
deliveries[].messageId	The message identifier.
deliveries[].conversationKey	Identifies the conversation for a chat catch element. See receive a chat message.
failures	Every destination that could not be reached.
failures[].platform	Always teams.
failures[].conversation	The conversation that could not be reached.
failures[].reason	Why that destination failed.

A single delivery is a one-element list, so with a result variable of response you read it as = response.deliveries[1].conversation. FEEL lists are 1-indexed.

failures is non-empty on a partial success. A process that must not continue on an incomplete fan-out can check = count(response.failures) > 0.

tip

To continue a conversation, feed the response back in. Pass conversation as the Microsoft Teams Conversation target. To wait for an answer instead of sending again, pass conversationKey to a chat message catch element.

Create channel

Create a channel in a Microsoft Teams team.

Property	Type	Required	Description	Example
Channel name	String	Yes	Display name for the new channel. Maximum 50 characters.	Releases
Team ID	String	Yes	The team's group ID, or a full Teams URL — the groupId query parameter is extracted automatically.	<groupId>
Channel type	Dropdown	Yes	Membership type. Only Standard is available.	Standard
Description	String	No	Channel description.	Release coordination

note

Only standard channels are supported. Private and shared channels are not yet available, and a request for either is rejected.

Response

{ "channelId": "19:new-channel@thread.tacv2" }

Read the new channel with = response.channelId. You can pass it straight into a Send message task as the channel target.

Receive a chat message

Start a process when someone writes to the Camunda app in Microsoft Teams, or wait for their reply while a process runs.

Receiving needs no connector task and no job worker. A chat catch element is an ordinary BPMN message event, and the App Integrations element templates set it up for you. Apply a template to the element, and the incoming message arrives as a process variable.

Chat conversation element templates

Apply one of these templates in the Camunda Hub modeler or Desktop Modeler. Each applies to a different BPMN element.

Element template	Apply to	Purpose
App Integrations Chat Conversation Start Event	Message start event	Start a process when someone writes to the Camunda app.
App Integrations Chat Message Intermediate Event	Intermediate message catch event	Wait for the next message in the conversation the process is holding.
App Integrations Chat Message Receive Task	Receive task	Wait for the next message as a task rather than an event.
App Integrations Chat Message Boundary Event	Boundary message event	Receive a message while another activity is running.

A conversation process usually pairs the start event with a single catch element, and loops back to that element for each turn.

Desktop Modeler fetches connector templates automatically, so the templates appear without any setup unless you have turned that off.

Route a chat to the right process

A chat key decides which process the messages in a channel or chat start. You set it in two places that must match: the start event in your model, and the channel or chat in the Camunda app.

The App Integrations Chat Conversation Start Event template carries a Chat key property. It holds the full name of the message the process starts on, and must read io.camunda.appIntegrations.conversationStarted.<chat key>, for example io.camunda.appIntegrations.conversationStarted.hr-intake. It defaults to io.camunda.appIntegrations.conversationStarted.default. The template rejects a value in any other form, so a typo can't subscribe your process to an unrelated message.

You don't have to type the value. Configure the channel or chat first: open the Camunda app in the channel or chat, select the Settings tab, and the app shows the exact string to copy into the Chat key property.

The Settings tab asks for a short chat key, such as hr-intake, and for the organization and cluster the conversation runs in. Each channel and chat is in one of three states.

State	What you set	What a message does
Default process	Nothing. Every channel and chat starts here.	Starts the process whose chat key is default, in the organization and cluster the sender has selected.
Specific process	A chat key, and the organization and cluster to run it in.	Starts the process with that chat key, in the configured cluster, whoever writes the message.
Off	Nothing is processed here.	Reaches no process. The Camunda app answers with its help message instead.

Give a chat key to exactly one process definition per cluster. If two deployed processes carry the same chat key, both of them start on every message and both reply to the person, and nothing detects the clash for you.

Changing a chat key applies to the next conversation. A conversation already under way finishes with the process holding it.

The chat message variable

Every chat template writes the incoming message to a chatMessage process variable. Rename it with the Result variable property.

{
  "platform": "teams",
  "conversationKey": "teams:19:abc@thread.tacv2;messageid=17123456789",
  "conversation": "19:abc@thread.tacv2;messageid=17123456789",
  "messageId": "17123456799",
  "text": "approved, ship it",
  "user": {
    "externalUserId": "6b1e0f9a-1f3d-4a2b-9d0e-4c1b2a3d4e5f",
    "email": "ada@example.com"
  },
  "receivedAt": "2026-08-26T09:41:02.113Z"
}

Field	Description
platform	Always teams.
conversationKey	Identifies the conversation. Use it as the correlation key of a catch element. Compare it, don't parse it.
conversation	The conversation the message came from. Pass it back to reply.
messageId	This message's own identifier.
text	The message as typed. In a channel, the mention of the Camunda app is removed.
user.externalUserId	The sender's identifier on the chat platform.
user.email	The sender's Camunda email address.
receivedAt	When app integrations received the message, in ISO 8601 format.

Attachments, files, and edits to an existing message aren't delivered.

Correlate a message to the right conversation

The catch templates set Conversation to =chatMessage.conversationKey, which is the conversation the process is already in. A process started by the chat start event has chatMessage in scope, so a start event and a catch element work together with nothing to configure.

Change Conversation only when the key comes from somewhere else, such as the conversationKey reported by an earlier Send message delivery. That is how a process that speaks first waits for the answer.

Reply to the sender

Reply with a Send message task. Set Recipient source to Microsoft Teams, choose the Conversation target, and set it to =chatMessage.conversation.

The reply is posted by the Camunda app, in the same thread the person wrote in.

Where a process can be reached

Surface	A message reaches a process when
Microsoft Teams personal chat	Someone writes anything.
Microsoft Teams channel	Someone writes a message that @mentions the Camunda app.

In a channel, add the Camunda app to the channel and @mention it to start a conversation. Messages that address nobody aren't delivered to a process, so a process that expects replies in a channel should ask to be @mentioned, or use a personal chat instead.

What the sender sees

Situation	What happens
A process is holding the conversation.	The message reaches the process, and the Camunda app stays quiet so the two don't overlap.
The person types a word the Camunda app understands, such as help.	The Camunda app answers. Commands take precedence over the process.
The person hasn't connected their Camunda account.	They're prompted to connect, and no message is sent to a process.
The channel or chat uses the default process, and the person can reach more than one cluster without having chosen one.	They're asked to select an organization and cluster first.
The person can't reach the cluster the channel or chat is configured for.	The message reaches no process. Give them access to that cluster, or point the channel at one they can reach.
The channel or chat is turned off.	The message reaches no process, and the Camunda app answers with its help message.
No deployed process uses the chat key.	Nothing happens, and the Camunda app doesn't answer.

A reply always reaches the cluster whose process asked the question, even if the person switches to a different cluster while the conversation is open.

note

Tell people which words your conversation shouldn't use. Words the Camunda app already understands, such as help, reach the app rather than your process.

Troubleshooting

Connector not configured

When app integrations are not set up for the environment, every job fails immediately with the error code APP_INTEGRATIONS_NOT_CONFIGURED and raises an incident.

This failure is not retried. The Retries and Retry backoff settings on the task do not apply, because no amount of retrying can supply missing configuration. Only processes using this connector are affected — the connector runtime keeps serving every other connector.

Resolving it is an administrator task. See prerequisites.

Environment	Cause	Fix
SaaS	Enable app integrations extensions is off for the cluster.	Ask an organization administrator to enable it in the cluster settings.
Self-Managed	The connector runtime is not configured to reach app integrations.	Complete the App Integrations connection settings and redeploy the runtime.
Self-Managed	The runtime authenticates with OAuth, but no cluster ID is set.	Set the cluster ID to the cluster's UUID and redeploy the runtime. See choose an authentication method.

The incident message names the missing setting, so read it before changing configuration.

Other error codes

Code	Cause
VALIDATION_ERROR	Additional content is Form but no linked form reached the job, or an Adaptive Card payload is not valid JSON of the expected shape.
IO_ERROR	The request could not be serialized, or the response could not be parsed.
HTTP status, such as 401	App integrations returned an error. The error code is the HTTP status.

Troubleshooting

To learn about general error handling in Camunda, see BPMN errors and failing jobs.

Further resources

• Camunda for Microsoft Teams — act on Camunda tasks from inside Teams.
• Notification rules — automatic user task notifications, configured without modeling a connector.
• Adaptive Cards and the Adaptive Card designer.