Skip to main content

Microsoft Teams

Microsoft Teams Bot Requirements

To send notifications via Microsoft Teams, a Microsoft Teams Bot is required. You may use an existing or create a new one.

Set Up Chat Using Microsoft Teams

Introduction

This step-by-step guide will walk you through sending a notification to a channel or user on Microsoft Teams using Courier. You will:

Prerequisites

You will need both Courier and Microsoft Teams accounts to complete this tutorial. If you don't have accounts already, sign up before proceeding. You will also need permission to install apps to Teams. Either an administrator can grant you this permission or you can sign up for a free Microsoft 365 developer program tenant.

Create a Microsoft Teams Bot

When building an app for Teams, you'll need to create an app package to be installed. We will be using App Studio to create this package directly from the Teams Client. Install the App Studio App in your Teams client, if you haven't already.

Create a new app

Open App Studio and click Create a new app on the Manifest Editor tab. Fill out all the required fields including the Bot names, descriptions, etc. At the App URLs section, fill out your privacy and Terms of Use web page URLs. In this example, we are just using the placeholder URL, https://example.com. Before you publish your app, you must update these urls to point to real web pages with the required statements. Next, generate an App ID.

App Studio Create App

Configure the bot

From the left menu, select Capabilities > Bots. Then, click Set up to configure a new bot. Fill out the bot name and select the Personal and Team scopes and click Create bot. Now click Generate new password. At the modal popup, copy the password. You'll also need to copy the ID next to your bot name. You will need both these values for the next steps.

App Studio Bot Configuration

Deploy the bot app

Before we can continue configuring and installing your bot, we must first deploy the code so we can create the messaging endpoint. In a browser, open the Microsoft Teams Bot Starter Repo and click the Deploy to Netlify button. You will be prompted for the App ID (Bot ID) and App Password from above along with your Courier Auth Token and a name for the repo. This will clone and deploy a starter Teams bot. Once the site is deployed, copy your site url. We'll need this to finish installing the bot. It should look like the following: https://{site-name}.netlify.app.

Netlify Deploy Input Dialog

Install the bot

We can now return to the bot configuration page and set the Bot endpoint address. Enter your site url with /api/messages at the end. It should look like the following: https://{site-name}.netlify.app/api/messages.

App Studio Bot Configuration

From the left menu, select Finish > Test and distribute. If you get any errors, go fix them, otherwise, click Install. Click the arrow next to Add to add to a team and add to a chat. You will now have access to message your bot in a channel and a direct message.

App Studio Add Dropdown

You can test the installation of your bot using the following commands:

In channel (you must mention your bot):

@YOUR_BOT test

In a direct message:

test

In both cases, the bot should respond with, "Your bot has been successfully added."

Add the Microsoft Teams Integration

Now that we have a working Microsoft Teams bot, we can use the App ID and Password from above to configure the Microsoft Teams Integration in Courier.

Navigate to the Integrations page and click on Microsoft Teams to configure it.

Courier Integrations each require different pieces of information based on the needs of the Integration provider. Using the App ID and Password from above, fill them in and click Install.

Configured Microsoft Teams Integration

Congratulations, you've configured your Integration with Microsoft Teams. Now, let's create a notification.

Create a notification

Navigate to the Courier "Notifications" page and click Create Notification. Click on “Untitled Notification” to rename your notification — for this tutorial, call it “Test Appointment Reminder.” From your list of configured Integrations, click on the Microsoft Teams button.

Notification Channel Selector with Microsoft Teams

Then, click the Microsoft Teams box that has been added to the sidebar in order to bring up a Microsoft Teams template.

Courier provides a visual template editor, so you can send notifications that are formatted professionally. You can add content blocks to the template by clicking appropriate icons. If you remove a content block, it is moved to your Library in the sidebar and can be dragged back to the template if necessary.

These content blocks can include variables using a mustache-like template syntax. Surround text with a single set of curly braces and that text will be interpreted as a variable (it will also be highlighted in green). For example, you may want to include a {name} variable (we'll cover the source of this variable data later in this tutorial).

For now, add a text block and fill it with whatever text you want to send. You can also copy the example below, which contains a few variables for demonstration.

Text
Hello {name},

This is an appointment reminder from Courier. We look forward to seeing you on {apt_date} at {apt_time}.

If you need to change your appointment for any reason, please contact us at least 24 hours in advance at {support_url} or {support_phone}.

Best regards,

Courier
Notification Design View with Block

When you are finished, click Publish Changes in the upper right corner.

Preview the notification using a Test Event

Courier allows you to preview your notifications using different Test Events so you can see how different data will affect the notification. Let's create a Test Event and preview the notification. We'll also use this Test Event when sending the message.

In the Notification Designer, click on the Preview tab at the top of the screen. Click the Create Test Event button. Give the event the name "Tutorial Example" and replace the provided JSON with the following:

JSON
{
"data": {
"name": "Spike Spiegel",
"apt_date": "June 26",
"apt_time": "8:44 PM",
"support_phone": "202-555-0143",
"support_url": "https://courier.com/docs"
},
"profile": {},
"override": {}
}
Notification Test Event Dialog

Click Create Test Event and you'll see a preview of the notification using the provided data for any variables used. Next, we'll use this test event to send the notification using the Send tab.

Send a Message

Courier passes messages to Integrations via the Send endpoint. For this tutorial, we will send our messages using the Send tab in the Notification Designer. It will also provide you with sample code for your preferred language using one of our SDKs.

Click the Send tab at the top of the page.

Notification Send Tab

Send a Direct Message

To send a direct message to a Microsoft Teams user, we'll need a Courier recipient with a Microsoft Teams profile that includes a user_id, tenant_id, and service_url. We can retrieve these values and save them to a profile using our bot's add-user command.

From the direct chat, type the following message:

add-user QUICKSTART_USER
Executed add-user command

The bot will reply with "Your profile has been updated." You can now update the Recipient ID with QUICKSTART_USER and click Send Notification. You should see the notification appear as a direct message from your bot.

Sent Direct Message

Send to a Channel

To send a message to a Microsoft Teams channel, we'll need a Courier recipient with a Microsoft Teams profile that includes a channel_id, tenant_id, and service_url. We can retrieve these values and save them to a profile using our bot's add-channel command.

From the channel your bot has been installed in, type the following message replacing YOUR_BOT with the name of your bot:

@YOUR_BOT add-channel QUICKSTART_CHANNEL
Executed add-channel command

The bot will reply with "Your profile has been updated." You can now update the Recipient ID with QUICKSTART_CHANNEL and click Send Notification. You should see the notification appear as a message from your bot in that channel.

Sent Channel Message

Congratulations, you have successfully sent notifications to a Microsoft Teams user and channel. You are welcome to further develop this starter bot to fit your needs and distribute it to other Microsoft Teams tenants.

Production Bots

The bot we are using works great for this guide, but likely won't fit a production use case. You'll want to update the Activity Handler to cover other events like when the bot is installed within an organizational unit. Check out Event-driven conversations using an activity handler.

Profile Requirements

With Microsoft Teams, Courier can send a message to either Users that are part of a tenant or the Channel.

To locate your tenant_id, you can navigate to https://teams.microsoft.com/?tenantId and copy the value from the redirected url tennantId query parameter.

Send a message to a Microsoft Teams User

To deliver a message to a recipient over Microsoft Teams, Courier must be provided with the ID of the intended recipient, the tenant ID for the Microsoft Teams account that recipient is a user of, and the service URL associated with that Microsoft Teams tenant.

You can use the Microsoft Graph Explorer to query for the user_id. You can learn more by checking out Build Microsoft Teams apps with Microsoft Graph.

JSON
{
"message": {
// Recipient Profile
"to": {
"ms_teams": {
"user_id": "",
"tenant_id": "",
"service_url": "https://smba.trafficmanager.net/amer"
}
}
}
}

Send a message to an Microsoft Teams Channel

To deliver a message to a channel over Microsoft Teams, Courier must be provided with the ID of the channel and the service URL associated with that Microsoft Teams tenant.

To locate the conversation_id open Microsoft Teams in the browser and use the threadId query parameter from the url.

JSON
// Recipient Profile
{
"message": {
"to": {
"ms_teams": {
"conversation_id": "",
"tenant_id": "",
"service_url": "https://smba.trafficmanager.net/amer"
}
}
}
}
info

If you are located in the Americas Region, the service url is https://smba.trafficmanager.net/amer.

Overrides

Overrides can be used to change the App ID and App Password of an Azure Bot. Below is an example of overriding the ID and password:

JSON
{
"message": {
"template": "<COURIER_NOTIFICATION_ID>",
"to": {
"ms_teams": {
"user_id": "a-user-id",
"tenant_id": "a-tenant-id-or-group-id",
"service_url": "https://smba.trafficmanager.net/amer"
}
},
"data": {
"name": "Katherine Pryde"
},
"providers": {
"msteams": {
"override": {
"config": {
"appId": "<App ID>",
"appPassword": "<App Password>"
}
}
}
}
}
}