# Microsoft Teams

Post and read messages in Teams channels and chats, ask for an approval in a chat, manage channels, chat members, online meetings and Planner tasks, and send activity feed notifications.

## Connect Microsoft Teams

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `microsoft teams` and choose **Microsoft Teams**.
3. Press **Sign in with Microsoft Teams**, then choose your account in Microsoft Teams’s window and allow access.

Before you sign in, the sheet asks:

- **Account type · Optional**: Which Microsoft accounts may sign in: common (work, school or personal; the default when empty), organizations (work or school only) or consumers (personal only). For your own app registered for one directory only (single tenant), its Directory (tenant) ID.

Microsoft Teams works with work or school accounts (Teams' APIs do not serve personal Microsoft accounts). Reading channel messages, managing channels and reading team members need an administrator’s consent for your organization.

**What if it says “Microsoft Teams sign-in isn’t set up here”?**

Signing in with Microsoft Teams needs a Microsoft Teams app on this installation, and it has none yet.

**On Cloud:** The sheet says “It’s set up once for everyone who uses this service, not by an organization.”

**Self-hosted:** An admin of the installation sees **Set up Microsoft Teams sign-in** instead, and sets it up once for everyone. Everyone else sees who to ask.

1. Create an app in Microsoft Teams’s developer settings ([Microsoft Teams’s guide](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app)).
2. In GoRunner, copy the **Redirect address to add in Microsoft Teams’s developer settings**, and add it to the app.
3. Paste the **Client ID** and **Client secret**, then press **Save and sign in**.

[Set up a sign-in app](https://docs.gorunner.io/self-host/oauth-apps#other-providers)

**Can I use my own Microsoft Teams app?**

Yes. In the sheet, open **Use your own Microsoft Teams app** and paste its **Client ID** and **Client secret**. Add the redirect address it shows to your app first. The connection then signs in through your app instead of the installation’s.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Microsoft Teams**. The trigger uses the same connection as the steps.

### On Teams Event

Starts a run when Microsoft Teams reports the event below (within seconds). Publishing the workflow subscribes to it in Microsoft Graph (Graph first checks the address); the subscription is renewed before it expires and removed when you unpublish. Every notification is checked against the subscription's secret, and one Graph sends again starts no second run. The run gets the ids of what changed (teamId, channelId, chatId, messageId…); add a Microsoft Teams step to read the message itself. Several changes Graph reports at once start one run, with all of them under notifications.

- **Trigger on · Required**: What starts a run. Channel messages and team members need an administrator's consent for the connection's permissions. Options: New channel message, New chat message, New channel, New chat, New team member. Default: New channel message.
- **Team · Required**: The team to watch. Shows when **Trigger on** is **New channel message**, **New channel** or **New team member**.
- **Channel · Required**: The channel to watch (its messages and replies). Shows when **Trigger on** is **New channel message**.
- **Include Replies · Optional**: Also start a run for replies in a thread, not only for new threads. On by default. Shows when **Trigger on** is **New channel message**.
- **Watch All Chats · Optional**: Every chat you are in, rather than one. Off by default. Shows when **Trigger on** is **New chat message**.
- **Chat · Required**: The chat to watch. Shows when **Trigger on** is **New chat message** and **Watch All Chats** is off.
- **Changes · Optional**: Which changes start a run: a new one, an edit (a message edited, a channel or chat renamed, a member's role changed) or a removal (a message deleted, a channel deleted, a member removed). Chats report no removals. Options: New, Edited, Removed.

A later step can use its data, such as `{{trigger.changeType}}`, `{{trigger.channelId}}`, `{{trigger.chatId}}` and 9 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Microsoft Teams

Add a **Microsoft Teams** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Channel Message](https://docs.gorunner.io/apps/microsoft-teams#fields-f-channelmessage): Create · Reply · Get · Get Many · Get Replies · Delete · Restore
- [Chat Message](https://docs.gorunner.io/apps/microsoft-teams#fields-f-chatmessage): Create · Send and Wait for Approval · Get · Get Many · Delete · Restore
- [Channel](https://docs.gorunner.io/apps/microsoft-teams#fields-f-channel): Create · Get · Get Many · Update · Delete
- [Chat](https://docs.gorunner.io/apps/microsoft-teams#fields-f-chat): Create · Get · Get Many
- [Chat Member](https://docs.gorunner.io/apps/microsoft-teams#fields-f-chatmember): Add · Get Many · Remove
- [Online Meeting](https://docs.gorunner.io/apps/microsoft-teams#fields-f-onlinemeeting): Create · Create or Get · Get · Update · Delete
- [Planner Task](https://docs.gorunner.io/apps/microsoft-teams#fields-f-task): Create · Get · Get Many · Update · Delete
- [Activity Notification](https://docs.gorunner.io/apps/microsoft-teams#fields-f-activitynotification): Send
- [Team](https://docs.gorunner.io/apps/microsoft-teams#fields-f-team): Get · Get Many

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Microsoft Teams can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Microsoft Teams says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Microsoft Teams is `pieceId: "microsoftteams"` with `actionId: "microsoftteams"`, set by `resource` and an `operation_…` field, such as `operation_activityNotification`. Its trigger is `teamstrigger` / `microsoftteams_event`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Microsoft Teams › Channel Message

### Create

- **Team · Required**: The team. Pick one of yours, or paste its id (a team's id is its Microsoft 365 group id).
- **Channel · Required**: The channel in that team.
- **Content Type · Required**: Whether the message is plain text or HTML. Options: Text, HTML. Default: Text.
- **Message · Required**: The message to post (at most about 28 KB).
- **Subject · Optional**: A subject line for a new thread (optional).
- **Importance · Optional**: Normal, high, or urgent (urgent rings the recipients repeatedly; in channels Teams shows it as important). Options: Normal, High, Urgent. Default: Normal.

### Reply

- **Team · Required**: The team. Pick one of yours, or paste its id (a team's id is its Microsoft 365 group id).
- **Channel · Required**: The channel in that team.
- **Message ID · Required**: The id of the message (the thread's first message, for a reply).
- **Content Type · Required**: Whether the message is plain text or HTML. Options: Text, HTML. Default: Text.
- **Message · Required**: The message to post (at most about 28 KB).
- **Importance · Optional**: Normal, high, or urgent (urgent rings the recipients repeatedly; in channels Teams shows it as important). Options: Normal, High, Urgent. Default: Normal.

### Get

- **Team · Required**: The team. Pick one of yours, or paste its id (a team's id is its Microsoft 365 group id).
- **Channel · Required**: The channel in that team.
- **Message ID · Required**: The id of the message (the thread's first message, for a reply).

### Get Many

- **Team · Required**: The team. Pick one of yours, or paste its id (a team's id is its Microsoft 365 group id).
- **Channel · Required**: The channel in that team.
- **Return All · Optional**: Read every message, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many messages to return (1–2000). Default: 50. Shows when **Return All** is off.

### Get Replies

- **Team · Required**: The team. Pick one of yours, or paste its id (a team's id is its Microsoft 365 group id).
- **Channel · Required**: The channel in that team.
- **Message ID · Required**: The id of the message (the thread's first message, for a reply).
- **Return All · Optional**: Read every message, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many messages to return (1–2000). Default: 50. Shows when **Return All** is off.

### Delete and Restore

- **Team · Required**: The team. Pick one of yours, or paste its id (a team's id is its Microsoft 365 group id).
- **Channel · Required**: The channel in that team.
- **Message ID · Required**: The id of the message (the thread's first message, for a reply).
- **Reply ID · Optional**: To delete or restore a reply in the thread rather than the thread's first message, the reply's id.

### Microsoft Teams › Chat Message

### Create

- **Chat · Required**: The chat. Pick one of your recent chats, or paste its id.
- **Content Type · Required**: Whether the message is plain text or HTML. Options: Text, HTML. Default: Text.
- **Message · Required**: The message to post (at most about 28 KB). For Send and Wait, the context the approver needs; the Approve and Reject links are added below it.
- **Importance · Optional**: Normal, high, or urgent (urgent notifies the chat's members every 2 minutes for 20 minutes). Options: Normal, High, Urgent. Default: Normal.

### Send and Wait for Approval

- **Chat · Required**: The chat. Pick one of your recent chats, or paste its id.
- **Title · Optional**: What is being decided; it opens the message in bold.
- **Message · Required**: The message to post (at most about 28 KB). For Send and Wait, the context the approver needs; the Approve and Reject links are added below it.
- **Buttons · Optional**: Approve and Reject, or Approve only (an acknowledgement). Options: Approve and Reject, Approve only. Default: Approve and Reject.
- **Auto-continue after (timeout) · Optional**: Resume by itself after this long when nobody answers (0 waits for an answer). On timeout nobody decided, so branch on status == "approved", never on the step having finished. Default: 0.
- **Timeout Unit · Optional**: Options: Seconds, Minutes, Hours, Days. Default: Hours.
- **Public Base URL · Optional**: The address the Approve and Reject links open; empty uses this installation's public URL.

### Get, Delete and Restore

- **Chat · Required**: The chat. Pick one of your recent chats, or paste its id.
- **Message ID · Required**: The id of the message.

### Get Many

- **Chat · Required**: The chat. Pick one of your recent chats, or paste its id.
- **Return All · Optional**: Read every message, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many messages to return (1–2000). Default: 50. Shows when **Return All** is off.

### Microsoft Teams › Channel

### Create

- **Team · Required**: The team. Pick one of yours, or paste its id (a team's id is its Microsoft 365 group id).
- **Name · Required**: The channel's name (at most 50 characters; no ~ # % & * { } + / \: \< >? | ' ").
- **Description · Optional**: What the channel is for; empty keeps it (Update).
- **Type · Optional**: Standard (everyone in the team), private (only the members you add; you are its owner) or shared (people outside the team can be added). Options: Standard, Private, Shared. Default: Standard.

### Get and Delete

- **Team · Required**: The team. Pick one of yours, or paste its id (a team's id is its Microsoft 365 group id).
- **Channel · Required**: The channel in that team.

### Get Many

- **Team · Required**: The team. Pick one of yours, or paste its id (a team's id is its Microsoft 365 group id).
- **Return All · Optional**: Read every channel, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many channels to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Team · Required**: The team. Pick one of yours, or paste its id (a team's id is its Microsoft 365 group id).
- **Channel · Required**: The channel in that team.
- **New Name · Optional**: A new name for the channel; empty keeps it.
- **Description · Optional**: What the channel is for; empty keeps it (Update).

### Microsoft Teams › Chat

### Create

- **Chat Type · Optional**: One on one (you and one person; Teams returns the existing chat if there is one) or a group chat. Options: One on one, Group. Default: One on one.
- **Members · Required**: The people to chat with besides you: email addresses, user principal names or user ids, separated by commas (one for one on one).
- **Topic · Optional**: A group chat's name (optional).

### Get

- **Chat · Required**: The chat. Pick one of your recent chats, or paste its id.
- **Include Members · Optional**: Also return each chat's members. Off by default.

### Get Many

- **Include Members · Optional**: Also return each chat's members. Off by default.
- **Return All · Optional**: Read every chat, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many chats to return (1–2000). Default: 50. Shows when **Return All** is off.

### Microsoft Teams › Chat Member

### Add

- **Chat · Required**: The chat. Pick one of your recent chats, or paste its id.
- **User · Required**: The person to add: an email address, user principal name or user id.
- **Share Chat History · Optional**: Let the new member see the messages sent before they joined. Off by default.

### Get Many

- **Chat · Required**: The chat. Pick one of your recent chats, or paste its id.
- **Return All · Optional**: Read every member, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many members to return (1–2000). Default: 50. Shows when **Return All** is off.

### Remove

- **Chat · Required**: The chat. Pick one of your recent chats, or paste its id.
- **Membership ID · Required**: The member's membership id in this chat (id from Get Many, not the user's id).

### Microsoft Teams › Online Meeting

### Create

- **Organizer · Optional**: Empty for you (the signed-in user). A signed-in user can only organize their own meetings.
- **Subject · Optional**: The meeting's subject.
- **Start · Optional**: When the meeting starts (ISO 8601 with a time zone, such as 2026-11-07T15:00:00Z). Create or Get: empty is now.
- **End · Optional**: When it ends. Create or Get: empty is an hour after the start.
- **Attendees · Optional**: User principal names of the people to invite, separated by commas (optional).

### Create or Get

- **External ID · Required**: Your own id for the meeting: the same External ID returns the meeting made before instead of a new one.
- **Subject · Optional**: The meeting's subject.
- **Start · Optional**: When the meeting starts (ISO 8601 with a time zone, such as 2026-11-07T15:00:00Z). Create or Get: empty is now.
- **End · Optional**: When it ends. Create or Get: empty is an hour after the start.
- **Attendees · Optional**: User principal names of the people to invite, separated by commas (optional).

### Get, Update and Delete

- **Organizer · Optional**: Empty for you (the signed-in user). A signed-in user can only organize their own meetings.
- **Meeting ID · Required**: The online meeting's id.
- **Subject · Optional**: The meeting's subject.
- **Start · Optional**: When the meeting starts (ISO 8601 with a time zone, such as 2026-11-07T15:00:00Z). Create or Get: empty is now.
- **End · Optional**: When it ends. Create or Get: empty is an hour after the start.

### Microsoft Teams › Planner Task

### Create

- **Team · Optional**: The team (Microsoft 365 group) whose plans to pick from. Only used to list its plans in the Plan picker.
- **Plan · Optional**: The Planner plan (Get Many: the plan to list when Tasks For is A plan).
- **Bucket · Required**: The plan's bucket (column) the task goes in.
- **Title · Required**: The task's title.
- **Assigned To · Optional**: User ids of the people to assign, separated by commas (optional; Update adds them).
- **Due · Optional**: When the task is due (ISO 8601 with a time zone).
- **Percent Complete · Optional**: 0 not started, 1–99 in progress, 100 completed (optional).

### Get and Delete

- **Task ID · Required**: The Planner task's id.

### Get Many

- **Team · Optional**: The team (Microsoft 365 group) whose plans to pick from. Only used to list its plans in the Plan picker.
- **Tasks For · Optional**: Your own tasks across plans, or every task of one plan. Options: Assigned to me, A plan. Default: Assigned to me.
- **Plan · Optional**: The Planner plan (Get Many: the plan to list when Tasks For is A plan).
- **Return All · Optional**: Read every task, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many tasks to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Task ID · Required**: The Planner task's id.
- **Title · Optional**: A new title; empty keeps it.
- **Assigned To · Optional**: User ids of the people to assign, separated by commas (optional; Update adds them).
- **Due · Optional**: When the task is due (ISO 8601 with a time zone).
- **Percent Complete · Optional**: 0 not started, 1–99 in progress, 100 completed (optional).
- **Move to Bucket · Optional**: A bucket id of the same plan to move the task to (optional).

### Microsoft Teams › Activity Notification

### Send

- **Recipient · Required**: Who gets the notification: a user principal name or user id.
- **Headline · Required**: The notification's first line.
- **Preview Text · Required**: The line under it (Teams shows the first 150 characters).
- **Topic · Required**: What the notification is about, shown as its title.
- **Topic Link · Required**: The Teams address the notification opens (https://teams.microsoft.com/…).
- **Chain ID · Optional**: Optional: the same Chain ID replaces the recipient's earlier notification instead of adding one.

### Microsoft Teams › Team

### Get

- **Team · Required**: The team. Pick one of yours, or paste its id (a team's id is its Microsoft 365 group id).

### Get Many

- **Return All · Optional**: Read every team, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many teams to return (1–2000). Default: 50. Shows when **Return All** is off.

Source: https://docs.gorunner.io/apps/microsoft-teams