Microsoft Teams

This is a step-by-step guide to integrating and sending notifications to users on Microsoft Teams.

Prerequisites

To send notifications on Microsoft Teams, you'll need to create a Teams bot. This bot will be responsible for sending notifications to users / channels in their Teams workspace. You'll also need a Microsoft 365 developer account and permission to add apps to your teams. You can ask your admin to assign you relevant permission, or you can sign up for a free Microsoft 365 developer program.

• Signup for a Microsoft 365 developer program
• Create a Teams App - Refer section for app creation steps.
  
  

Overview

In this documentation, we'll create an app to send direct messages to users or Team channels. Here's an overview of the steps required to integrate and notify on Microsoft teams:

1. Create Teams App - You'll use this app and configure bot to send direct messages to a user or teams channel.
2. Add teams bot configuration on SuprSend platform - SuprSend will use this configuration to route notifications via your Teams bot to the respective teams workspace.

By following the above steps, your Teams integration will be setup. The next steps will be to

3. Update user or channel profile to send message
4. Create Microsoft Teams template and trigger workflow

Step 1: Create Teams App

You'll have to create a Teams App to send notifications via SuprSend. User will have to add this App in their Teams workspace and channel to start getting notifications through the App. You can learn more about Apps here.

To create the App:

1. First, create a Microsoft 365 Developer Account. Sign in If you have an existing developer account. You'll need permission to add Apps in your account. Ask your admin to assign you relevant permissions if you are using an existing account.
2. Now, navigate to the Apps section and click on +New App.

3. Give your App a suitable name and Add. For your test app, you can use something like "SuprSend Test App" for app name

4. You'll be redirected to a new window where you'll have to add a few information related to your application such as company name, description, website link, URLs to register the App.

5. Now select App feature from your left panel to click on Bot.
6. If you have an existing bot, select it from the list or click on Create a new bot

Creating a new bot

On the bot page, click on +New Bot and add bot name. Add a relevant bot name and Add.

Once the bot is created, you'll land on bot configuration page. Leave the endpoint blank, select "Microsoft teams" in the channel and create client secret for your bot. Save your bot secret somewhere safe. You'll need this in SuprSend vendor integration form.

7. Now login to Azure portal and select All Apps. Here, you'll see the recently created bot. Click on it and copy the App (client) ID. You'll need to fill this information in SuprSend vendor integration form.

8. Navigate to Authentication from the left panel and select Accounts in any organizational directoryand save.

9. Now that your bot is created, go back to your developer portal -> Apps and select your last created App. Select App features -> bot. In the bot configuration, add your recently created bot.

10. Choose Only send notifications in "what can your bot do?". Add personal, team and group chat in bot scopes and click on Save.

11. In your App permissions, add below permission.

12. Publish your App to make it available for use. Publish to org if you want your App to be accessible only inside your organization teams. Publish to store if you want to make it publically available in the teams App store.

13. Your admin will have to approve the App for it to go live. For admin approval, go to admin portal and publish it again. Your App might take some time to go live once it is published.
14. Add client ID that you copied from azure portal into your App Basic Information:

15. Now go to https://teams.microsoft.com/ and ADD the app . First, from left panel select Apps with a + sign and then In the section "Built for this organization", there will be an option to Add the app.

Step 2: Add Teams integration on SuprSend

Go to SuprSend dashboard -> Microsoft teams Vendor Settings page. Add Application (client) ID and client secret (in Password field) generated while creating bot in the above step.

Step 3: Update teams channel in user profile

The information required in the user profile is dependent on the type of message you are sending.

Sending a direct message

To send a direct message to a user, add tenant_id , service_url of the tenant, and conversation_id or user_id corresponding to user personal chat.

You can pass this information in a json format using user.add_ms_teams method as below:

distinct_id = "__uniq_user_id__"  # Unique identifier of user in your application
# Instantiate User profile
user = supr_client.user.get_instance(distinct_id=distinct_id)

# using conversation_id
user.add_ms_teams(
  {
		"tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
		"service_url": "https://smba.trafficmanager.net/amer",
		"conversation_id": "19:c1524d7c-a06f-456f-8abe-xxxx"
  })

# using user_id
user.add_ms_teams(
  {
		"tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
		"service_url": "https://smba.trafficmanager.net/amer",
		"user_id": "29:1nsLcmJ2RKtYH6Cxxxx-xxxx"
  })

response = user.save()
print(response)

const distinct_id = "__uniq_user_id__"  // Unique id of user in your application
const user = supr_client.user.get_instance(distinct_id) // Instantiate User profile

// using conversation_id
user.add_ms_teams(
  {
		"tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
		"service_url": "https://smba.trafficmanager.net/amer",
		"conversation_id": "19:c1524d7c-a06f-456f-8abe-xxxx"
  })

//using user_id
user.add_ms_teams(
  {
		"tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
		"service_url": "https://smba.trafficmanager.net/amer",
		"user_id": "29:1nsLcmJ2RKtYH6Cxxxx-xxxx"
  })

const response = user.save()
response.then((res) => console.log("response", res));

Getting tenant ID, user ID, conversation ID

You'll get tenant ID from your developer azure portal.

You'll get conversation_id from the URL of the chat.

You can get user_id by following the steps to fetch the roster or user profile. You'll need authentication token to fetch user profile. You can get this token from SuprSend vendor page after saving the form.

Sending to a channel

To send a message to a public or private channel, you’ll need to pass tenant_id , service_url of the tenant, and conversation_id of the teams chat channel.

🚧

Please note that you'll have to add App in your teams channel to send notification otherwise it will fail.

To add App to your teams channel, click on + icon to add a tab. In Add a tab modal, click on "More Apps".

You'll see your App in your organization. Click on the App and Add to the team.

We recommend creating a separate user for identifying channels and not mix it in user profile. You can create a teams channel user with distinct_id as channel_<channel_name> so it's easy for you to remember and pass in your workflow calls whenever you want to send message on a teams channel.

Refer below example to add teams channel

distinct_id = "channel_general"  # Unique identifier of user in your application
# Instantiate User profile
user = supr_client.user.get_instance(distinct_id=distinct_id)

user.add_ms_teams(
  {
		"tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
		"service_url": "https://smba.trafficmanager.net/amer",
		"conversation_id": "19:c1524d7c-a06f-456f-8abe-xxxx"
  })

response = user.save()
print(response)

const distinct_id = "channel_general"  // Unique id of user in your application
const user = supr_client.user.get_instance(distinct_id) // Instantiate User profile

user.add_ms_teams(
  {
		"tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
		"service_url": "https://smba.trafficmanager.net/amer",
		"conversation_id": "19:c1524d7c-a06f-456f-8abe-xxxx"
  })

const response = user.save()
response.then((res) => console.log("response", res));

Sending message using incoming webhook

To send a direct message using incoming webhook, just pass the webhook URL in user profile. You can pass this information in a json format using user.add_ms_teams method as below:

distinct_id = "__uniq_user_id__"  # Unique identifier of user in your application
# Instantiate User profile
user = supr_client.user.get_instance(distinct_id=distinct_id)

user.add_ms_teams(
  {
    "incoming_webhook": {
      "url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
    }
  })

response = user.save()
print(response)

const distinct_id = "__uniq_user_id__"  // Unique id of user in your application
const user = supr_client.user.get_instance(distinct_id) // Instantiate User profile

user.add_ms_teams(
  {
    "incoming_webhook": {
      "url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
    }
  })

const response = user.save()
response.then((res) => console.log("response", res));

🚧

Avoid using incoming webhook configuration in the case of a multi-tenant architecture where same set of users may belong to multiple tenants and you want to send notifications via tenant vendor. The incoming webhook is not tied exclusively to the app configuration used for sending notifications and will invariably be dispatched to all incoming webhooks included in the user profile, regardless of the tenant's vendor configuration.

Get Incoming webhook for a teams channel

To get incoming webhook, select connectors from channel -> more options.

Configure Incoming webhook in connectors. Click on create and copy the webhook URL

Order of Precedence

Microsoft teams profile should only contain incoming_webhook->url, or the bot configurations like tenant_id, conversation_id and serive_url . If there are multiple keys in user.add_ms_teams() call, the order of precedence is as follows:

incoming_webhook->url > conversation_id > user_id. For example, if your add_ms_teams argument is as follows:

distinct_id = "__uniq_user_id__"  # Unique identifier of user in your application
# Instantiate User profile
user = supr_client.user.get_instance(distinct_id=distinct_id)

user.add_ms_teams(
  {
    "incoming_webhook": {
      "url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
    },
		"tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
		"service_url": "https://smba.trafficmanager.net/amer",
		"conversation_id": "19:c1524d7c-a06f-456f-8abe-xxxx",
    "user_id":"29:1nsLcmJ2RKtYH6Cxxxx-xxxx"
  })

response = user.save()
print(response)

const distinct_id = "__uniq_user_id__"  // Unique id of user in your application
const user = supr_client.user.get_instance(distinct_id) // Instantiate User profile

user.add_ms_teams(
  {
    "incoming_webhook": {
      "url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
    },
		"tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
		"service_url": "https://smba.trafficmanager.net/amer",
		"conversation_id": "19:c1524d7c-a06f-456f-8abe-xxxx",
    "user_id":"29:1nsLcmJ2RKtYH6Cxxxx-xxxx"
  })

const response = user.save()
response.then((res) => console.log("response", res));

The profile will be saved as {"incoming_webhook": { "url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"}}

Step 4: Create Teams template

Refer teams template documentation for step-by-step guide on how to create, preview and publish the template.

Tenancy in Microsoft teams

In scenarios where you're sending notifications on behalf of your enterprise clients, each with their own team applications for communicating with end-users, you can define distinct app configurations at the tenant level. In SuprSend, we presently identify tenants as brands.

To support this, simply include the app configuration for the brand on the vendor details page. This will override the default brand vendor at the time of sending notification. This configuration needs to be set up once, and SuprSend will seamlessly direct all notifications associated with that brand through the vendor configuration specified for the brand.

In case you don't have vendor defined for a tenant, notifications will automatically fallback to the default vendor credentials.

Refer Steps to configure brand level vendor here