Skip to content

Latest commit

 

History

History
 
 

samples

README.md

Samples

In this folder you will find various examples showcasing the different capabilities of the JS Teams AI Library. Click on the sample folder to see set up and testing instructions. To learn more about all the different samples supported see the getting started.

Appendix

Multiple ways to test a sample

It is recommended to use the Teams Toolkit for Visual Studio Code way to test a sample. However, there are other ways possible as well.

The easiest and fastest way to get up and running is with Teams Toolkit as your development guide. To use Teams Toolkit to automate setup and debugging, please continue below.

Otherwise, if you only want to run the bot locally and build manually, please jump to the BotFramework Emulator section.

Using Teams Toolkit for Visual Studio Code

The simplest way to run this sample in Teams is to use Teams Toolkit for Visual Studio Code.

  1. Ensure you have downloaded and installed Visual Studio Code
  2. Install the Teams Toolkit extension
  3. Select File > Open Folder in VS Code and choose this sample's directory from the repo
  4. Using the extension, sign in with your Microsoft 365 account where you have permissions to upload custom apps
  5. Update the .env file and provide your OpenAI Key key for leveraging GPT
  6. Select Debug > Start Debugging or F5 to run the app in a Teams web client.
  7. In the browser that launches, select the Add button to install the app to Teams.

If you do not have permission to upload custom apps (sideloading), Teams 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.

Using Teams Toolkit CLI

You can also use the Teams Toolkit CLI to run this sample.

  1. Install the CLI

    npm install -g @microsoft/teamsfx-cli

  2. Open a second shell instance and run ngrok tunneling service - point to port 3978

    ngrok http --host-header=rewrite 3978

  3. Copy the ngrok URL and put the URL and domain in the /env/env.local file

    BOT_ENDPOINT=https://{ngrok-url}.ngrok.io
BOT_DOMAIN={ngrok-url}.ngrok.io

  4. Update the .env file and provide your OpenAI Key key for leveraging GPT

  5. In the repository directory, run the Teams Toolkit CLI commands to automate the setup needed for the app

    cd teams-ai/js/samples/<sample-directory>/
teamsfx provision --env local

  6. Next, use the CLI to validate and create an app package

    teamsfx deploy --env local

  7. Finally, use the CLI to preview the app in Teams

    teamsfx preview --env local

Manually upload the app to a Teams desktop client

If you used Teams Toolkit in the above steps, you can upload a custom app to a desktop client using the /appPackage/appPackage.local.zip file created by the tools and skip to step 6.

  1. In a terminal, navigate to teams-ai/js/samples/<sample-directory>/

    cd teams-ai/js/samples/<sample-directory>

  2. Run ngrok tunneling service - point to port 3978

    ngrok http --host-header=rewrite 3978

  3. Create Bot Framework registration resource in Azure

    • Use the current https URL you were given by running ngrok. Append with the path /api/messages used by this sample.
    • Ensure that you've enabled the Teams Channel

  4. Update the .env configuration for the bot to use the Microsoft App Id and App Password from the Bot Framework registration. (Note the App Password is referred to as the "client secret" in the Azure Portal and you can always create a new client secret anytime.)

  5. Update the .env file and provide your OpenAI Key key for leveraging GPT

  6. This step is specific to Teams.

    • Edit the manifest.json contained in the appPackage folder to replace your Microsoft App Id (that was created when you registered your bot earlier) everywhere you see the place holder string ${{TEAMS_APP_ID}} (depending on the scenario the Microsoft App Id may occur multiple times in the manifest.json). If you haven't created an Azure app service yet, you can use your bot id for the above. You're bot id should be pasted in where you see ${{BOT_ID}}. Replace everywhere you see ${{BOT_DOMAIN}} with the domain part of the URL created by your tunneling solution.
    • Zip up the contents of the appPackage folder to create a manifest.zip

  7. Run your app from the command line:

    yarn start

  8. Upload the app file (manifest.zip created in the previous step) in Teams.

Testing in BotFramework Emulator

Bot Framework Emulator Allows testing bots independently from Channels when developing your bot. If you do not wish to use Teams Toolkit, please follow the steps below to test your bot in Emulator.

Directions
  1. Download and install Bot Framework Emulator
  2. Launch Bot Framework Emulator
  3. Run the app you are in the directory for.
yarn start
  1. Add your app's messaging endpoint to the "Open a Bot" dialog. The endpoint your localhost endpoint with the path /api/messages appended. It should look something like this: http://localhost:3978/api/messages.

Bot Framework setup menu with a localhost url endpoint added under Bot URL

  • In order to test remote apps, you will need to use a tunneling service like ngrok along with an Microsoft App Id and password pasted into the dialog shown above.
  • Channel-specific features (For example, Teams Message Extensions) are not supported in Emulator and therefore not fully-testable.
  • If you are building, testing and publishing your app manually to Azure, you will need to put your credentials in the .env file.

Deploy the bot to Azure

You can use Teams Toolkit for VS Code or CLI to host the bot in Azure. The sample includes Bicep templates in the /infra directory which are used by the tools to create resources in Azure.

To configure the Azure resources to have an environment variable for the OpenAI Key:

  1. Add a ./env/.env.staging.user file with a new variable, SECRET_OPENAI_KEY= and paste your OpenAI Key.

The SECRET_ prefix is a convention used by Teams Toolkit to mask the value in any logging output and is optional.

  1. (optional) If you want to use Linux Web app to host your bot, there are some changes you need to make.

    2.1. Update Bicep templates.

    @description('The Runtime stack of current web app')
param linuxFxVersion string = 'NODE|18-lts'

// Compute resources for your Web App
resource serverfarm 'Microsoft.Web/serverfarms@2021-02-01' = {
  kind: 'linux'
  location: location
  name: serverfarmsName
  sku: {
    name: webAppSKU
  }
  properties: {
    reserved: true // This indicates it's a Linux app service plan
  }
}

// Web App that hosts your bot
resource webApp 'Microsoft.Web/sites@2021-02-01' = {
  kind: 'app'
  ...
  linuxFxVersion: linuxFxVersion
  ...
}

    2.2. Change the start command in package.json. (Note: Only for deployment to Azure; remember to change it back if you are doing local debugging.)

    "scripts": {
    ...
    "postinstall": "tsc --build",
    "start": "node ./lib/index.js",
    ...
}

Use the Provision, Deploy, and Publish buttons of the Teams Toolkit extension or from the CLI with teamsfx provision and teamsfx deploy. Visit the documentation for more info on hosting your app in Azure with Teams Toolkit.

Alternatively, you can learn more about deploying a bot to Azure manually in the Deploy your bot to Azure documentation.

Further reading