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.
| Integration | teams |
|---|---|
| Connection mode | Platform |
| Identity | Always the app (the grant covers the project, whoever triggers the call) |
| Default max scopes | notify:* |
| Default sensitivity | Low |
Prerequisites
- Recipients need a Microsoft Teams licence.
- Recipients must be enabled people in the organization's directory.
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.
| Scope | Lets the app message |
|---|---|
notify:person@contoso.com | One person |
notify:Accounting | Every enabled member of a directory group |
notify:role:approver | Everyone holding the app role approver in this project |
notify:* | Anyone (use as a max scope, not a grant) |
Setup steps
- Open Admin › Integrations and select Microsoft Teams.
- Set Approvers for Teams requests.
- 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
- Trigger a notification from the app.
- On the project's Integrations page, check Recent calls for a
notifyoperation with status200. - Confirm the message arrived in the recipient's Teams chat with the bot.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
TC_BAD_REQUEST | No to, or neither text nor card | Send both a recipient and content. |
A recipient is in pending | No grant for that recipient | Approve the request, or message people who can open the app. |
| Delivered to 0 recipients | The group or role has no enabled members | Check the group in the directory, or the role on the project's Access page. |
PROJECT_NOT_ACTIVE | The project is archived or turned off | Restore or re-enable the project. |