Articles in this section

Create a Teams App and Bot for Nudging

Updated

Overview

As a reseller, you can create your own Microsoft Teams app and bot for nudging. Subaccounts can install your Teams app in their Microsoft Teams client and sync their Teams teams as groups in Portal.

This article explains how to create the bot, gather the required Microsoft Entra credentials, configure the Teams app in the Microsoft Teams Developer Portal, grant the required Microsoft Graph permissions in Entra ID, download the finished Teams app package, and deploy the app to users with a Teams app setup policy.

Use the links below to jump to a section:

Before you begin

Confirm that you have access to the following Microsoft and Portal resources before creating the app:

  • Access to the Microsoft Teams Developer Portal.
  • Access to the Microsoft Entra admin center.
  • Access to the Microsoft Teams admin center, if you will deploy the app to users.
  • Permission to create or manage app registrations in Microsoft Entra ID.
  • The whitelabeled Portal domain used to access the reseller portal.
  • Branding assets for the Teams app, including the color icon and outline icon.
  • A Microsoft administrator who can grant admin consent for application permissions, if your organization requires it.
  • A Teams administrator who can allow, install, pin, and assign the app in Microsoft Teams, if the app will be deployed through a setup policy.

Important: Keep the client secret secure. The secret is used as the Client Secret when configuring the Teams integration in Portal.

Back to top

Create the bot

  1. Visit https://dev.teams.microsoft.com/.
  2. In the left navigation menu, select Tools, and then select Bot management.
  3. Select + New bot.
  4. Enter a name for the bot, and then select Add. The Teams Developer Portal opens the configuration screen for the new bot.
  5. Enter the endpoint address using the following format:
    https://<whitelabeled_portal_domain>/teams_controller.php
    Replace <whitelabeled_portal_domain> with the domain used to access your reseller portal.
  6. In the bot's menu, select Client secrets.
  7. Select Add a client secret for your bot.
  8. Copy the generated client secret. This value will be used as the Client Secret when setting up the Teams integration in Portal.

Creating the bot also creates an app in Microsoft Entra ID and ties the client secret to that app.

Back to top

Get your credentials to use

Before configuring the Teams integration in Portal, gather the Microsoft application identifiers from Entra ID.

  1. Visit https://entra.microsoft.com/.
  2. In the left navigation menu, select App registrations.
  3. Select the app that shares the name of the bot you created.
  4. On the app's Overview page, copy the following values:
    • Application (client) ID: Use this value as the Client ID when setting up the Teams integration in Portal.
    • Directory (tenant) ID: Use this value as the Tenant ID when setting up the Teams integration in Portal.

Back to top

Create the Teams app

  1. Visit https://dev.teams.microsoft.com/.
  2. In the left navigation menu, select Apps.
  3. Select + New app.
  4. Enter a name for the app, leave the manifest version at its default value, and then select Add.
  5. On the next screen, enter the required basic information for the app.
  6. In Application (client) ID, enter the Application (client) ID copied from Entra ID.
  7. Save your changes.
  8. In the left navigation menu, select Branding, and then upload the icons you want to use for the Teams app.
  9. Go to Configure > Permissions.
  10. In Chat/Meeting permissions, expand Application.
  11. Locate ChatMessageReadReceipt.Read.Chat, select the checkbox to the left of the permission, and save your changes.
  12. In the left navigation menu, select App features.
  13. Select Bot.
  14. In Identify your bot, choose Select an existing bot if it is not already selected, and then select the bot you created.
  15. In Select the scopes where people can use your bot, select Personal.
  16. Save your changes.
  17. Go to Configure > Single sign-on.
  18. Set Application ID URL using the following format:
    api://<your-whitelabeled-domain-here>/<entra_client_id>
    Replace <your-whitelabeled-domain-here> with your whitelabeled Portal domain and replace <entra_client_id> with the Application (client) ID copied from Entra ID.
  19. To make the app available to users, go to Publish > Publish to org.
  20. Submit the app.

Back to top

Settings to configure tracking in the Teams Developer Portal

Complete these settings so Portal can track when a user reads a bot message sent from a campaign configured to send nudging messages.

  1. Visit https://dev.teams.microsoft.com/apps.
  2. Select your app.
  3. Go to Configure > Permissions.
  4. In Chat/Meeting permissions, expand Application.
  5. Locate ChatMessageReadReceipt.Read.Chat, select the checkbox to the left of the permission, and save your changes.

Back to top

Settings to configure in Entra ID

Configure Microsoft Graph permissions in Entra ID so the app can find users by email in Microsoft Teams.

  1. Visit https://entra.microsoft.com/.
  2. Navigate to App registrations.
  3. In the Owned applications tab, find your app and select its name.
  4. In the secondary navigation menu, select API permissions.
  5. Select Add a permission.
  6. In the panel that opens, select Microsoft Graph from the Microsoft APIs tab.
  7. Select Application permissions.
  8. Search for User.Read.All.
  9. Under User, select User.Read.All.
  10. Repeat the previous search and selection steps to add Group.Read.All and TeamMember.Read.All.
  11. Grant admin consent for the permissions if your organization requires administrator approval.
  12. In the secondary navigation menu, select Authentication.
  13. Select Add a platform or Add Redirect URI, depending on the Entra ID interface shown.
  14. Choose Web.
  15. In Redirect URI, enter the following URL:
    https://<your-whitelabeled-domain-here>/authorize_teams.php
    Replace <your-whitelabeled-domain-here> with your whitelabeled Portal domain.

Back to top

Download your finished Teams app

  1. Visit https://dev.teams.microsoft.com/.
  2. In the left navigation menu, select Apps, and then select your Teams app.
  3. Select Configure > App package editor.
  4. Select Download to download the Teams app package.

Upload the downloaded Teams app package when configuring the Teams integration in Portal.

Back to top

Deploy the Teams app to users

Use a Teams app setup policy when the Teams app should be installed automatically for assigned users. For Microsoft guidance, see Manage app setup policies in Microsoft Teams.

  1. Visit https://dev.teams.microsoft.com/
  2. Go to Teams apps > Setup policies.
  3. Edit the Global org-wide default policy, or create a new policy.
  4. Under Installed apps, select Add apps.
  5. Search for the Teams app, select it, and then select Add.
  6. Optional: Under Pinned apps, add the app so users can access it from the Teams left rail.
  7. Save the policy.
  8. Assign the policy to the applicable users by going to Users, selecting the users, opening Policies, and assigning the app setup policy. If the tenant supports group policy assignment, assign the policy to the applicable groups instead.

 

Back to top

  • After creating the app package, see Configure Microsoft Teams Nudging for Subaccounts (Resellers) for steps to enter the Client ID, Client Secret, Tenant ID, and Teams app package in Portal.
  • For subaccount setup and branding behavior, see Configure and Brand Microsoft Teams Nudging (Subaccounts).

Back to top

Troubleshooting

The Teams integration test fails in Portal

Confirm that the Client ID, Client Secret, and Tenant ID all belong to the same Microsoft application and tenant. Also confirm that the required Microsoft Graph application permissions were added and granted admin consent.

The Teams app package cannot be installed

Confirm that the package was downloaded as a ZIP file from the Microsoft Teams Developer Portal and that the app's required basic information, bot configuration, branding, permissions, and single sign-on values are complete.

The app is not available in the Teams admin center

If the app is blocked, go to Teams apps > Manage apps and allow the app. For custom or internal apps, confirm that custom app upload and organization app permissions are configured correctly before assigning the setup policy.

The app does not appear for assigned users

Confirm that the correct app setup policy is assigned to the users or groups. Policy changes can take several hours to apply and may take up to 24 hours.

The redirect URI does not work

Confirm that the redirect URI uses the correct whitelabeled Portal domain and follows this format: https://<your-whitelabeled-domain-here>/authorize_teams.php.

The app cannot find users by email

Confirm that User.Read.All, Group.Read.All, and TeamMember.Read.All were added as Microsoft Graph application permissions in Entra ID and approved by an administrator if required.

Back to top

Was this article helpful?
0 out of 0 found this helpful