page_type | languages | products | description |
---|---|---|---|
sample | csharp | office-teams | Water Cooler is a custom Teams app that enables corporate teams to create, invite, and join casual conversations among teammates, like those that take place by the Water Cooler or break room. |
Water Cooler is a custom Teams app that enables corporate teams to create, invite, and join casual conversations among teammates, like those that take place by the Water Cooler or break room. Use this template for multiple scenarios, such as new non-project related announcements, topics of interest, current events, or conversations about hobbies.
The app provides an easy interface for anyone to find an existing conversation or start a new one. It's a foundation for building custom targeted communication capabilities, promoting interaction amongst coworkers who may otherwise not get a chance to socialize during breaks.
Water Cooler Welcome Tour: Welcome tour gives a brief introduction about the Water cooler app and helps the users on how to create the rooms or join existing rooms.
Water Cooler Home Page: Browse existing rooms where team members are interacting in existing conversations with certain people or topics of interest. Active conversations on the Home Page will show a room name, short description, call duration, and room image.
Join room: Active conversations will show a Join button to allow visitors to immediately enter an ongoing conversation.
Room creation: Easily create rooms by specifying the room name, short description, up to 5 colleagues as an initial group and selecting from the provided set of room images. Room creation will create a Teams call/chat for all attendees to interact.
Find room: Use the find room feature to search keyword which will match the topic or short descriptions of ongoing conversations.
App badge: Like other Teams apps, the Water Cooler icon on the left menu will show a badge with the number of active conversations visible from Teams while using any app.
The Water Cooler app has the following main components:
The app service implements two main concepts, Endpoints for displaying the calls and a scheduler job for updating the participant info.
The end point will return all the active rooms by checking the azure storage tables. The azure storage tables will provide all active rooms. By utilizing the graph API, we will get the active participants in the call and return it data back to the UI. All these methods will be implemented using parallel async calls.
The scheduler will run for specified time and update database with the following things. It will loop through all the active calls and get the desired information from graph and based on the database records it will update or insert the records. E.g.: Currently there are 4 active users in the room. When the scheduler runs for the first time it will insert all 4 records. In next scheduler event we have a new participant in the call it will check for the change and as the new user is there it will insert the data. If any other user dropped off it will update the meeting end time for the user.
The UI will fetch all the rooms and participants from the above-mentioned API and display the tiles information. The tile will have the Room name, description, participants list and a button to join the call. If the user is part of the call the join button will be displayed. Apart from that the first will be fixed and it will have the create new room button. Click on the button to open the dialog box with Room Name, Description and Participants list. After saving the Room a new call will be initiated. Bot will join the call and it will call other users who are invited initially. The UI application will continuously the poll the API to get the latest rooms information.
App service requires the following Delegated Permission:
Delegated Permission | Use Case |
---|---|
User.Read | In order to read the profile information of the logged in user. |
App service requires the following Application Permissions:
Application Permission | Use Case |
---|---|
Calls.AccessMedia.All | In order to access media streams in a call as an app. |
Calls.Initaite.All | Initiate 1 to 1 outgoing call from app. |
Calls.InitiaateGroupCall.All | Initiate outgoing group calls from the app. |
Calls.JoinGroupCall.All | Join group calls and meetings as an app. |
OnlineMeetings.Read.All | Read online meeting details. |
OnlineMeetings.ReadWrite.All | Read and create online meetings. |
People.Read.All | Read all users relevant peoples list. |
User.Read.All | Read all users profile. |
Deployment of the Water Cooler app will take approx. 90 minutes, assuming all pre-requisites are in place.
Please make sure you are ready with the following list:
Register Azure AD application: Register an Azure AD application in your tenant's directory for Water Cooler app.
Click New registration to create an Azure AD application.
Leave the "Redirect URI"
field blank for now.
When the app is registered, you'll be taken to the app's "Overview" page.
Verify that the "Supported account types" is set to Multiple organizations.
On the side rail in the Manage section, navigate to the "Certificates & secrets" section.
Click "Add".
Once the client secret is created, copy its Value; we will need it later. At this point you should have the following 3 values.
We recommend that you copy the values, we will need them later.
Deploy your Azure subscription
Click on the Deploy to Azure button below.
Azure will create a "Custom deployment" based on the Water Cooler ARM template and ask you to fill in the template parameters.
IMPORTANT NOTE: Please ensure that you don't use underscore (_) or space in any of the field values otherwise the deployment may fail.
Select a subscription and a resource group.
The resource group location MUST be in a datacenter that supports all the following:
For an up-to-date list of datacenters that support the above, click here
Update the following fields in the template:
not taken
otherwise, the deployment will fail with a Conflict error)not taken
otherwise, the deployment will fail with a Conflict error) not taken
otherwise, the deployment will fail with a Conflict error) - write this down as you'll need it later. Note: Make sure that the values are copied as-is, with no extra spaces. The template checks that GUIDs are exactly 36 characters.
Note: Please use single tenant for deployment, app registration and installing the app in Teams.
If deployment fails, Go to the deployed App sevice -> Deployment Center -> Logs. Then Sync to redeploy.
Once successfully deployed, get the URL value from the Web API App Service that has been provisioned. Copy that value to clipboard for use next (and later).
Go to: Home -> Bot Services -> Your Bot -> Channels -> Microsoft Teams (edit) -> Calling tab -> Tick ‘Enable Calling’ -> create Webhook like example here: https://yourappserviceurl.azurewebsites.net/callback/calling
Click Save
Click on Bot Profile
Update Bot icon, name and description
Set-up Authentication
Web
https://%AppServiceUrl%/
auth-end for the URL e.g. https://yourappserviceurl/auth-end
(app service)Back under Manage, click on Expose an API.
Click on the Set link next to Application ID URI, and change the value to api://%AppServiceURL%/%ClientId%
, this is the same URL you used in the previous step (but with api not https) see below:
e.g. api://youappserviceurl.azurewebsites.net/your-registered-app-id
.
Click Save to commit your changes.
Click on Add a scope, under Scopes defined by this API. In the flyout that appears, enter the following values:
access_as_user
Click Add scope to commit your changes.
Click Add a client application, under Authorized client applications. In the flyout that appears, enter the following values:
5e3ce6c0-2b1f-4285-8d4b-75ee78787346
(<- Has to be this)access_as_user
. (There should only be 1 scope in this list.)Click Add application to commit your changes.
Repeat the previous two steps, but with client ID = 1fec8e78-bce4-4aaf-ab1b-5451cc387264
. After this step you should have two client applications (5e3ce6c0-2b1f-4285-8d4b-75ee78787346
and 1fec8e78-bce4-4aaf-ab1b-5451cc387264
) listed under Authorized client applications.
Add Permissions to your App
Continuing from the Azure AD app registration page where we ended Step 3.
In Microsoft APIs under Select an API label, select the service and give the following permissions,
Click on Add Permissions to commit your changes.
https://login.microsoftonline.com/common/adminconsent?client_id=%appId%
. Replace the %appId%
with the Application (client) ID of Microsoft Teams Water Cooler bot app (from above).Give policy access to admin user
Click on command shell icon on header
Update-Module MicrosoftTeams
(To use updated module)Write below commands to run and provide appropriate details
$userCredential
= Get-Credential$userCredential
%clientId%
-Description "Water cooler app - Online meeting policy for admin -Tenant"Grant-CsApplicationAccessPolicy -PolicyName OnlineMeeting-WaterCooler -Identity %adminUserId%
Create the Teams app package
Now everything is deployed in Azure, we need to package up the Teams App and add it into Teams!
MenifestVersion = 1.5
Version = 1.0.0
id
= Client ID
developer.name
= Microsoft (What's this?) developer.websiteUrl
developer.privacyUrl
developer.termsOfUseUrl
(This should be the same Terms of use URL used in step 4 ->15-> 2)
[Note: These 3 URLs should be different]Water Cooler
”,Water Cooler
”waterCooler
",Water Cooler
",https://yourappserviceurl.azurewebsites.net/
,"https://yourappserviceurl.azurewebsites.net/
",<<clientId>>
placeholder in the id setting of the webApplicationInfo section to be the %clientId%
value. Change the <<appDomain>>
placeholder in the resource setting of the webApplicationInfo section to be the %appDomain%
value e.g. api://appname.azurewebsites.net/clientId
.Create a ZIP package with the manifest.json, color.png, and outline.png. The two image files are the icons for your app in Teams.
manifest.zip
, so you know that this is the app for the Water Cooler.Make sure that the 3 files are the top level of the ZIP package, with no nested folders.
Install app in Microsoft Teams
Upload room icons to blob storage
Click on upload and upload the icons for room as shown below.
Proactive app installation will work only if you upload the app to your tenant's app catalog. Install the app (the manifest.zip package) to the users and teams that will be the target audience.
Update app service application settings.
Go to resource group provided for deployment.
Open deployed API app service.
Go to Configuration from left tray.
Click on Advance edit.
Update following property values.
AzureAd:ApplicationIdURI : api://yourapiappservice.azurewebsites.net/<<clientId>>
Add properties mentioned below.
TermsOfUseText
(Terms of use Text to be shown in welcome card) TermsOfUseUrl
(Link to be redirected when clicked on terms of use text)__WEBSITE_NODE_DEFAULT_VERSION__ should be 14.16.0
Save the configuration settings.
Sync the deployment.
Click on sync.
Update app services link in registered App.
Go to Expose an API.
Update Application ID URI
api://yourapiappservice.azurewebsites.net/<<ClientId>>
Save the changes.
Go to Authentication.
Update redirect WEB URIs
https://yourapiappservice.azurewebsites.net/auth-end
Save the changes.
Delete your UI App service. We don’t need it anymore.
Create the Teams app package (Follow Deployment process step 6 above)
If deployment fails, Go to the deployed App service -> Deployment centre -> Logs. Then Sync to redeploy.
If Sync fails then We recommend to deploy on P1v2, P2v2, P3v2 (Premium V2 service plans) and after deploying successfully change the plan to S1.
Thoughts? Questions? Ideas? Share them with us on Teams UserVoice!
Please report bugs and other code issues here.
This app template is provided under the MIT License terms. In addition to these terms, by using this app template you agree to the following:
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.