js

Preparing your app (applies to all samples)

To build the packages and samples do the following from the root js directory:

yarn install
yarn build

Running from root directory is required to ensure all packages are built, since currently there is no package deployment of the SDK.

To then run a sample:

cd into the sample directory to see more instructions.

1. Follow the Teams Toolkit setup instructions.
   • Teams Toolkit is fast and easy to get setup and testing within minutes.
   • Alternatively, you can use Bot Emulator to test locally.
   • See the sample directions or below.

Multiple ways to test

The easiest and fastest way to get up and running is with Teams Toolkit as your development guide. To use Teams Toolkit to continue 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. Select Debug > Start Debugging or F5 to run the app in a Teams web client.
6. 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. In the repository directory, run the Teams Toolkit CLI commands to automate the setup needed for the app

   cd teams-ai/js/samples/01.messaging.a.echobot/
   teamsfx provision --env local
   

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

   teamsfx deploy --env local

6. 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/01.messaging.a.echobot/

   cd teams-ai/js/samples/01.messaging.a.echobot/

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

6. Run your app from the command line:

   yarn start

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

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

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