Skip to content

Microsoft Teams

Microsoft Teams channels send a post to one Teams channel or group chat through the UmbHost.Automate.Teams package and its Post a Card to Microsoft Teams action (teams.postCard). It is meant for internal news, not public posts.

dotnet add package UmbHost.Automate.Teams

You don’t need an Azure app, an admin’s consent or a Microsoft developer account. Anyone who can create a Workflow in Teams can connect it.

  • Commercial Microsoft 365 with Teams, and permission to create Workflows in it. GCC High, DoD and 21Vianet aren’t supported.
  • Membership of the team and channel, or the group chat, that should get the posts.
  • Your site’s public https address, if posts will have images. Teams loads them from your site.

There are no permissions to request, no review and no redirect URL.

You need a Workflow address: the web address a Teams Workflow gives you. One address is one destination, so each channel or chat that should get posts needs its own Workflow.

  1. In Teams, open Workflows and search the templates for the webhook one. Microsoft has named it Post to a channel when a webhook request is received, and more recently Send webhook alerts to a channel. For a group chat, choose the chat version of the same template.
  2. Choose the plain template, not the ones “from specific people” or “from people in an org”: those check who is posting, and UmbSocial doesn’t sign in to Teams.
  3. Pick the team and channel (or the chat) it should post to, and create the Workflow.
  4. Leave the trigger’s Who can trigger set to Anyone. A trigger limited to your organisation’s users refuses every post.
  5. Copy the address it shows you. It’s on a Microsoft Workflows host, ending logic.azure.com or api.powerplatform.com.

Microsoft’s guide is Send messages in Teams using incoming webhooks, and the trigger is described in the Microsoft Teams connector reference.

Put the address in configuration, not in the connection:

{ "Umbraco": { "Automate": { "Secrets": { "TeamsWebhookUrl": "..." } } } }

Keep it out of appsettings.json in source control: use user secrets or an environment variable, Umbraco__Automate__Secrets__TeamsWebhookUrl.

Give each Teams destination its own secret. The default name, TeamsWebhookUrl, can hold only one address. For a second channel or chat, add another secret with its own name, such as TeamsCompanyNewsWebhookUrl:

{ "Umbraco": { "Automate": { "Secrets": { "TeamsWebhookUrl": "...", "TeamsCompanyNewsWebhookUrl": "..." } } } }

Then point that connection’s Workflow address at it: $Umbraco:Automate:Secrets:TeamsCompanyNewsWebhookUrl. A second connection left on the default posts into the first one’s channel or chat.

Automate → Connections → Create → Microsoft Teams. Its one setting is the Workflow address, which is a secret and is filled in with $Umbraco:Automate:Secrets:TeamsWebhookUrl by default. For any connection after the first, change it to the secret you named for that destination.

Press Test connection on the connection. It posts a card titled UmbSocial test into the channel or chat, so check it appears there. Saving the connection never posts anything; only Test connection does. If the address is wrong, the test fails and names the host only, never the address.

  1. In Automate, open the workspace UmbSocial uses and add the connection to its Allowed Connections. The workspace needs a Service Account (an API user). See Connecting networks.
  2. In Umbraco’s Settings section, open UmbSocial › Connections, choose Create, name the channel, pick Microsoft Teams and the connection, and Save. The channel shows the connection’s name, so name the connection for where it posts, such as “Company news channel”. A Teams channel takes no options.
  3. Check that Enabled is on. A channel that came from another environment shows Needs connecting: choose Connect on it instead, then switch it on.

See Connecting networks for the rest.

Each post becomes a card in Teams.

Post field Sent as
Text The card’s text, up to 4,000 characters. It shows as you typed it: Markdown and HTML characters aren’t interpreted.
Image Optional. Shown in the card.
Image alt text Sent, as the image’s alt text.
Link URL A button under the card, labelled with the link title, or Open link if there is none. Not added to the text.
Link description Not sent.

Teams takes no thread, first comment, content warning, Pin title or call to action, so the composer doesn’t offer them. See Network limits.

Teams loads the image from your site, so it only appears if your site can be reached from the internet. The composer says so under the Teams preview when the post has an image.

Posts appear in Teams as Workflows. That is Microsoft’s limit: a Workflow can’t post under another name or icon. Only commercial Microsoft 365 is supported, not GCC High, DoD or 21Vianet.

A sent post shows Sent to Teams, with no View post link. Teams answers that it received the post. It doesn’t say the post appeared, and it gives no address for the message.

If a post doesn’t appear in Teams, open the Workflow in Teams and check its run history. The Automate run for the post carries the same note: Teams accepted the post. It can’t confirm it appeared: if it didn’t, check the Workflow’s run history in Teams.

UmbSocial records a sent Teams post as Published, as for any network.

None. Teams gives no message id to ask about, so UmbSocial reads no figures and shows Not available on Microsoft Teams. See Views and interactions.

A Teams channel counts towards the free edition’s three channels, like any other. See Editions and licensing.

  • The Workflow was deleted or switched off. Teams answers that the address no longer works. The post fails and isn’t retried. Switch the Workflow back on, or create a new one and update the secret.
  • The trigger isn’t set to Anyone. Teams refuses the post, and the run says Teams refused the post: the Workflow’s address no longer works, or its trigger isn’t set to Anyone. with the status and the host. Set Who can trigger back to Anyone, or create a new Workflow and update the secret. The post isn’t retried.
  • Teams answers with a redirect. Redirects are never followed, so nothing was sent. The run says Teams answered with a redirect, which is never followed. Check the Workflow address. Copy the address from the Workflow again.
  • Teams is busy. The post is retried later: nothing was posted.
  • No clear answer. If the request fails without a clear answer, the action doesn’t retry, because the post may have gone out. UmbSocial records the post as Unknown: check the channel before retrying.

Each channel posts to one account. Don’t add other post steps to a Teams channel’s automation: the post fails with channel.automation_changed. See Error codes.