Q1. Does this app require any API permissions to be granted? If so, which ones? What are they used for?
In order to enable a seamless UX for the end users of the Perkbox app for Microsoft Teams (MS Teams), the below listed permissions will need to be granted either by each user or by a Teams Admin on behalf of all users in the organisation. Granting permissions is a prerequisite for the app to function properly.
Reads the users’ primary email address used to sign in to MS Teams
Used for looking up the current user's tenant in Perkbox to enable a seamless login experience for users when they attempt to use the Perkbox app on MS Teams
openid
Sign users to the app using their work/school accounts in order to get their MS token for authorisation purposes
profile
View users’ basic profile such as name, profile picture, username, etc. to customise the messages sent by the bot to the user
user.read
Sign-in users to the app and read basic information about their profile and basic company information, used in the linking process between MS and Perkbox tenant and users
directory.Read.All
Read directory data, like users, in order to dynamically link (without login) the Microsoft user profiles to their corresponding Perkbox profile
channelMessage.Read.All
Read user channel messages in order to sync the team channel replies for a recognition (adaptive card) with the comment section in Perkbox Celebration Hub
ChatMessage.Read
Read user chat messages in order to sync one-to-one and group chat replies for a recognition (adaptive card) with the comment section in Perkbox Celebration Hub
teamsAppInstallation.ReadWriteSelfForChat.All
Allow the app to manage itself in chats when it comes to install, uninstall, update events
teamsAppInstallation.ReadWriteSelfForTeam
Allow the app to manage itself in teams when it comes to install, uninstall, update events
TeamsAppInstallation.ReadWriteSelfForUser.All
teamsAppInstallation.ReadWriteSelfForUser — deprecated in February 2023
Allow the app to manage itself in personal scopes when it comes to install, uninstall, update events for a user
AppCatalog.Read.All
Allows the bot to check if it is available in your organisation’s app catalog and fetches its installation ID
Q2. What can users do with Perkbox for Microsoft Teams?
Users can create recognitions only (not polls) from within Teams
They will also be able to view the recognitions created by their colleagues on MS Teams if they’re part of the conversation or channel where it is created.
Users will be able to reply to a recognition created but only within MS Teams
Q3. How do I review all the API permissions granted to Perkbox for Microsoft Teams?
Simply click here to navigate to the Microsoft Teams Admin Centre. Once you have logged in, simply scroll down to find the section titled “Org-wide permissions” and click on the “Review permissions” button. You may be prompted to login again at this stage. Once done, a popup will appear listing down all the API permissions requested by Perkbox - simply click on the Accept button and that’s it.
In case the link doesn’t work for you, once you have opened the Microsoft Teams Admin Centre, navigate to Teams Apps > Manage apps > Search for Perkbox > Permissions tab > Org-wise permissions.
Q4. How do I install Perkbox for Microsoft Teams?
The Perkbox app can be installed via the AppSource or by clicking on the Apps button in the left hand navigation bar of the MS Teams desktop app. Click on the Add button on the app listing to add the app to your instance of MS Teams. You may be prompted to grant permissions to the app depending on whether or not your IT admin has set the app up for your organisation.
Q5. How and where will these recognitions be created? And where will they appear?
Recognitions created on Teams will appear both on Perkbox platform and on Teams (within the conversation or channel where it was created)
Recognitions created on the platform will appear on the platform only
Comments will be mutually exclusive on either (for v1) - meaning that comments on the recognition on the platform will remain on the platform only and similarly on Teams