Microsoft Teams integration for RandomCoffee
This documentation aims to understand in detail how the integration between RandomCoffee and Microsoft Teams works and lists the different technical processes used to operate and maintain it.
This Documentation also refers to external protocols including those of Microsoft Teams which are not elaborated by RandomCoffee and may be updated over time.
If you have any questions or need more detailed information in connection with a contract implementation, do not hesitate to contact our support team (support@random-coffee.com)
Setting up the integration
Prerequisites
Existing program
The Microsoft Teams integration works by associating a RandomCoffee program to one or several Microsoft Teams team(s).
We recommend to have at least one existing program already created in your RandomCoffee workspace before setting up the Microsoft Teams integration.
Permissions
To complete the installation process, you will need to be authorized to add/remove external apps to your Microsoft teams workspace.
Before starting, make sure you have the appropriate permissions (depending on your organization's policy) or get supported by your IT colleagues during the process.
Installing the RandomCoffee app
Once the prerequisites are checked, you can add the app to a team by following these steps.
Step 1: Go to the "Settings" section in the "configuration" tab -> select the Microsoft Teams integration
-> click on the Install button:
Step 2: You should be redirected to Microsoft Teams, then select "Add to a team"
Step 3: The RandomCoffee app needs to be installed in a team. Select your desired team and click "Set up"
Step 4: Select the RandomCoffee program to associate:
If you select an existing running program, this will reset its communication templates to make it compatible with Microsoft Teams cards. Don't forget to adapt your message templates once the installation is complete!
Step 5: Well done! Your program is successfully associated to the team. The RandomCoffee bot will send a confirmation card to the team:
Step 6: Click “complete setup” (or go to your RandomCoffee workspace) to finish setting up your program by choosing your matching rules, personalizing your message, and scheduling upcoming sessions.
In your RandomCoffee workspace, the associated program should automatically appear as configured to "Microsoft teams"
Note that you can add several MS Teams Teams in 1 program.
Managing your participants
Members synchronization
As mentioned upper, the Microsoft Teams integration works by associating a RandomCoffee program to one or several Microsoft Teams team(s).
When a program is configured for Microsoft Teams and associated with a team, its default audience is: all people that are part of the team.
This means that:
Everyone in the team will receive proposals from RandomCoffee
People who join a team where RandomCoffee is running will automatically be added to the RandomCoffee sessions and will receive proposals.
People who leave the team will automatically stop receiving propositions from RandomCoffee
Edge case: people with a guest status in your teams are not included into randomcoffees as they are not considered by organization members by Microsoft.
Check this article for more details
✨ Pro tip
You can take advantage of this mechanics above to facilitate your internal communication. For example, by creating a Team dedicated to RandomCoffee and inviting your members to join it to participate automatically.
User experience on Microsoft Teams
Team public tab
Associating a RandomCoffee program to a team automatically creates a public tab in the team. Every member of the team can access essential information about the program and its activity, such as:
The context and the goal of the program (perfect for new joiners!)
The schedule of the program with upcoming sessions
The overall participation chart across time
The Top Randomers of the program
Team communications
Once the RandomCoffee app is installed in a team, The RandomCoffee bot posts a welcome message in the general channel in order to introduce RandomCoffee to all team members:
Also, when a program is associated to a team, the bot posts an announcement to all users:
Receiving opt-ins and matches cards
The RandomCoffee bot sends opt-in cards and matching card to every user through private chat message.
For opt-ins, users have the choice to accept or not the proposition to get matched in the current session. Here is an example of an opt-in card:
Users who have accepted to be matched receive a matching card in a secondary time (according to the schedule you defined) where they discover their match:
Multiple actions are possible from the matching card:
Schedule your meetup - to generate a native Microsoft/Outlook meeting with your match
Start a chat - opens a direct chat with your match
Start a call - launches a video call with your match
Chatting with the bot
Users can directly interact & chat with the RandomCoffee bot and access several prompts:
Help - Explains what RandomCoffee does and provides help support
Feedback - allows to send a message to the RandomCoffee team
Snooze - allows to temporary pause your participation for a defined time:
Personal space
In addition to all interactions and cards, every user can access his RandomCoffee personal tab. The interface consists in 3 main tabs:
My activity
Users can find all their RandomCoffee actions in this section, such as participating to a session, getting matched with someone new or being informed of upcoming/past sessions.
My network
Users can view their matching history to remember all people matched through RandomCoffee with context. They can also restart a chat or book a new coffee meeting with a previous match.
My programs
Users can find a centralized view of all RandomCoffee programs they are involved in (from all teams) and retrieve the context of each program.
Technical factors
Single Sign-On (SSO)
SSO and Authentication
RandomCoffee integrates a discret SSO authentication protocol when installing the RandomCoffee app on a Microsoft Teams team.
The RandomCoffee member who has a RandomCoffee account is automatically recognized by his email and linked to his Microsoft Teams account. This is called a "discreet" authentication protocol in that this step is invisible to the user.
Use cases for enabling discreet SSO
This allows the user, when adding the RandomCoffee application to a team, to synchronize and display data from his RandomCoffee account (such as existing programs already created) in his Microsoft Teams's teams.
Users who are not recognized for any reason are requested to sign up and create a RandomCoffee account before continuing.
SSO app-users experience:
Teams gets the access token for the current app user from Microsoft Entra ID. This interaction with Microsoft Entra ID is invisible to the app user. It translates to get the app access without having to leave the Teams environment.
An app user needs to consent only in a multitenant environment. If the app user and the app reside in the same tenant, the app user doesn't need to give consent for using the app.
After consenting to Teams the first time, the app user can use your app with no further need of consent, even on any other device. For this reason, it offers a better user experience.
Alternatively, the tenant administrator can grant consent on behalf of the app users. In this scenario, when the tenant administrator consents for the app users in the tenant, the app users don't need to be prompted for consent at all. It means that the app users don't see the consent dialogs and can access the app seamlessly.
The access token is pre-fetched by Teams to improve performance and load time of the app in the Teams environment.
The app users don't need to memorize or record several passwords to access and use apps in Teams environment.
SSO interactions at runtime
The following image shows how SSO works when a Teams app user attempts to access the tab app.
1
Tab app → Teams Client
The tab app makes a JavaScript call to getAuthToken(), which tells Teams to obtain an access token.
2
Teams Client → Microsoft Entra ID
Teams requests Microsoft Entra endpoint for the access token for the current app user based on Teams identity.
3
Microsoft Entra ID → Consent form
If the current app user is using your tab app for the first time, Teams displays request prompt to consent, if the app needs to access some protected data. The app user (or the administrator) must give consent to Teams for using the app user's Teams identity to obtain access token from Microsoft Entra ID. Alternately, there's a request prompt to handle step-up authentication such as two-factor authentication.
4
Microsoft Entra ID → Teams Client
Microsoft Entra ID sends the access token to the Teams Client. The token is a JSON Web Token (JWT), and its validation works just like token validation in most standard OAuth flows. Teams caches the token on your behalf so that future calls to getAuthToken() return the cached token.
5
Teams Client → Tab app client
Teams sends the access token to the tab app as part of the result object returned by the getAuthToken() call.
6
Tab app (between client and server)
The tab app parses the access token using JavaScript to extract required information, such as the app user's email address. The token returned to the tab app is both an access token and an identity token.
You can refer to this Microsoft Documentation article to know more about SSO practices and details:
User provisioning
Once the RandomCoffee bot is installed on your Team, the app automatically retrieves the list of all teams members using the MS Teams REST API.
The RandomCoffee bot accesses basic but essential information as the first name, last name, and email address of each team member.
App permissions
The RandomCoffee Application is authorized to call MS Teams REST APIs when it is granted permissions by users/admins as part of the consent process. Here is the list of configured permissions needed by RandomCoffee app :
email
offline_access
openid
profile
User.Read
FAQ
Last updated
