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.

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.

Creat a Microsoft 365 Account

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.

Navigate to Apps

Now, navigate to the Apps section and click on +New App.

Add a name and other details

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

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.

Add Bot

Now select App feature from your left panel to click on Bot. If you have an existing bot, select it from the list or click on Create 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.

Get started with the Azure Portal

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.

Navigate to Authentication from the left panel

After navigating, select Accounts in any organizational directoryand save.

Add your Recently Created Bot

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.

Add specific info about your bot, and add some permissions

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

In your App permissions, add below permission.

Section	Permissions
Team Permissions -> Application	`Channel.Create.Group`, `Channel.Delete.Group`, `ChannelMessage.Read.Group`, `ChannelMessage.Send.Group`, `TeamsActivity.Send.Group`
Chat/Meeting Permissions -> Application	`ChatMessage.Read.Chat`, `ChatMessage.Send.Chat`
User Permissions -> Application	`TeamsActivity.Send.User`

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.

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.

Add the Client ID

Add client ID that you copied from azure portal into your App Basic Information:

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.

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.

Update teams channel in user or object 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)

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.

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)

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)

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)

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

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 tenants.

To support this, simply include the app configuration for the tenant on the vendor details page. This will override the default tenant 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 tenant through the vendor configuration specified for the tenant.

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

Refer Steps to configure tenant level vendor here

GETTING STARTED

CORE CONCEPTS

WORKFLOW BUILDER

SUPRSEND BACKEND SDK

SUPRSEND CLIENT SDK

Notification Inbox

PREFERENCE CENTRE

VENDOR INTEGRATION GUIDE

INTEGRATIONS

MONITORING & DEBUGGING

MANAGE YOUR ACCOUNT

Prerequisites

Create Teams App

Add Teams integration on SuprSend

Update teams channel in user or object profile

Order of Precedence

Create Teams template

Tenancy in Microsoft teams

GETTING STARTED

CORE CONCEPTS

WORKFLOW BUILDER

SUPRSEND BACKEND SDK

SUPRSEND CLIENT SDK

Notification Inbox

PREFERENCE CENTRE

VENDOR INTEGRATION GUIDE

INTEGRATIONS

MONITORING & DEBUGGING

MANAGE YOUR ACCOUNT

​Prerequisites

​Create Teams App

​Add Teams integration on SuprSend

​Update teams channel in user or object profile

​Order of Precedence

​Create Teams template

​Tenancy in Microsoft teams

Prerequisites

Create Teams App

Add Teams integration on SuprSend

Update teams channel in user or object profile

Order of Precedence

Create Teams template

Tenancy in Microsoft teams