​
Create and Configure a Microsoft Teams App

1

Step 1: Create a Microsoft Teams App

  1. Open the Microsoft Teams Developer Portal.
  2. In the sidebar, navigate to Apps.
  3. Click New app.
  4. Enter a name for your app and click Add.

We recommend adding -app to your app name to differentiate it clearly from your bot, especially if you manage multiple bots or apps.

  1. Save your App ID and App Password—you’ll need these later.
  2. Navigate to Configure > Basic Information.
  3. Complete the required fields (e.g., App ID, App Name).
  4. Click Save.
2

Step 2: Add Bot Functionality to the App

To send notifications via Courier, your Microsoft Teams app requires a bot. You can use an existing bot or create a new one.

  1. In the sidebar of the Microsoft Teams Developer Portal, select Configure > App Features.
  2. Click Bot to add bot functionality.
  3. If you already have a bot, select it and skip to step 9. Otherwise, click Create a new bot to open the Bot Management Tool.
  4. In the Bot Management Tool, click + New Bot and provide a unique name.

Use a distinct name for your bot to avoid confusion with your app.

  1. Select your bot in the Bot Management Tool.
  2. Under Client Secrets, create and securely store a new client secret.
  3. Return to the Microsoft Teams Developer Portal and select your app.
  4. In Configure > App Features, click Bot again.
  5. Select your bot from the dropdown.
  6. Configure bot scopes:
    • Under What can your bot do?, select:
      • ✓ Only send notifications (one-way conversations)
    • Under Select the scopes where people can use your bot, select:
      • ✓ Personal (for 1:1 notifications)
      • ✓ Team (for channel notifications)
      • ✓ Group Chat (for group chat notifications)
  7. Click Save.
3

Step 3: Install the App in Teams

After configuring your app and bot, install the app in Microsoft Teams. There are two primary ways to install:

For direct 1:1 notifications, users must either:

  • Start a chat with the bot.
  • Be @mentioned by the bot in a channel where it’s installed.
  • Have the app pre-installed by an admin for individual use.

Clicking Add alone makes the app available but does not install the bot across teams or chats. Always use the dropdown menu to specify the correct installation context, typically choosing Add to a Team for notifications.

Ensure you save your generated password securely. Keep the Messaging endpoint blank for now.

4

Step 4: Configure Microsoft Teams Integration in Courier

Now that your Microsoft Teams app is ready, configure it in Courier:

In Courier, navigate to Integrations > Microsoft Teams. Enter your Bot ID and Bot Password, then click Install Provider.

Courier’s integration requires the Bot ID and Bot Password. You can find your Bot ID at:

Congratulations! You’ve successfully created a Microsoft Teams Bot and configured it in Courier. You can now send notifications to Microsoft Teams channels and users.

​
Courier → Recipient Flowchart

​
Profile Requirements

To send notifications to Microsoft Teams, Courier requires the recipient’s user profile to include an ms_teams object. This object must contain the following fields:

  • tenant_id: Your Microsoft Teams tenant ID.
  • service_url: The service URL for your region (e.g., https://smba.trafficmanager.net/amer).
  • One of the following identifiers:
    • user_id
    • email
    • conversation_id
    • Combination of team_id and channel_name
{
  "message": {
    "to": {
      "ms_teams": {
        "user_id": "<user_id>",
        "tenant_id": "<tenant_id>",
        "service_url": "https://smba.trafficmanager.net/amer"
      }
    }
  }
}

To find your tenant_id, navigate to https://teams.microsoft.com/?tenantId and copy the tenantId query parameter from the redirected URL. If the parameter isn’t visible, click the three-dot menu next to your Team, select Get link to team, and locate the tenantId in the URL.

For users in the Americas region, the standard service URL is https://smba.trafficmanager.net/amer.

To send messages using either email or channel_name, your bot must have the following Microsoft Graph API permissions:

  • ChannelSettings.Read.All (requires admin consent)
  • TeamSettings.Read.All (requires admin consent)
  • User.Read.All

These permissions allow Courier to resolve the user_id or channel_id using the Microsoft Graph API.

​
Overrides

Overrides allow you to change the Azure Bot’s App ID and App Password directly within your Courier message payload:

{
  "message": {
    [...],
    "providers": {
      "msteams": {
        "override": {
          "config": {
            "appId": "<App ID>",
            "appPassword": "<App Password>"
          }
        }
      }
    }
  }
}

​
Adaptive Cards

Courier supports Microsoft Teams Adaptive Cards through Jsonnet blocks within the Template Designer. Adaptive Cards let you create interactive, visually appealing notifications for your users in Microsoft Teams.

​
Using Jsonnet Blocks

Jsonnet blocks enable you to customize the appearance and functionality of Adaptive Cards sent through Microsoft Teams. Follow the steps below to create and send your first Adaptive Card:

  1. In Courier’s Template Designer, add a new Microsoft Teams channel.
  2. Insert a Jsonnet block within your message.

Jsonnet Block

  1. Open the Adaptive Cards Designer and select or create a card layout.
  2. Copy the card JSON from the “Card Payload Editor” into your Courier Jsonnet block.

Sample Jsonnet

​
Sending an Adaptive Card

When sending your Adaptive Card, ensure your Courier message includes the necessary sample data from the Adaptive Cards Designer:

{
  "message": {
    "to": {
      "user_id": "QUICKSTART_USER"
    },
    "template": "TGAV18XGBAM565JHKFZY3SJYZB52",
    "data": {
      "title": "Publish Adaptive Card Schema",
      "description": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
      "creator": {
        "name": "Matt Hidinger",
        "profileImage": "https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg"
      },
      "createdUtc": "2017-02-14T06:08:39Z",
      "viewUrl": "https://adaptivecards.io",
      "properties": [
        {"key": "Board", "value": "Adaptive Cards"},
        {"key": "List", "value": "Backlog"},
        {"key": "Assigned to", "value": "Matt Hidinger"},
        {"key": "Due date", "value": "Not set"}
      ]
    }
  }
}

Ensure your recipient profile includes a valid ms_teams object with the appropriate fields (e.g., conversation_id). Once sent, your Adaptive Card will appear in Microsoft Teams:

MS Teams Adaptive Card

Congratulations, you’ve successfully sent an Adaptive Card through Courier!

​
Using @Mentions in Adaptive Cards

To include mentions in Adaptive Cards, you’ll need two key elements:

  • <at>username</at> within the Jsonnet block.
  • A corresponding entities object within the Adaptive Card JSON payload, including the Teams user ID of the mentioned individual.

Here’s a sample mention:

{
  "msteams": {
    "entities": [
      {
        "type": "mention",
        "text": "<at>John Doe</at>",
        "mentioned": {
          "id": "29:123124124124",
          "name": "John Doe"
        }
      }
    ]
  }
}

Now you’re ready to enhance your Microsoft Teams notifications with interactive Adaptive Cards and mentions.