Articles in this section

Configure a Custom Teams App for a White-Labeled Teams Bot

Updated

Overview

As a reseller, you can create a custom Microsoft Teams app for your white-labeled Teams bot. The app connects Microsoft Teams to your branded portal so that selected teams and their members can be synchronized into the platform. The integration can also support Teams-based notifications.

Important: Complete these steps in the reseller account or subaccount that will use the integration. Each integration uses the Microsoft application credentials saved for that account.

Use the links below to jump to a section:

Requirements

Before you begin, make sure you have the following:

  • A reseller account or reseller subaccount with access to Administration > Integration Store.
  • Node.js 20 or later on the computer where you will run the Teams Developer CLI.
  • A Microsoft 365 account that can create applications and install custom Teams apps.
  • Custom app upload, also called sideloading, enabled for the Microsoft 365 tenant.
  • Permission to update the app registration in Microsoft Entra and grant tenant-wide admin consent.
  • The public HTTPS URL of your white-labeled portal. The Teams bot endpoint must use this portal's domain.

Security note: The generated .env file contains application credentials. Store it securely, do not commit it to source control, and do not share its client secret.

Back to top

Create the custom Teams app

  1. Open a terminal and install the Microsoft Teams Developer CLI:

    npm install -g @microsoft/teams.cli

  2. Sign in to the Microsoft 365 tenant that will own the app:

    teams login

  3. Check the tenant and account status:

    teams status

    Confirm that the output shows Sideloading: enabled. If it shows disabled, ask the tenant administrator to enable custom app upload before continuing.

  4. From the directory where you want the credential file to be created, run the following command as a single line:

    teams app create --name "My Teams Bot" --endpoint https://your-white-labeled-portal.example/teams_controller.php --teams-managed --env .env

Replace the example values as follows:

  • My Teams Bot: Enter the customer-facing name for your branded Teams app.
  • https://your-white-labeled-portal.example: Enter the public HTTPS origin for your white-labeled portal.
  • Keep /teams_controller.php at the end of the endpoint URL. This is the portal endpoint that receives requests from your bot.

The command creates a .env file in the current directory. Keep this file: you will use its CLIENT_ID, CLIENT_SECRET, and TENANT_ID values when you configure the integration in the portal.

For additional CLI information, see Microsoft's Quickstart: Register your app.

Back to top

Configure Microsoft Graph permissions

The portal requires Microsoft Graph access to read users, groups, and team membership. Configure the app registration created by the CLI:

  1. Sign in to the Microsoft Entra admin center.
  2. Navigate to Identity > Applications > App registrations.
  3. Open the app registration for the Teams app you created.
  4. Navigate to API permissions > Add a permission > Microsoft Graph.
  5. Add the following Microsoft Graph permissions:
    • User.Read.All
    • Group.Read.All
    • TeamMember.Read.All
  6. Select Grant admin consent for the tenant, if required by your organization's Microsoft policies.
  7. Confirm that the permissions show a granted status before testing the integration in the portal.

These permissions can require administrator approval because they allow the app to read organization-wide directory and team information. For details, see the Microsoft Graph permissions reference.

Back to top

Install the app in Microsoft Teams

The teams app create command prints a Teams App ID and an Install in Teams link. Open that link while signed in to the intended Microsoft Teams tenant, and then select Add in Teams.

If you no longer have the install link:

  1. Run teams app list to find the Teams App ID.
  2. Run the following command, replacing the placeholder with that ID:
teams app get <teamsAppId> --install-link

Open the returned link and select Add. If Teams prevents the installation, verify that custom app upload is enabled and that your account is allowed to install custom apps.

Back to top

Connect the app in the Integration Store

  1. In the white-labeled portal, navigate to Administration > Integration Store.
  2. Use the Filter Integrations field to search for Teams.
  3. On the Teams integration card, select Setup.

Teams integration card in Administration > Integration Store, showing the Setup button and inactive status toggle.

The Teams integration card before initial configuration.

  1. In the Edit Configuration dialog, leave Active set to Yes.
  2. Copy the following values from the .env file into the matching fields:
    • CLIENT_ID into CLIENT ID.
    • CLIENT_SECRET into CLIENT SECRET.
    • TENANT_ID into TENANT ID.
  3. Select Test. The portal validates the credentials, endpoint, permissions, and access to the Microsoft tenant.
  4. After the test succeeds, select the Microsoft teams that you want the portal to synchronize.
  5. Select Save.

Note: The Save button remains unavailable until the current settings pass a test. If the test fails, the dialog shows Test Failed!; correct the configuration and run Test again.

After the first successful save, the button on the Teams card changes from Setup to Edit. Use Edit whenever you need to change credentials, teams, mappings, or activation status.

Back to top

Configure optional field mappings

Field mappings control how Microsoft user properties populate target fields in the portal. To configure them:

  1. In the Teams Edit Configuration dialog, expand Advanced settings.
  2. Under Optional field mapping, select Add Field.
  3. In Integration field, select the Microsoft user property to import.
  4. In Target field, select the portal field that should receive the value.
  5. Select Add Field again for each additional mapping. Select Remove beside a row that you do not want to keep.
  6. Select Test, and then select Save.

Available Microsoft properties include ID, email, display name, phone numbers, address fields, company name, job title, department, user principal name, account status, preferred language, employee ID, and office location. Available target fields include email, first and last name, company, title, address fields, phone numbers, language, department, manager fields, and optional custom fields.

Back to top

Select teams and verify synchronization

After the integration has been tested and saved, the selected Microsoft teams can be synchronized into the portal:

  • Each selected Microsoft team is synchronized as an integrated group.
  • Team members are synchronized as targets in the corresponding group.
  • Configured field mappings populate the matching target fields.
  • A previously deactivated portal target is reactivated when the active Microsoft user is synchronized again.
  • A target is deactivated when its corresponding Microsoft user becomes inactive and the integration synchronizes again.

To change the selected teams later, navigate to Administration > Integration Store, select Edit on the Teams card, update the selection, and then select Test > Save.

Back to top

Troubleshooting

teams status shows sideloading is disabled

Ask the Microsoft 365 tenant administrator to enable custom app upload and confirm that your account is permitted to install custom apps. Run teams status again before creating or installing the app.

The portal displays “Test Failed!”

  • Confirm that the CLIENT ID, CLIENT SECRET, and TENANT ID came from the same generated .env file.
  • Make sure the client secret has not expired or been revoked.
  • Confirm that the app has User.Read.All, Group.Read.All, and TeamMember.Read.All.
  • Confirm that administrator consent has been granted when required.
  • Verify that the bot endpoint is the public HTTPS address of your white-labeled portal followed by /teams_controller.php.

The Save button is unavailable

Select Test. The current configuration must pass before Save becomes available. Run the test again after changing credentials, team selections, or field mappings.

No teams appear for selection

Verify the Microsoft Graph permissions and administrator consent, confirm that the credentials belong to the intended tenant, and test the connection again. Also confirm that the signed-in tenant contains teams that the app can read.

The client secret was rotated

Navigate to Administration > Integration Store, select Edit on the Teams card, replace CLIENT SECRET, and then select Test > Save.

Back to top

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