Readme for the bot-proactive-messaging-teamsfx sample has been updated.

samples/bot-proactive-messaging-teamsfx/README.md

@@ -1,100 +1,133 @@
+---
+
+page_type: sample
+description: This sample bot showcases proactive messaging capabilities in Microsoft Teams by storing user conversation references to send scheduled or triggered reminder notifications.
+products:
+- office-teams
+- office
+- office-365
+languages:
+- nodejs
+extensions:
+ contentType: samples
+ createdDate: "10-04-2022 17:00:25"
+urlFragment: officedev-microsoft-teams-samples-bot-proactive-messaging-teamsfx-nodejs
+
+---
+
 # How to use this Proactive message bots app
 
 This sample bot showcases proactive messaging capabilities in Microsoft Teams by storing user conversation references to send scheduled or triggered reminder notifications. The app is designed for local debugging and deployment to Azure, offering full integration with Microsoft 365 Agents Toolkit for streamlined setup and testing.
 
-## Prerequisites
+## Play with the App
 
-- [NodeJS](https://nodejs.org/en/)
-- An M365 account. If you do not have M365 account, apply one from [M365 developer program](https://developer.microsoft.com/en-us/microsoft-365/dev-program)
-- [Microsoft 365 Agents Toolkit Visual Studio Code Extension](https://aka.ms/teams-toolkit) version after 1.55 or [Microsoft 365 Agents Toolkit CLI](https://aka.ms/teams-toolkit-cli)
+This sample provides following functionality:
+
+- You can send any command to bot to get the same message echoed back.
+
+- You can navigate to http://localhost:3978/api/notify to proactively message everyone who has previously messaged this bot.
+
+  ![ShareMessage](./images/send-proactive-messages.gif)
 
 ## Try it yourself - experience the App in your Microsoft Teams client
 Please find below demo manifest which is deployed on Microsoft Azure and you can try it yourself by uploading the app package (.zip file link below) to your teams and/or as a personal app. (Sideloading must be enabled for your tenant, [see steps here](https://docs.microsoft.com/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant#enable-custom-teams-apps-and-turn-on-custom-app-uploading)).
 
 **Proactive message bots app:** [Manifest](/samples/bot-proactive-messaging-teamsfx/demo-manifest/bot-proactive-messaging-teamsfx.zip)
 
-## Debug
+## Prerequisites
 
-- From Visual Studio Code: Start debugging the project by hitting the `F5` key in Visual Studio Code. 
-- Alternatively use the `Run and Debug Activity Panel` in Visual Studio Code and click the `Run and Debug` green arrow button.
-- From Microsoft 365 Agents Toolkit CLI:
-  - Install [dev tunnel cli](https://aka.ms/teamsfx-install-dev-tunnel).
-  - Login with your M365 Account using the command `devtunnel user login`.
-  - Start your local tunnel service by running the command `devtunnel host -p 3978 --protocol http --allow-anonymous`.
-  - In the `env/.env.local` file, fill in the values for `PROVISIONOUTPUT_BOTOUTPUT_VALIDDOMAIN` and `PROVISIONOUTPUT_BOTOUTPUT_SITEENDPOINT` with your dev tunnel URL.
-    ```
-    PROVISIONOUTPUT_BOTOUTPUT_VALIDDOMAIN=sample-id-3978.devtunnels.ms
-    PROVISIONOUTPUT_BOTOUTPUT_SITEENDPOINT=https://sample-id-3978.devtunnels.ms
-    ```
-  - Executing the command `atk provision --env local` in your project directory.
-  - Executing the command `atk deploy --env local` in your project directory.
-  - Executing the command `atk preview --env local --run-command "cd bot; npm run dev:atk"` in your project directory.
+- [NodeJS](https://nodejs.org/en/)
+- An M365 account. If you do not have M365 account, apply one from [M365 developer program](https://developer.microsoft.com/en-us/microsoft-365/dev-program)
+- [Microsoft 365 Agents Toolkit Visual Studio Code Extension](https://aka.ms/teams-toolkit) version after 1.55 or [Microsoft 365 Agents Toolkit CLI](https://aka.ms/teams-toolkit-cli)
 
-**Note**: If deploying or provisioning the sample, please replace line 9 of file `bot/teamsBot.js` with .env.dev. (By default its set to `.env.local`)
 
-## Edit the manifest
+## Run the app (Using Microsoft 365 Agents Toolkit for Visual Studio Code)
 
-You can find the Teams app manifest in `appPackage` folder. The folder contains a manifest template file:
-* `manifest.json`
+The simplest way to run this sample in Teams is to use Microsoft 365 Agents Toolkit for Visual Studio Code.
 
-Both files contain template arguments with `{...}` statements which will be replaced at build time. You can hover the prepoerties to see the actual value or preview the manifest. You may add any extra properties or permissions you require to this file. See the [schema reference](https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) for more information.
+1. Ensure you have downloaded and installed [Visual Studio Code](https://code.visualstudio.com/docs/setup/setup-overview)
+1. Install the [Microsoft 365 Agents Toolkit extension](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension)
+1. Select **File > Open Folder** in VS Code and choose this samples directory from the repo
+1. Using the extension, sign in with your Microsoft 365 account where you have permissions to upload custom apps
+1. Select **Debug > Start Debugging** or **F5** to run the app in a Teams web client.
+1. In the browser that launches, select the **Add** button to install the app to Teams.
 
-**Note**: If you are facing any issue in your app, please uncomment [this](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-proactive-messaging-teamsfx/bot/index.js#L28) line and put your debugger for local debug.
+> If you do not have permission to upload custom apps (uploading), Microsoft 365 Agents Toolkit will recommend creating and using a Microsoft 365 Developer Program account - a free program to get your own dev environment sandbox that includes Teams.
 
-> Important Notes! This sample is under upgrading, please expect errors if you attempted to provision and deploy the app to cloud.
-> Once the sample complete upgrading, this notice will be removed. And the sample will be ready to be deployed to cloud by then.
-> Before that, please debug and run this sample app locally!
-> 
-## Deploy to Azure
+## Run the app (Manually Uploading to Teams)
 
-Deploy your project to Azure by following these steps:
+> Note these instructions are for running the sample on your local machine, the tunnelling solution is required because
+the Teams service needs to call into the bot.
 
-| From Visual Studio Code                                                                                                                                                                                                                                                                                                                                                  | From Microsoft 365 Agents Toolkit CLI                                                                                                                                                                                                                    |
-| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <ul><li>Open Microsoft 365 Agents Toolkit, and sign into Azure by clicking the `Sign in to Azure` under the `ACCOUNTS` section from sidebar.</li> <li>After you signed in, select a subscription under your account.</li><li>Open the Microsoft 365 Agents Toolkit and click `Provision` from LIFECYCLE section or open the command palette and select: `Microsoft 365 Agents:Provision`.</li><li>Open the Microsoft 365 Agents Toolkit and click `Deploy` or open the command palette and select: `Microsoft 365 Agents:Deploy`.</li></ul> | <ul> <li>Run command `atk auth login azure`.</li> <li>Run command ` auth set --subscription <your-subscription-id>`.</li> <li> Run command `atk provision`.</li> <li>Run command: `atk deploy`. </li></ul> |
+1) Run ngrok - point to port 3978
 
-> Note: Provisioning and deployment may incur charges to your Azure Subscription.
+   ```bash
+   ngrok http 3978 --host-header="localhost:3978"
+   ```  
 
-## Preview
+   Alternatively, you can also use the `dev tunnels`. Please follow [Create and host a dev tunnel](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started?tabs=windows) and host the tunnel with anonymous user access command as shown below:
 
-Once the provisioning and deployment steps are finished, you can preview your app:
+   ```bash
+   devtunnel host -p 3978 --allow-anonymous
+   ```
 
-- From Visual Studio Code
+## Setup for bot
+In Azure portal, create a [Azure Bot resource](https://docs.microsoft.com/azure/bot-service/bot-service-quickstart-registration).
+    - For bot handle, make up a name.
+    - Select "Use existing app registration" (Create the app registration in Microsoft Entra ID beforehand.)
+    - __*If you don't have an Azure account*__ create an [Azure free account here](https://azure.microsoft.com/free/)
+
+   In the new Azure Bot resource in the Portal, 
+    - Ensure that you've [enabled the Teams Channel](https://learn.microsoft.com/azure/bot-service/channel-connect-teams?view=azure-bot-service-4.0)
+    - In Settings/Configuration/Messaging endpoint, enter the current `https` URL you were given by running the tunneling application. Append with the path `/api/messages`
 
-  1. Open the `Run and Debug Activity Panel`.
-  1. Select `Launch Remote (Edge)` or `Launch Remote (Chrome)` from the launch configuration drop-down.
-  1. Press the Play (green arrow) button to launch your app - now running remotely from Azure.
+## Setup for code
+1) Clone the repository
 
-- From Microsoft 365 Agents Toolkit CLI: execute `atk preview --env dev` in your project directory to launch your application.
+    ```bash
+    git clone https://github.com/OfficeDev/Microsoft-Teams-Samples.git
+    ```
 
-## Validate manifest file
+1) In a terminal, navigate to `samples/bot-proactive-messaging-teamsfx/nodejs`
 
-To check that your manifest file is valid:
+1) Install modules
 
-- From Visual Studio Code: open the command palette and select: `Microsoft 365 Agents:Validate Application`, then select `validate app manifest schema` option.
-- From Microsoft 365 Agents Toolkit CLI: run command ` validate` in your project directory.
+    ```bash
+    npm install
+    ```
 
-## Package
+1) Run your bot at the command line:
 
-- From Visual Studio Code: open the Microsoft 365 Agents Toolkit and click `Zip App Package` or open the command palette and select `Microsoft 365 Agents:Zip App Package`.
-- Alternatively, from the command line run ` package` in the project directory.
+    ```bash
+    npm start
+    ```
+    It will start at port 3978.
 
-## Publish to Teams
+1) __*This step is specific to Teams.*__
+    - **Edit** the `manifest.json` contained in the  `appManifest` folder to replace your Microsoft App Id (that was created when you registered your bot earlier) *everywhere* you see the place holder string `<<YOUR-MICROSOFT-APP-ID>>` (depending on the scenario the Microsoft App Id may occur multiple times in the `manifest.json`)
+    - **Edit** the `manifest.json` for `validDomains` with base Url domain. E.g. if you are using ngrok it would be `https://1234.ngrok-free.app` then your domain-name will be `1234.ngrok-free.app` and if you are using dev tunnels then your domain will be like: `12345.devtunnels.ms`.
+    - **Zip** up the contents of the `appManifest` folder to create a `manifest.zip` (Make sure that zip file does not contains any subfolder otherwise you will get error while uploading your .zip package)
+    - **Upload** the `manifest.zip` to Teams (In Teams Apps/Manage your apps click "Upload an app". Browse to and Open the .zip file. At the next dialog, click the Add button.)
+    - Add the app in personal/groupchat/team scope (supported scopes)
 
-Once deployed, you may want to distribute your application to your organization's internal app store in Teams. Your app will be submitted for admin approval.
+**Note**: If you are facing any issue in your app, please uncomment [this](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-message-reaction/nodejs/index.js#L48) line and put your debugger for local debug.
 
-- From Visual Studio Code: open the Microsoft 365 Agents Toolkit and click `Publish to Teams` or open the command palette and select: `Microsoft 365 Agents:Publish to Teams`.
-- From Microsoft 365 Agents Toolkit CLI: run command ` publish` in your project directory.
+## Running the sample
 
-## Play with the App
+Message the bot and it will respond with a proactive hello.  Add a message reaction to the bots response, and the bot will reply accordingly.
 
-This sample provides following functionality:
+- **App Installation:**
 
-- You can send any command to bot to get the same message echoed back.
+![App Installation ](images/1.Install.png)
 
-- You can navigate to http://localhost:3978/api/notify to proactively message everyone who has previously messaged this bot.
+- **Personal Scope Interactions:**
 
-  ![ShareMessage](./images/send-proactive-messages.gif)
+![personalScope-AddApp ](images/2.PersonalChat.png)
+
+
+## Deploy the bot to Azure
+
+To learn more about deploying a bot to Azure, see [Deploy your bot to Azure](https://aka.ms/azuredeployment) for a complete list of deployment instructions.
 
 
 ## Further reading