MS Teams

The Novu Microsoft Teams integration enables you to send notifications to Teams channels and direct messages (DMs) across multiple customer workspaces using a single multi-tenant bot.

You create and host a Microsoft Teams App (Bot) in your Azure environment, while your customers simply authorize (via Admin Consent) and install your bot into their specific Teams tenants.

Once a customer connects their workspace, Novu establishes a secure channel connection using your bot's credentials. You then map specific destinations, whether they are public channels or individual users to channel endpoints, allowing Novu to route notifications dynamically to the correct tenant and conversation context.

Azure and Teams configuration

Before you can configure Novu, you must create the infrastructure that hosts your bot. This involves two distinct portals:

• Azure portal: To create the identity (App Registration) and infrastructure (Bot Service).
• Teams developer Portal: To create the "App Package" that your customers will install.

Create the app identity (Azure AD)

First, we need to create a multi-tenant identity for your bot.

1. Log in to the Azure Portal.
2. In the left menu, select Microsoft Entra ID (formerly Azure Active Directory).
3. In the left menu, under the Manage section, select App registrations.
4. Click New registration to create an application.
5. Fill in the form:
   • Name: Enter any name of your choice
   • Supported account types: Select Accounts in any organizational directory (Any Microsoft Entra ID directory - Multitenant).
6. Click Register.
7. After creation, note the Application (client) ID and Directory (tenant) ID, they will be required to configure MS Teams in Novu.

Configure client secret

1. From your new app's overview page, in the left menu, go to Certificates & secrets.
2. Click New client secret.
3. Add a description and set an expiration.
4. Click Add
5. Copy the Value. This is your BOT_APP_SECRET, you'll need to paste it into Novu. This value cannot be viewed, except for immediately after creation. Be sure to save the secret when created before leaving the page.

Add Novu’s redirect URI

After your customers go through the admin consent page. Microsoft must know where to send the result (Novu).

1. In the app sidebar, go to Authentication (Preview).
2. Click Add Redirect URI
3. In the menu that appears, click Web.
4. In the Redirect URI field, set the redirect URI to the Novu OAuth callback URL:
   • US region

   https://api.novu.co/v1/integrations/chat/oauth/callback

   • EU region

   https://eu.api.novu.co/v1/integrations/chat/oauth/callback

   
5. Click Configure

Add Microsoft Graph application permissions

These permissions lets your app list teams and channels to determine where messages should be sent.

1. In the app sidebar, go to API permissions.
2. Click Add a permission.
3. Click Microsoft Graph.
4. Click Application permissions.
5. Search for and check the following permissions:
   • Team.ReadBasic.All
   • Channel.ReadBasic.All
   • AppCatalog.Read.All
   • TeamsAppInstallation.ReadWriteSelfForTeam.All (optional, for automation)
   • TeamsAppInstallation.ReadWriteSelfForUser.All (optional, for automation)
6. Click Add permissions.

Create an Azure Bot resource

Now you register your bot with the Azure AI Bot Service and link it to the app registration you just created. In the Azure portal, click Create a resource.

1. In the Azure portal left menu,, click Create a resource.
2. Search for “Azure Bot” and select the Azure Bot resource.
3. Click Create.
4. Fill in the basics:
   • Bot handle: This is a unique display name in Azure.
   • Subscription: Select the Azure subscription.
   • Resource group: A resource group is a collection of resources that share the same lifecycle, permissions, and policies, you can either select or create one.
   • Data residency: Specify an option for data residency, either global or regional.
5. Under Microsoft App ID:
   • Type of app: Select Single-tenant app registration.
   • Creation type: Choose “Use existing app registration” and use app IDs you created earlier:
     • App ID: Replace with the Application (client) ID.
     • App tenant ID: Replace with the Directory (tenant) ID.
6. Click Review + create.
7. Click Create.

Enable the Microsoft Teams channel

This connects your bot resource to Teams and is required for your Teams app to install cleanly.

1. Once the deployment finishes, click Go to resource.
2. In the left menu, go to Settings
3. Click Channels.
4. In the available channelssection, click Microsoft Teams.
5. In the menu that appears, accept the terms of services.
6. In the Messaging section, choose the appropriate environment (typically Microsoft Teams Commercial).
7. Click Apply

Create a Teams app

Now you create the Teams “wrapper” around your app registration and bot.

1. Open the Teams Developer Portal.
2. Click Apps.
3. Click + New app and then enter a name.
4. Click Add.
5. In the basic information page, fill in the required fields.
6. In the left menu, select App feature.
7. Add a Bot and choose “Enter a bot ID”
8. Set the Bot ID to your BOT_APP_ID (the same App ID you used for the Azure Bot).
9. Enable “What can your bot do?” to at minimum “Only send notification”
10. Enable scopes based on your usecase:
    • team (for channel messages)
    • personal (for DMs)

You don’t need to edit the JSON yourself, The developer portal will generate and validate this for you.

Publish the Teams app

Next, publish the app to a Teams store, if you want the app publicly available in the store or publish to org if you want your App to be accessible only inside your organization teams.

Refer to the Microsoft Teams documentation to learn how to:

• Publish to your org.
• Publish to the Teams store.

Configure the Teams (Bot) integration in Novu

Now that your Azure Bot is configured, you need to provide Novu with the credentials to integrate it.

1. Log in to the Novu dashboard.
2. In the sidebar, click Integrations Store.
3. Click Connect Provider.
4. Select Chat and click MSTeams.
5. Enter the credentials you saved from the Azure Portal:
   • Client ID: Enter your BOT_APP_ID.
   • Client Secret: Enter your BOT_APP_SECRET.
   • App Tenant ID: Enter your APP_TENANT_ID (This is your specific tenant ID where the app was registered).
   • Redirect URL (Optional): If you want to control where your users land after they grant admin consent, enter that URL here. If left empty, the consent window will simply close automatically.
6. Click Create Integration

Novu is now authenticated to act as your Bot. However, it cannot send messages yet because no customers have installed the bot.

Let your customers connect their tenant

Each of your customers has their own Microsoft 365 tenant. Before you can send them messages, they must grant your app a one time admin consent. This authorizes your bot to act within their environment.

Generate a "Connect Teams" URL

On your backend, use the Novu SDK to generate the authorization URL. This URL is specific to the customer's tenant context in your system.

import { Novu } from '@novu/api';
 
const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });
 
const url = await novu.integrations.generateChatOAuthUrl({
  integrationIdentifier: 'ms-teams-bot', // The identifier used for that integration on Novu
  subscriberId: 'customer-admin-id',     // (optional)
  context: { tenant: 'acme-corp' },      // (optional)
});

Novu returns a URL pointing to Microsoft's admin consent endpoint. This URL already includes your Client ID, Redirect URI, and the necessary Graph scopes.

Show it in your UI

In your frontend application, bind this URL to a button:

// On "Connect Microsoft Teams" button click:
window.open(url, '_blank');

What the customer admin does

1. A Teams/Microsoft 365 Admin from your customer's organization logs into your product.
2. They clicks your Connect Microsoft Teams button.
3. They see a Microsoft consent page listing the permissions.
4. They clicks Accept.

When this is done, Microsoft redirects the user back to Novu. Novu captures the customer's tenant ID and automatically creates a Teams connection for that specific tenant context. You do not need to handle the callback yourself.

Customer installs your app in their Teams

Granting Admin consent in the previous step only authorizes your bot to exist in the customer's tenant. It does not automatically add the bot to any specific teams or chats.

For the bot to send messages, it must be installed in the specific context where notifications should appear:

• For channel messages: The app must be installed in the specific Team.
• For direct messages (DMs): The app must be installed for the specific User (Personal scope).

Your customer’s admin can install your app from the Teams app store or their org catalog, depending on how you published. However, if you requested the TeamsAppInstallation.ReadWriteSelfForTeam.All permission, your backend can programmatically install the app into a specific team using the Microsoft Graph API.

Tell Novu where to send the messages

Your customer decides where notifications should land and gives you the right IDs and then your backend registers them as Channel Endpoints in Novu.

There are two supported destination types:

• Channels: Sending a message to a specific channel within a Team.
• Users: Sending a direct message (DM) to a specific user.

Sending message to channels

To send a notification to a specific channel, you need to discover the Team ID and Channel ID from Microsoft, and then register them in Novu.

Find the Team and Channel IDs (Microsoft Graph)

You can discover these IDs using the Microsoft Graph API. This requires an App-Only Token (Client Credentials) scoped to the customer's tenant.

1. Get a Graph access token:

POST https://login.microsoftonline.com/{SUBSCRIBER_TENANT_ID}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
 
client_id={BOT_APP_ID}
&client_secret={BOT_APP_SECRET}
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&grant_type=client_credentials

The SUBSCRIBER_TENANT_ID is the ID of the customer's tenant, which Novu stored on the ChannelConnection object after they completed the Admin Consent flow.

GET /v1/channel-connections
{
  "identifier": "chconn-eeybt4",
  "integrationIdentifier": "msteams",
  "providerId": "msteams",
  "channel": "chat",
  "subscriberId": "689c4a87c5bdaa96aaef0cfd",
  "workspace": {
    "id": "e6633b86-ef94-4416-863f-f0f409700ca0" // this
  },
  "auth": {
    "accessToken": "app-only"
  },
}

2. List teams:

GET https://graph.microsoft.com/v1.0/teams
Authorization: Bearer {ACCESS_TOKEN}

3. List channels in a team:

GET https://graph.microsoft.com/v1.0/teams/{TEAM_ID}/channels
Authorization: Bearer {ACCESS_TOKEN}

Register the channel endpoint (Novu)

Once you have the IDs, create an ms_teams_channel endpoint in Novu. This maps a subscriber to that specific channel.

POST /v1/channel-endpoints
Authorization: ApiKey {CUSTOMER_API_KEY}
Content-Type: application/json
 
{
  "identifier": "msteams-main-notifications",
  "integrationIdentifier": "ms-teams-bot-1",
  "providerId": "msteams",
  "channel": "chat",
 
  "subscriberId": "workspace_abc",
  "connectionIdentifier": "msteams-tenant-subscriberX",
 
  "type": "ms_teams_channel",
  "endpoint": {
    "teamId": "TEAM_ID",
    "channelId": "CHANNEL_ID"
  },
}

Novu stores this as ChannelEndpoint<'ms_teams_channel'>. You can later target it from workflows via subscriberId + context.

Sending direct message to a user

To send a direct message (DM), you need the user's Teams User ID before registering the user endpoint in Novu.

Find the user ID (Bot framework)

You cannot use the Graph API for this. You must use the Bot Framework API to inspect the roster of a team the bot is installed in.

1. Ensure the bot is installed in at least one team that includes the target user(s).
2. Get a Bot Framework token:

   POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded
    
   grant_type=client_credentials&
   client_id={BOT_APP_ID}&
   client_secret={BOT_APP_SECRET}&
   scope=https%3A%2F%2Fapi.botframework.com%2F.default

3. Call the roster API for that team, using the team’s 19:...@thread.tacv2 id as {TEAM_CONVERSATION_ID}:

   GET https://smba.trafficmanager.net/teams/v3/conversations/{TEAM_CONVERSATION_ID}/members
   Authorization: Bearer {BOT_ACCESS_TOKEN}

From the returned members, take the member’s id this is the Teams user ID (29:...) you’ll use as userId.

Register the user endpoint (Novu)

Once you have the IDs, create the endpoint in Novu using the ms_teams_user type.

POST /v1/channel-endpoints
Authorization: ApiKey {CUSTOMER_API_KEY}
Content-Type: application/json
 
{
  "identifier": "msteams-user-alice",
  "integrationIdentifier": "ms-teams-bot-1",
  "providerId": "msteams",
  "channel": "chat",
 
  "subscriberId": "user_123",
  "connectionIdentifier": "msteams-tenant-subscriberX",
 
  "type": "ms_teams_user",
  "endpoint": {
    "userId": "29:1GcS4EyB_oSI8A88XmWB..."
  },
 
  "contextKeys": []
}

Novu stores this as ChannelEndpoint<'ms_teams_user'>. From here, any workflow that resolves to this endpoint will send a DM from your bot to that user.

Workflows for Teams (Webhook-style)

If you do not need a full Bot identity or Direct Message capabilities, you can support a simplified, channel-only integration using Workflows for Microsoft Teams.

This approach relies on a unique Webhook URL generated by the Teams client. It requires no Azure app registration and no admin consent.

User generates the webhook URL (Teams client)

The setup begins inside the Microsoft Teams application. Instruct your users to follow these steps:

1. In Microsoft Teams, go to Apps in the sidebar.
2. Search for and open Workflows.
3. Click Create new flow either from blank or template.
4. Choose a trigger like “When a Teams webhook request is received”.
5. Add an action to post a message into a specific channel.
6. Save the workflow
7. Once created, the workflow generates a unique URL. The user must copy this URL.

Register the webhook endpoint (Novu)

Unlike the Bot integration, you do not use ms_teams_channel here. Instead, you treat this as a generic webhook endpoint. Your application should provide a form where the user can paste the URL they generated in the previous step.

await novu.channelEndpoints.create({
  type: 'webhook',
  identifier: 'teams-workflow-alerts',
  integrationIdentifier: 'ms-teams-workflow',
  subscriberId: 'customer-account-id',
  context: { tenant: 'acme' },
  endpoint: {
    url: 'https://prod-00.westeurope.logic.azure.com:443/workflows/...' // workflow URL
  },
});

Sending the notification

When you trigger a workflow that targets this subscriber:

1. Novu sends a standard HTTP POST payload to the Teams Workflow URL.
2. Workflows for Teams receives the payload.
3. The Workflow executes and posts the message content into the configured channel.