csharp

page_type	languages	products	description	extensions	urlFragment
sample	csharp	office-teams office office-365	Two samples to highlight solutions to two challenges with building proactive messaging apps in Microsoft Teams	contentType createdDate samples 05/17/2022 01:48:56 AM	officedev-microsoft-teams-samples-bot-proactive-messaging-csharp

Teams Proactive Messaging Samples

Two samples to highlight solutions to two challenges with building proactive messaging apps in Microsoft Teams.

Contents

File/folder	Description
/coordinate-logger	Sample of getting conversation coordinates using BotFramework Events & SDK.
/proactive-cmd	Sample of sending proactive messages with throttling policies.
/teamsAppManifest	App manifest for the teams app.
.gitignore	Define what to ignore at commit time.
CHANGELOG.md	List of changes to the sample.
CONTRIBUTING.md	Guidelines for contributing to the sample.
README.md	This README file.
LICENSE	The license for the sample.

Included Features

• Bots

Interaction with app

Prerequisites

• Microsoft Teams account
• .NET SDK version 6.0
• Publicly addressable https url or tunnel such as dev tunnel or ngrok latest version or Tunnel Relay

Setup

1. Configure public url to point to http port 5000

   ngrok http 5000 --host-header="localhost:5000"

   Alternatively, you can also use the dev tunnels. Please follow Create and host a dev tunnel and host the tunnel with anonymous user access command as shown below:

   devtunnel host -p 5000 --allow-anonymous

2. Create a Microsoft Entra ID app registration and Azure Bot in Azure portal: Azure Bot registration resource.

• Ensure that you've enabled the Teams Channel
• configure the messaging endpoint in Azure bot with your application domain URL and append /api/messages like: https://111xxx.ngrok-free.app/api/messages

3. Modify the manifest.json in the /AppManifest folder and replace the {{BOT-ID}} with the id received while doing Microsoft Entra ID app registration in previous steps and also update the <<App Domain>> with your application domain like ngrok domain: 111xxx.ngrok-free.app or dev tunnels domain: 12345.devtunnels.ms excluding http/https.

4. Zip the contents of AppManifest into a manifest.zip.

5. Modify the /coordinate-logger/appsettings.local.json file and fill in the {{ Bot Id }} and {{ Bot Password }} with the id's received while doing Microsoft Entra ID app registration in previous steps.

Coordinate Logger

Note this is a noisy application, it is recommended you not run this in shared teams where you would disturb other users!

1. Start the application

   # dotnet run

   It is running when the following output is displayed.

   Hosting environment: Development
   Content root path: C:\msteams-samples-proactive-messaging\coordinate-logger
   Now listening on: https://localhost:5001
   Now listening on: http://localhost:5000
   Application started. Press Ctrl+C to shut down.
   

2. Install the app personally in Teams

   • Go to the Apps in the left rail
   • Select Upload a custom app and select the manifest.json file
   • Click the Add Button on the consent screen

   The coordinates of the user should be log in the console window(refer above image)

3. Install the app to a Team

   • Go to the Apps in the left rail
   • Select Upload a custom app and select the manifest.json file
   • Select the down arrow next to the Add Button on the consent screen
   • Select a Team to install to.

   The app will send a message to each channel in the Team & log the coordinates for each new thread to the console window.(refer above image)

Proactive CMD

1. Send a message to a user Using the values from the Coordinate Logger for a User's conversation coordinates & Bot registration fill in the parameters to the following command.

   # dotnet run -- sendUserMessage --app-id="{{Bot Id}}" --app-password="{{Bot Password}}" --service-url="{{ServiceUrl}}" --conversation-id="{{Conversation Id}}" --message="Send Message to a User"

   This will send a message to the 1-on-1 conversation with the user

2. Send a message to a thread Using the values from the Coordinate Logger for a Channel Thread's conversation coordinates & Bot registration fill in the parameters to the following command.

   # dotnet run -- sendChannelThread --app-id="{{Bot Id}}" --app-password="{{Bot Password}}" --service-url="{{ServiceUrl}}" --conversation-id="{{Conversation Id}}" --message="Send Message to a Thread"

   This will send a message to the thread

Running the sample.

User Conversation log info

Channel Conversation log info

Proactive message

Team name in which message will post

Meesages in other Team

Key concepts

The two samples correspond with two of the most common challenges when building proactive messaging apps in Microsoft Teams, getting the conversation coordinates and sending messages reliably.

The CoordinateLoggerActivityHandler.cs file in the Conversation Logger demonstrates three separate ways to obtain or generate conversation coordinates for users or channel threads using the BotBuilder SDK.

The SendWithRetries function and policy from the CreatePolicy function demonstrate how to reliably send messages when dealing with throttling from Microsoft Teams.

Contributing

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.opensource.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., status check, 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.