How do I send Joyous conversations with Microsoft Teams?

Many organizations are moving towards more cohesive internal communication strategies, where employees expect important business communication to come through official platforms such as Microsoft Teams.

Your Joyous campaigns can reach employees where they already spend their time by sending conversations and notifications via Microsoft Teams chat with our notification bot app.

About this integration

The Joyous Teams app is a notification-only bot that can:

• Install itself for Teams users who are part of a campaign audience;
• Send chat messages to Teams users with links to Joyous conversations or notifications;
• Teams users cannot send messages to the Joyous bot - all activity is done in the Joyous platform by clicking on the links.

The Joyous Teams app receives minimal permissions to operate and has no broader access to your Microsoft systems. For more information see the appendix on permissions at the bottom of this page.

Prerequisites

Joyous requires some information about your Microsoft Teams configuration before the app can be installed.

Teams Tenant ID

Joyous needs to match the Tenant ID of your Microsoft Teams instance to your organization in our platform. Find your Tenant ID through the Azure Portal, and send it to your Joyous customer care representative.

The Tenant ID is a non-sensitive piece of public information that is used purely to identify your organization, and does not allow Joyous any access any data in your Microsoft system.

Azure Object ID

Joyous needs to match your people in the Joyous platform to the correct Microsoft Teams users with their Microsoft Azure Object ID. There are 3 ways to achieve this:

• If your organization uses the Joyous Azure Active Directory integration for provisioning people data, then Joyous already has access to the Azure Object ID for your people, and no further action is required;
• If your organization imports people data into Joyous with a CSV file via SFTP, there are two options:
  • Include the Azure Object ID for each person in a column in the CSV file;
  • If it is not practical to automate adding the Azure Object ID to your people data CSV file, you must ensure that the email passed to Joyous in your CSV file is the same as the email used as the UserPrincipalName (UPN) in Microsoft Azure Active Directory. In this case the Joyous Teams app can use the UPN to fetch the Azure Object ID via the Graph API, and match it to a person in the Joyous platform.

Install the Joyous Teams App

1. Request the Teams app manifest from your Joyous customer care representative:
   1. Joyous will send a .zip file containing the app manifest
2. Open the Microsoft Teams admin center
3. Navigate to Teams apps > Manage apps
4. Click + Upload new app
   1. Upload the app manifest .zip from Joyous
5. On the Manage apps page, search for the Joyous app and select it
6. Note down the App ID and send this information to your Joyous representative along with your Tenant ID (see Prerequisites)
7. Navigate to the Permissions tab and click Review permissions
8. Click Accept on the dialog to grant permissions for the Joyous app
   
   1. See the appendix at the bottom of this page for more information on requested permissions.

What happens next?

After you have provided your Tenant ID and the App ID to Joyous, your representative will confirm that the installation has been successful.

When a campaign launches with Microsoft Teams as the sending method, Joyous will automatically install the Teams app for any audience members who don't already have it. Joyous conversations will then be sent by Teams chat to the campaign audience.

Appendix: App Permissions

The Joyous Teams app receives the minimal permissions provided to all bots by the Microsoft Teams Bot Framework SDK, and requests one Application Permission to facilitate the install process. No Delegated or Administrator level permissions are required.

Basic Permissions

The following permissions are granted to all Teams bot apps, but in practice only a few of these are actively used due to the nature of the Joyous Teams app:

Actively used:

• Send messages and notifications to Teams users with the app installed.
• Access basic profile information of Teams users with the app installed, e.g. name, UPN, email address.

Not actively used:

• Receive messages and @-mentions from Teams users with the app installed - not used as the Joyous app is a notification-only bot.
• The following basic permissions are used when an app is added to a Channel or a Group Chat, which is only possible for apps publicly available through the Teams App Store. As the Joyous app can only be installed for individuals, and not in Channels, these permissions are not actively used:
  • Send messages to a channel or group chat
  • Access profile information of group chat or channel members

Application Permissions

In addition, the app requests the following Application Permission to install itself only for Teams users who are part of Joyous campaign audiences. This permission requires Administrator consent to grant, but the app itself does not require any Delegated or Administrator level permissions.

Joyous requires the Azure Object ID or the UPN of a Teams user in order to install the app. As such Joyous can only install the app for users where this information has been provided to Joyous through the people data integration with your organization. Joyous is unable to install the app for any Teams users not present in the people data provisioned to Joyous.

This installation flow is used to ensure that the app is only installed for people at your organization who are in scope for the Joyous platform, and ensures that any new people added to Joyous automatically receive the Teams app without your IT team having to manage that.

This permission does not allow the Joyous app to query the Graph API for any information beyond what basic permissions from the Microsoft Teams Bot Framework SDK enable.