Skip to main content

Microsoft Teams

Overview​

The Microsoft Teams integration (teams) lets apps message people, groups or app-role holders through the vastframe Teams bot. Apps share the platform's bot, so nobody registers a bot per app. The same bot delivers access request cards to approvers and notifications to requesters.

Integrationteams
Connection modePlatform
IdentityAlways the app (the grant covers the project, whoever triggers the call)
Default max scopesnotify:*
Default sensitivityLow

Prerequisites​

  • Recipients need a Microsoft Teams licence.
  • Recipients must be enabled people in the organization's directory.
Availability

Locally, a Teams stand-in records the bot's messages and renders cards per recipient. On Azure installations, delivery through Bot Framework (proactive messages and validated card actions) is planned and not yet available.

Permissions​

Each recipient is its own scope, so IT can see exactly whom an app may message.

ScopeLets the app message
notify:person@contoso.comOne person
notify:AccountingEvery enabled member of a directory group
notify:role:approverEveryone holding the app role approver in this project
notify:*Anyone (use as a max scope, not a grant)

Setup steps​

  1. Open Admin › Integrations and select Microsoft Teams.
  2. Set Approvers for Teams requests.
  3. Open Admin › Policies. The built-in rule "Teams messages to people who can open the app: auto" approves messages to recipients who can already open the app. Messages to anyone else go to the approvers.

Use it in an app​

await tc.teams.notify({ to: 'role:approver', text: 'New purchase request' });
await tc.teams.notify({ to: 'henrik.larsen@contoso.com', text: 'Your request was approved', card });
await tc.teams.notify({ to: ['Accounting', 'role:approver'], text: 'Month-end close starts Monday' });

to takes an email, a group name, role:<app role>, or a list of them. Send text, an Adaptive Card in card, or both.

The response lists who it was delivered to and any recipients still pending approval:

{
"delivered": [{ "to": "role:approver", "recipients": 2, "names": ["Henrik Larsen", "Lucy Zhang"] }],
"pending": [{ "to": "Accounting", "code": "ACCESS_PENDING", "message": "...", "request": { "id": 42 } }]
}

Partial delivery is normal: messages to approved recipients go out, and the rest wait for their request. If nothing could be delivered, the call fails with the first recipient's error (for example ACCESS_PENDING) instead.

Verify​

  1. Trigger a notification from the app.
  2. On the project's Integrations page, check Recent calls for a notify operation with status 200.
  3. Confirm the message arrived in the recipient's Teams chat with the bot.

Troubleshooting​

SymptomCauseFix
TC_BAD_REQUESTNo to, or neither text nor cardSend both a recipient and content.
A recipient is in pendingNo grant for that recipientApprove the request, or message people who can open the app.
Delivered to 0 recipientsThe group or role has no enabled membersCheck the group in the directory, or the role on the project's Access page.
PROJECT_NOT_ACTIVEThe project is archived or turned offRestore or re-enable the project.
Was this page helpful?