Skip to content

Latest commit

 

History

History

csharp

README.md

page_type languages products description extensions urlFragment
sample
csharp
office-teams
office
office-365
This sample provides solutions for proactive messaging in Teams, including user and channel coordinate logging and message throttling.
contentType createdDate
samples
05/17/2022 01:48:56 AM
officedev-microsoft-teams-samples-bot-proactive-messaging-csharp

Teams Proactive Messaging Samples

This sample showcases two approaches for building proactive messaging apps in Microsoft Teams using C#. The Coordinate Logger solution captures user and channel conversation coordinates, while the Proactive CMD solution demonstrates how to send messages with policies that handle throttling, ensuring reliable delivery.

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

Broadcast from user

Prerequisites

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

  1. 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.

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

  3. 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 Conversation details

Channel Conversation log info Conversation details

Proactive message Proactive message

Team name in which message will post Proactive message

Meesages in other Team Proactive message

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.