Updated documentation

manifest/manifest.json

@@ -0,0 +1,48 @@
+{
+    "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.15/MicrosoftTeams.schema.json",
+    "version": "1.0.0",
+    "manifestVersion": "1.15",
+    "id": "<YOUR-MICROSOFT-APP-ID>",
+    "packageName": "com.teams.openai.bot",
+    "name": {
+        "short": "OpenAI Bot",
+        "full": "OpenAI Bot"
+    },
+    "developer": {
+        "name": "Lee Ford",
+        "mpnId": "",
+        "websiteUrl": "https://www.lee-ford.co.uk",
+        "privacyUrl": "https://www.lee-ford.co.uk",
+        "termsOfUseUrl": "https://www.lee-ford.co.uk"
+    },
+    "description": {
+        "short": "OpenAI Bot",
+        "full": "OpenAI Bot used for talking with OpenAI from Teams"
+    },
+    "icons": {
+        "outline": "outline.png",
+        "color": "color.png"
+    },
+    "accentColor": "#FFFFFF",
+    "bots": [
+        {
+            "botId": "<YOUR-MICROSOFT-APP-ID>",
+            "scopes": [
+                "team",
+                "personal"
+            ],
+            "isNotificationOnly": false,
+            "supportsFiles": false
+        }
+    ],
+    "validDomains": [
+        "token.botframework.com",
+        "online.microsoftlogin.com",
+        "*.ngrok.io"
+    ],
+    "defaultGroupCapability": {
+        "team": "bot",
+        "groupchat": "bot",
+        "meetings": "bot"
+    }
+}

readme.md

@@ -1,26 +1,91 @@
-# Teams OpenAI Bot
+# Teams OpenAI Conversation Bot
+
+## Summary
 
 This is a sample example OpenAI bot for Microsoft Teams. It allows a user in Teams to send a chat message to the Bot, which then uses [OpenAI API](https://beta.openai.com/overview) to get an answer to the chat message.
 
-![Example conversation](https://user-images.githubusercontent.com/472320/210224132-bd475461-6d02-48b6-9824-97151b2cc30a.gif)
+> Please note: Currently there is no publicly available API for OpenAI's [ChatGPT](https://openai.com/blog/chatgpt/). This sample uses the OpenAI API, which models doesn't currently include ChatGPT. The OpenAI API is currently in beta, and is not free. You can sign up for a free account [here](https://beta.openai.com/). For a list of supported models, see [here](https://beta.openai.com/docs/api-reference/models).
+
+![Example conversation](./assets/example-conversation.gif)
 
-> Please note: Currently there is no publicly available API for [ChatGPT](https://openai.com/blog/chatgpt/). This sample uses the OpenAI API, which models don't currently include ChatGPT. The OpenAI API is currently in beta, and is not free. You can sign up for a free account [here](https://beta.openai.com/). For a list of supported models, see [here](https://beta.openai.com/docs/api-reference/models).
+## Frameworks
+
+![drop](https://img.shields.io/badge/Bot Framework-4.18-green.svg)
 
 ## Prerequisites
 
-* You need to have an OpenAI account and API key. You can sign up for a free account [here](https://beta.openai.com/)
+* [OpenAI account](https://beta.openai.com/) and API key
+* [Office 365 tenant](https://dev.office.com/sharepoint/docs/spfx/set-up-your-development-environment)
+* [Node.js](https://nodejs.org) version 14 or higher
+
+    ```bash
+    # determine node version
+    node --version
+    ```
+
+* [Azure Functions Core Tools](https://github.com/Azure/azure-functions-core-tools) version 4 or higher
+
+    ```bash
+    # determine core tools version
+    func --version
+    ```
+
+* [ngrok](https://ngrok.com/) - Although a free account will work with this sample, the tunnel subdomain will change each time you run ngrok, requiring a change to the Azure Bot messaging endpoint and the Teams app manifest. A paid account with a permanent subdomain is recommended.
+
+## Version history
+
+Version|Date|Author|Comments
+-------|----|----|--------
+1.0|Jan 3, 2023|Lee Ford|Initial release
+
+## Disclaimer
 
-## Run locally
+**THIS CODE IS PROVIDED _AS IS_ WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**
 
-1. You need to ensure you have the [Azure Functions Core Tools](https://github.com/Azure/azure-functions-core-tools) installed first.
-2. Create an Ngrok tunnel to your local machine on port 7071 ([download here](https://ngrok.com/download))
-    * `ngrok http 7071`
-    * Copy the HTTPS URL (e.g. `https://12345678.ngrok.io`. (Note: this may change each time you restart ngrok and you will need to update the Azure Bot Registration with the new URL)
-3. [Create a Single Tenant Azure Bot Registration](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration?view=azure-bot-service-4.0&tabs=singletenant) in the [Azure Portal](https://portal.azure.com)
-4. Under `Configuration`, populate the Messaging endpoint with the HTTPS URL with the path of `/api/messages/` from step 2 (e.g. `https://12345678.ngrok.io/api/messages`) and make a note of the `Microsoft App ID` and `Microsoft App Password/Client secret` (you will need these later)
-    ![image](https://user-images.githubusercontent.com/472320/210186162-815859ee-4bd1-4c7a-b1ab-d8637e08b179.png)
-5. Under Channels, add the Microsoft Teams channel and enable messaging
-6. Create a populate a `local.settings.json` file with the following (with your own values):
+---
+
+## Minimal Path to Awesome
+
+### Start ngrok
+
+Start ngrok listening on port 7071 (or whatever port you are running the Azure Function on)
+
+```bash
+ngrok http 7071
+```
+
+If you have a paid account, add the subdomain:
+
+```bash
+# Replace 12345678 with your ngrok subdomain
+ngrok http 7071 -subdomain=12345678
+```
+
+Take a note of the forwarding URL, as you will need it later.
+
+### Create an Azure Bot
+
+1. Go to the [Azure Portal](https://portal.azure.com)
+2. Search for **Azure Bot** and choose **Create**
+3. Populate the bot with the following:
+   * **Bot handle**: A unique bot name (the display name can be changed later)
+   * **Type of App**: Single tenant (in a production scenario, you would be running in Azure and use Managed Identity)
+    ![image](/assets/create-azure-bot.png)
+4. With the bot created, under **Configuration**:
+   * Take a note of the **Microsoft App ID** and **Microsoft App Tenant ID** (you will need these later)
+   * Populate the **Messaging endpoint** with the ngrok forwarding URL (with `/api/messages` appended). Note: if you are not using a paid account, you will need to update this each time you restart ngrok.
+    ![image](/assets/azure-bot-configuration.png)
+   * Click on **Manage Password** and create a **New client secret**. Specify a name and when it expires. Take a copy of the **Secret value** (you will need this later)
+    ![image](/assets/create-client-secret.png)
+    ![image](/assets/copy-client-secret.png)
+    > Note in a production environment, you should be using a Managed Identity to authenticate to the Azure Bot, rather than a client secret.
+5. Under **Channels**, add the **Microsoft Teams** channel and enable messaging
+   ![image](/assets/add-teams-channel.png)
+
+### Run Locally
+
+1. Clone this repository
+2. Create and populate a `local.settings.json` file in the root folder with the following (with your own values):
 
     ```json
     {
@@ -34,17 +99,22 @@ This is a sample example OpenAI bot for Microsoft Teams. It allows a user in Tea
         "MicrosoftAppPassword": "<YOUR MICROSOFT APP REGISTRATION CLIENT SECRET>",
         "MicrosoftAppTenantId": "<YOUR MICROSOFT APP REGISTRATION TENANT ID>",
         "MicrosoftAppType": "SingleTenant"
-    }
+        }
     }
     ```
 
-7. Then, use the following to install, build and run the code (from the root folder):
+3. Run the following to install, build and run the code (from the root folder):
 
     ```bash
     npm install
     npm run build
     func host start
     ```
 
-8. You can at this point choose to create a Teams App Manifest and side-load the app into Teams, or you can use the link on the Azure Portal to test the bot in Teams.
-    ![Open in Teams](https://user-images.githubusercontent.com/472320/210186363-61638c2b-fd48-461c-a1bf-898421687b1a.png)
+### Teams App Manifest
+
+1. Edit the `manifest.json` file and replace the `id` and `botId` values with the **Microsoft App ID** from the Azure Bot
+2. Zip the `manifest` folder into a `manifest.zip` file
+3. Upload the `manifest.zip` file to Teams (side load the or upload in Teams Admin Center)
+
+<img src="https://pnptelemetry.azurewebsites.net/sp-dev-fx-webparts/samples/bot-openai" />