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 ([e-mail])

---

Setting up the integration

Prerequisites

Existing program

The Microsoft Teams integration works by associating a RandomCoffee program to a Microsoft Teams team.

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"

---

Managing your participants

Members synchronization

As mentioned upper, the Microsoft Teams integration works by associating a RandomCoffee program to a Microsoft Teams team.

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.

#	Interaction	What's going on
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:

Overview to authentication for tabs using SSO in Teams with Microsoft Entra ID - TeamsMicrosoftLearn

---

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

Can MS Teams integration and HRIS integration work together?

Yes, you can combine the MS Teams integration with the HRIS integration to enrich your users' data not present in MS Teams to create powerful and accurate matchmaking rules.

In this case, users provisioned by MS Teams who are also present in your HRIS are automatically recognized with their email address and are automatically enriched with data from your HRIS.