Skip to main content

Microsoft Teams

Overview​

This integration enables Orbb to operate as an app inside Microsoft Teams, sending notifications, creating group chats with stakeholders, and analyzing communication signals across your organization. The integration uses Microsoft Entra admin consent and a one-time Teams app manifest upload to securely connect to your Microsoft 365 tenant and provide comprehensive access to chats, channels, users, and messaging capabilities.

Prerequisites​

  • A Microsoft 365 tenant where you have Teams admin or Global admin privileges
  • Permission to authorize Microsoft Entra applications in your tenant
  • Your tenant's app setup policy must allow uploading custom apps
caution

Only users with administrative privileges can perform these actions. Ensure you have the necessary permissions before proceeding.

Permissions​

The Teams integration uses two complementary permission systems: Microsoft Graph application permissions (consented during connect, scoped to your whole tenant) and Resource-Specific Consent (RSC) permissions (declared in the Teams app manifest and consented at upload, scoped to chats, teams, and users where Orbb is invited).

The following Microsoft Graph application permissions are required:

AppCatalog.Read.All
Chat.Create
TeamsAppInstallation.ReadWriteSelfForUser.All
TeamsAppInstallation.ReadWriteAndConsentSelfForChat.All
TeamsAppInstallation.ReadWriteAndConsentSelfForTeam.All
TeamsAppInstallation.ReadWriteAndConsentSelfForUser.All
User.Read.All

The following RSC permissions are declared in the manifest:

ChannelMessage.Read.Group
ChannelMessage.Send.Group
ChannelSettings.Read.Group
TeamMember.Read.Group
TeamSettings.Read.Group
TeamsAppInstallation.Read.Group
TeamsActivity.Send.Group
ChatMessage.Read.Chat
ChatMember.Read.Chat
ChatSettings.Read.Chat
TeamsAppInstallation.Read.Chat
TeamsActivity.Send.Chat
TeamsActivity.Send.User
TeamsAppInstallation.Read.User
Permissions Explanation

Here's what each permission enables:

  • Tenant-wide app permissions:

    • AppCatalog.Read.All: Locate the Orbb app in your tenant's Teams app catalog.
    • Chat.Create: Create group chats for multi-stakeholder notifications.
    • TeamsAppInstallation.ReadWriteSelfForUser.All: Install the Orbb bot in a user's personal scope.
    • TeamsAppInstallation.ReadWriteAndConsentSelfForChat.All: Install Orbb in a group chat with its RSC permissions consented.
    • TeamsAppInstallation.ReadWriteAndConsentSelfForTeam.All: Install Orbb in a team with its RSC permissions consented.
    • TeamsAppInstallation.ReadWriteAndConsentSelfForUser.All: Install Orbb for a user with its RSC permissions consented.
    • User.Read.All: Read full user profiles (name, email, job title, department, manager) for relationship intelligence.

  • Team and channel scopes (when Orbb is invited to a team):

    • ChannelMessage.Read.Group: Read messages in that team's channels.
    • ChannelMessage.Send.Group: Post messages to that team's channels.
    • ChannelSettings.Read.Group: Read channel names, descriptions, and settings.
    • TeamMember.Read.Group: Read the team's members.
    • TeamSettings.Read.Group: Read team metadata.
    • TeamsAppInstallation.Read.Group: See which apps are installed in the team.
    • TeamsActivity.Send.Group: Send activity-feed notifications to team members.

  • Chat scopes (when Orbb is invited to a group chat):

    • ChatMessage.Read.Chat: Read messages in that chat.
    • ChatMember.Read.Chat: Read the chat's members.
    • ChatSettings.Read.Chat: Read chat settings (topic, etc.).
    • TeamsAppInstallation.Read.Chat: See which apps are installed in the chat.
    • TeamsActivity.Send.Chat: Send activity-feed notifications to chat participants.

  • User scopes (when Orbb is installed for a user):

    • TeamsActivity.Send.User: Send activity-feed notifications to the user's bell icon.
    • TeamsAppInstallation.Read.User: Read which apps are installed in the user's personal scope.
tip

RSC permissions are scoped to where Orbb is invited. If you don't add Orbb to a particular team or chat, Orbb has no access to messages or members there.

Integration Steps​

1. Upload the Orbb Teams manifest​

  1. In your Orbb dashboard, navigate to Admin → Integrations → Chat
  2. Click Download manifest and save the .zip file to your computer
  3. Sign in to the Microsoft Teams Admin Center as a Teams admin
  4. Open Teams apps → Manage apps, click Actions → Upload new app, and select the .zip file
  5. When prompted, review and Allow the requested RSC permissions
tip

Keep the zip as-is — don't unzip or modify its contents. Microsoft Teams expects the exact package Orbb produces.

2. Authorize Orbb​

  1. Back in your Orbb dashboard at Admin → Integrations → Chat, click Connect with Teams
  2. You will be redirected to Microsoft's authorization page
  3. Review the requested permissions (scopes) and click Accept
  4. You will be redirected back to Orbb with the integration configured
tip

After authorization is complete, you can test the integration by sending a test notification to ensure everything is working correctly.

Security Considerations​

  • The connection is secure and can be revoked at any time from the Microsoft Entra admin center → Enterprise applications
  • Removing the Orbb app from your Teams app catalog blocks new installations
  • RSC permissions only apply where Orbb is invited — uninviting Orbb from a specific chat or team immediately revokes its access there
  • Monitor the integration's usage through the Microsoft Teams Admin Center

Troubleshooting​

If you encounter any issues:

  1. Verify that the Microsoft authorization was successful
  2. Check that the Orbb Teams app has been uploaded to your tenant's app catalog and given 1–2 minutes to propagate
  3. Ensure your tenant's app setup policy allows uploading custom apps (Teams admin center → Teams apps → Setup policies)
  4. If a recent Orbb manifest update added new permissions, re-upload the manifest to re-trigger the consent dialog
  5. Try disconnecting and reconnecting the integration if issues persist