How to Integrate Microsoft Teams with Preppio
Pre-requirements:
Administrator access for MS Teams and Microsoft Azure is required for the person doing the installation.
1. Go to dev.teams.microsoft.com and log in. Here you will create an app and a bot that is associated with it. First we start with creating the bot.
Select the Tools section on the left and then bot management (see the below image).
2. Add a bot and name it something that you think is appropriate for your organization and its users to interact with.
3. Let's configure your new bot with the following endpoint address: https://preppapp.com/api/messages
4. While in this section, we also need to create a client secret key for the bot. Please make sure you copy this key somewhere as we will need it later. This is referred to the app secret value and is required later during configuration in Preppio application (described later in this guide). Copy & paste the key somewhere for later reference.
We are done with creating our bot. We need to create an app so let's go back to where we started and the Apps section:
5. Now please select to create a + New app from the top of this screen.
6. Lets start configuring it after we have named it.
Provide the appropriate naming and description of your own choice. You can use the following information from Preppio in the following sections on this screen:
We repeat them here for you to easily copy and paste the information onto the page:
Developer information: Preppio
Website: https://preppio.com
Privacy policy: https://preppio.com/privacy-cookie
Terms of Use: https://preppio.com/tos
For Application Client Id, you will need to log into Azure Portal and look for the bot name you created under the app registration section (see the below image). You will need to copy this application client id value and paste it into the above-referenced section. Make sure you save this step before continuing.
Once finished with the above section. Save and continue to the branding section.
7. Feel free to add the icons in appropriate sizes/resolutions for your app here. We will skip this section to keep this guide short.
8. App features: select the Bot feature to be added to this application.
Select an existing bot which should be the bot we created as the first step in this guide. Also, select and enable the feature for uploading and downloading files.
Next, you will need to add a command by selecting the below:
Make sure all the three boxes above are checked. Add and Save your changes.
9. Select the language you would like your app to support. Add to the default one which is the English language.
10. In the domain section, please add the following domains: *.prepp.io and *.preppio.com
11. Let's package the application for deployment. Please go ahead and download the package:
12. You then need to go to https://admin.teams.microsoft.com/ and upload the app to your organization app catalog.
Go to the manage app section and select upload. Upload the package you created in the previous step and you should see your custom app available in the manage app list.
Select the app you uploaded to see its details page.
Make a copy of the App id (referred to as application catalog id in the Preppio application just to distinguish between this app id and the client app id from Azure). We need this app id for installing the bot in the Preppio application.
13. Head over to the Azure portal. We need to get a few settings from the Azure portal in order to complete the installation. After log-in, search for App registration.
Select the application (in this example called Onboard Me).
Make sure you copy the application id (different from the previous one above) and the tenant id somewhere so that we can refer to them later when doing the installation.
14. Go to the Api permission section to start granting API permissions to the application. This is needed in order for the app to get hold of groups/teams and members of the Team's information, in addition, to installing the app for each user so that we can send proactive messages.
Select add permissions and on the right-hand side select Microsoft Graph.
then select Application permissions.
Search and add the following permissions:
15. Important! Click on the “Grant admin consent”. You need to then reload the page (the refresh button here may not always work). You should then see the below with a green checkmark beside each permission requested.
Now you are all set here :)
16. Head over to the Preppio application and the settings section. Select your bot and add a channel -> Microsoft Teams channel. Add the following credentials created during the setup:
On the next screen add the Microsoft Team/Group you want the integration installed in. This is an important step as the integration will be able to extract groups/teams member information. Please make sure you add the integration to the group(s) that has all employees within your organization. This will enable the solution to reach and message those employees when required during the onboarding journeys.
That's it, you did it 🎉🎉🎉
Now you need to let the syncing and importing of members take place. This could take up to a few hours based on the number of members inside the team/group being imported.
Troubleshooting tips:
First of all, great work 🙌 If you made it so far you should be all set. We know that there are several steps to go through and that a single miss configuration can create an issue. in particular, we would like to point out the following based on our experience troubleshooting this for customers:
- Please make sure you do not skip step #3 as the endpoint registration is required.
- Please make sure you add the commands described in step #8 above. This is required in order to register webhook information when interacting with the bot - pressing buttons during a dialogue.
- Please make sure you copy the correct application key from step #12 above. Over time, Microsoft has been changing the name/reference to this key, and recently it has more attributes displayed on the app details page in your organization's app store. The key is referred to as App Id, but since we also have an App Id (client id) value which is required, we refer to this App Id attribute as Application catalog id inside Preppio application (keys entry section - step 16).
- If you are for some reason removing the integration and are trying to re-add it again, please give it some time before re-adding it as the clean-up process could take up to 10 minutes.