By following this tutorial, you will learn how Teams Toolkit helps simplify and accelerate your Microsoft Teams app development by building a bot that obtains data from an external API and sends a rich message using an Adaptive Card into Microsoft Teams on a pre-defined schedule.<\/p>\n
<\/p>\n <\/p>\n To follow this guide successfully, you will need an account that has access to a Microsoft 365 tenant,\u00a0which has been configured for developing Microsoft Teams apps<\/a>, have Visual Studio Code<\/a> and the current LTS version (v16) of nodejs<\/a> installed.<\/p>\n If you do not have a tenant, I highly recommend that you use a\nMicrosoft 365 Developer Tenant, which you can obtain for free by\njoining the Microsoft 365 Developer Program<\/a>.<\/p>\n With the pre-requisites done, let\u2019s begin!<\/p>\n <\/p>\n Our first step is to install Teams Toolkit into Visual Studio Code, you can do this several ways, however the easiest is way is to search for and install the extension using the Extensions panel from the Side Bar within Visual Studio Code.<\/p>\n Once the extension has been successfully installed, you will see a Microsoft Teams icon in the Side Bar.<\/p>\n Congratulations, you have successfully installed Teams Toolkit for Visual Studio Code and are now ready to create your first Microsoft Teams app! \ud83c\udf89<\/p>\n <\/p>\n After installing the extension, let\u2019s create a new project.<\/p>\n When the project scaffolding is complete, Teams Toolkit will re-open Visual Studio code in the project folder and open a Readme file for the project.<\/p>\n Feel free to look through the Readme file to understand the base project functionality and structure.<\/p>\n Congratulations, you have successfully created your first project with Teams Toolkit that contains a Notification Bot! \ud83c\udf89<\/p>\n <\/p>\n When creating a new project using Teams Toolkit, the next step is to ensure that you have authenticated Teams Toolkit to your Microsoft 365 tenant.<\/p>\n After successfully authenticating with your Microsoft 365 tenant, you will see that your account name is now showing in the Account section of the Teams Toolkit extension and an indication of the current Sideloading status in your tenant will also be displayed.<\/p>\n Congratulations, you have successfully connected Teams Toolkit with your Microsoft 365 tenant! \ud83c\udf89<\/p>\n <\/p>\n As our notification bot will use Adaptive Cards to represent our stock price update, let\u2019s update the adaptive card design to fit our needs.<\/p>\n Open the notification-default.json<\/em> file in the bot\/src\/adaptiveCards<\/em> directory and replace the contents with the following JSON.<\/p>\n We are using Adaptive Cards Template Language here to provide separation between our data and layout.<\/p>\n Using binding expressions i.e., ${name}, we can add placeholders to our layout in locations where we want our data to be rendered.<\/p>\n Let\u2019s create an interface to represent the data object to use with the template.<\/p>\n Open the cardModels.ts<\/em> file in the bot\/src<\/em> directory and replace the contents with the following.<\/p>\n When we combine our template and data using the Adaptive Cards SDK, the notification will look something like this.<\/p>\n Congratulations, you have successfully created an Adaptive Card which will represent our stock update notification! \ud83c\udf89<\/p>\n <\/p>\n When providing an update, our bot will need to obtain the latest stock price, to do this we will create an API connection to the Alpha Vantage API.<\/p>\n After completing the wizard, a new folder is created in the bot\/src<\/em> directory called apiConnections<\/em>, inside it a new file called alphaVantage.ts<\/em> is generated which contains the logic to create an authenticated API client.<\/p>\n To complete the setup, we must provide a value to pass in the apikey<\/em> query string parameter.<\/p>\n Open the .env.teamsfx.local <\/em>file in the bot<\/em> directory and update the environment variable TEAMSFX_API_ALPHAVANTAGE_API_KEY<\/em> to TEAMSFX_API_ALPHAVANTAGE_API_KEY=demo<\/em><\/p>\n Congratulations, you have successfully created an API connection to an external API using API Key authentication! \ud83c\udf89<\/p>\n \u00a0<\/em><\/p>\n Let\u2019s update the logic in the bot.<\/p>\n Open the timerTrigger.ts<\/em> file, this file contains the core logic of our bot that will be executed on a schedule. For now, remove the contents of the entire file, so we can work from a blank slate.<\/p>\n First, let\u2019s include the imports for the dependant global modules.<\/p>\n Let\u2019s cover what these dependencies are.<\/p>\n Next, lets add our local dependencies.<\/p>\n Let\u2019s cover what these dependencies are.<\/p>\n Now that we have our dependencies in place, lets implement the Azure Function trigger logic.<\/p>\n Whilst this is a lot to unpack, the general flow of the function is<\/p>\n Next, we will implement the functions that this handler uses.<\/p>\n Add these after the timerTrigger<\/em> function but before the export<\/em> statement.<\/p>\n The following functions, getTimestamp<\/em> and makeValidAdaptiveCardISOString,<\/em> are used to return a valid time stamp that can be used in an Adaptive Card.<\/p>\n The following functions, getQuoteBySymbol<\/em> and getResponseData<\/em>, are used to send a request to the Alpha Vantage API and obtain the response data from the API client.<\/p>\n The following functions, extractGlobalQuote<\/em>, transformGlobalQuote<\/em>, removePercent, addTimestamp<\/em> and addCompanyName<\/em>, are used to manipulate the API response data and convert it into a GlobalQuote<\/em> object which we can use with our Adaptive Card.<\/p>\n The following function, getInstallations<\/em>, is used to return an array of locations where the bot is installed.<\/p>\n The following function, sendCard<\/em>, is used to send an Adaptive Card to a bot installation location, this is also where the card template and quote data is merged.<\/p>\n Finally, the following function, handleError<\/em>, is used as a basic error handler, logging out any errors using the Azure Function context log.<\/p>\n Congratulations, you have successfully updated the bot to request data from an external API and render an Adaptive Card in the locations where the bot is installed! \ud83c\udf89<\/p>\n <\/p>\n Now it is time to see our bot in action!<\/p>\n Open the Debug<\/em> panel from the Side Bar, select your browser of choice from the drop-down menu and start the bot by pressing the F5 key.<\/p>\n Now, sit back, relax and watch the magic of Teams Toolkit in action \ud83e\ude84<\/p>\n When you start the bot Teams Toolkit will perform several checks of your environment, ensuring that all the required dependencies are installed.<\/p>\n In addition to the above checks, Teams Toolkit is also registering a bot with Bot Framework and updating the app manifest for you.<\/p>\n Once all the checks have been passed, Teams Toolkit will launch a browser session, you may be prompted to sign in with your account the first time you launch your bot, if so, complete the sign in flow.<\/p>\n After signing into Microsoft 365, the web version of Microsoft Teams is opened and a prompt to sideload your app will be shown. Click the Add button to install the bot as a personal app.<\/p>\n Wait a few seconds for your bot to be executed, sending a message into Microsoft Teams with the latest stock price.<\/p>\n Congratulations, you have just created your first notification bot using Microsoft Teams Toolkit \ud83c\udf89<\/p>\n <\/p>\n Want to make more updates? Here are a few things you can try.<\/p>\n <\/p>\n Happy coding!<\/p>\n","protected":false},"excerpt":{"rendered":" Learn how Microsoft Teams Toolkit helps simplify and accelerate your Microsoft Teams app development by building a bot that obtains data from an external API and sends a rich message using an Adaptive Card into Microsoft Teams.<\/p>\n","protected":false},"author":100385,"featured_media":11540,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[8,128],"tags":[23,55,44],"class_list":["post-11467","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-adaptive-cards","category-microsoft-teams","tag-teams-toolkit","tag-visual-studio","tag-visual-studio-code"],"acf":[],"blog_post_summary":" Learn how Microsoft Teams Toolkit helps simplify and accelerate your Microsoft Teams app development by building a bot that obtains data from an external API and sends a rich message using an Adaptive Card into Microsoft Teams.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/11467","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/100385"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=11467"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/11467\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/11540"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=11467"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=11467"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=11467"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}![\"A](\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/09\/stocksupdatenotificationbot.png\")
<\/a><\/p>\nTable of Contents<\/h2>\n
\n
\ud83c\udfc1 Pre-requisites<\/h2>\n
\n
\n\ud83d\udee0 Install Teams Toolkit for Visual Studio Code<\/h2>\n
\n
\ud83d\udc77 Scaffold the project<\/h2>\n
\n
\ud83e\uddd1\u200d\ud83d\udcbb Sign into your Microsoft 365 tenant<\/h2>\n
\n
\u2139\ufe0f Update the Adaptive Card<\/h2>\n
{\r\n \"$schema\": \"http:\/\/adaptivecards.io\/schemas\/adaptive-card.json\",\r\n \"type\": \"AdaptiveCard\",\r\n \"version\": \"1.4\",\r\n \"body\": [\r\n {\r\n \"type\": \"Container\",\r\n \"items\": [\r\n {\r\n \"type\": \"TextBlock\",\r\n \"text\": \"${name}\",\r\n \"size\": \"Medium\",\r\n \"wrap\": true\r\n },\r\n {\r\n \"type\": \"TextBlock\",\r\n \"text\": \"${symbol}\",\r\n \"isSubtle\": true,\r\n \"spacing\": \"None\",\r\n \"wrap\": true\r\n },\r\n {\r\n \"type\": \"TextBlock\",\r\n \"text\": \"{{DATE(${timestamp},SHORT)}} {{TIME(${timestamp})}}\",\r\n \"wrap\": true\r\n }\r\n ]\r\n },\r\n {\r\n \"type\": \"Container\",\r\n \"spacing\": \"None\",\r\n \"items\": [\r\n {\r\n \"type\": \"ColumnSet\",\r\n \"columns\": [\r\n {\r\n \"type\": \"Column\",\r\n \"width\": \"stretch\",\r\n \"items\": [\r\n {\r\n \"type\": \"TextBlock\",\r\n \"text\": \"${formatNumber(price,2)}\",\r\n \"size\": \"ExtraLarge\",\r\n \"wrap\": true\r\n },\r\n {\r\n \"type\": \"TextBlock\",\r\n \"text\": \"${if(change >= 0, '\u25b2', '\u25bc')} ${formatNumber(change,2)} USD (${formatNumber(changePercent, 2)}%)\",\r\n \"spacing\": \"None\",\r\n \"wrap\": true\r\n }\r\n ]\r\n },\r\n {\r\n \"type\": \"Column\",\r\n \"width\": \"auto\",\r\n \"items\": [\r\n {\r\n \"type\": \"FactSet\",\r\n \"facts\": [\r\n {\r\n \"title\": \"Open\",\r\n \"value\": \"${formatNumber(open,2)}\"\r\n },\r\n {\r\n \"title\": \"High\",\r\n \"value\": \"${formatNumber(high,2)}\"\r\n },\r\n {\r\n \"title\": \"Low\",\r\n \"value\": \"${formatNumber(low,2)}\"\r\n }\r\n ]\r\n }\r\n ]\r\n }\r\n ]\r\n }\r\n ]\r\n }\r\n ]\r\n}<\/pre>\nexport interface GlobalQuote {\r\n symbol: string;\r\n open: number;\r\n high: number;\r\n low: number;\r\n price: number;\r\n volume: number;\r\n latestTradingDay: string;\r\n previousClose: number;\r\n change: number;\r\n changePercent: number;\r\n name?: string;\r\n timestamp?: string;\r\n}\r\n<\/pre>\n![\"Image](\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/09\/teams-toolkit_test-bot.png\")
<\/a><\/p>\n\ud83d\udce1 Create an API connection<\/h2>\n
\n
\ud83e\udd16 Update the bot logic<\/h2>\n
import { AzureFunction, Context } from '@azure\/functions';\r\nimport { AdaptiveCards } from '@microsoft\/adaptivecards-tools';\r\nimport { AxiosInstance, ConversationBot, TeamsBotInstallation } from '@microsoft\/teamsfx';\r\n<\/pre>\n\n
import { bot } from '.\/internal\/initialize';\r\nimport { GlobalQuote } from '.\/cardModels';\r\nimport template from '.\/adaptiveCards\/notification-default.json'\r\nimport { alphaVantageClient } from '.\/apiConnections\/alphaVantage';\r\n<\/pre>\n\n
const timerTrigger: AzureFunction = async function (context: Context, myTimer: any): Promise<void> {\r\n const timestamp = getTimestamp(new Date());\r\n\r\n getQuoteBySymbol(alphaVantageClient)('MSFT')\r\n .then(getResponseData)\r\n .then(extractGlobalQuote)\r\n .then(transformGlobalQuote)\r\n .then(quote => addTimestamp(quote)(timestamp))\r\n .then(quote => addCompanyName(quote)('Microsoft Corporation'))\r\n .then(quote =>\r\n getInstallations(bot)\r\n .then(targets => targets.map(target => sendCard(target)(AdaptiveCards)(template)(quote)))\r\n )\r\n .catch(err => handleError(err)(context));\r\n\r\n}\r\n\r\nexport default timerTrigger;\r\n<\/pre>\n\n
const getTimestamp =\r\n (date: Date): string =>\r\n makeValidAdaptiveCardISOString(date.toISOString());\r\n\r\nconst makeValidAdaptiveCardISOString =\r\n (iso: string): string =>\r\n `${iso.split('.')[0]}Z`;\r\n<\/pre>\nconst getQuoteBySymbol =\r\n (apiClient: AxiosInstance) =>\r\n (symbol: string) =>\r\n apiClient.get(`\/query?function=GLOBAL_QUOTE&symbol=${symbol}`)\r\n\r\nconst getResponseData =\r\n (res: any): object =>\r\n res.data;\r\n<\/pre>\nconst extractGlobalQuote =\r\n (data: object): GlobalQuote =>\r\n data['Global Quote'];\r\n\r\nconst transformGlobalQuote =\r\n (quote: GlobalQuote): GlobalQuote => ({\r\n symbol: Object.values(quote)[0],\r\n open: Number.parseFloat(Object.values(quote)[1]),\r\n high: Number.parseFloat(Object.values(quote)[2]),\r\n low: Number.parseFloat(Object.values(quote)[3]),\r\n price: Number.parseFloat(Object.values(quote)[4]),\r\n volume: Number.parseFloat(Object.values(quote)[5]),\r\n latestTradingDay: Object.values(quote)[6],\r\n previousClose: Number.parseFloat(Object.values(quote)[7]),\r\n change: Number.parseFloat(Object.values(quote)[8]),\r\n changePercent: Number.parseFloat(removePercent(Object.values(quote)[9]))\r\n });\r\n\r\nconst removePercent =\r\n (string: string): string =>\r\n string.replace('%', '');\r\n\r\nconst addTimestamp =\r\n (quote: GlobalQuote) =>\r\n (timestamp: string): GlobalQuote => { return { ...quote, timestamp } }\r\n\r\nconst addCompanyName =\r\n (quote: GlobalQuote) =>\r\n (name: string): GlobalQuote => { return { ...quote, name } }\r\n\r\n<\/pre>\nconst getInstallations =\r\n (bot: ConversationBot): Promise<TeamsBotInstallation[]> =>\r\n bot.notification.installations();\r\n<\/pre>\n
const sendCard =\r\n <T extends object>(target: TeamsBotInstallation) =>\r\n (ac: typeof AdaptiveCards) =>\r\n (template: object) =>\r\n (quote: GlobalQuote): Promise<any> =>\r\n target.sendAdaptiveCard(ac.declare<T>(template).render(quote as T));\r\n<\/pre>\n
const handleError =\r\n (err: Error) =>\r\n (context: Context) =>\r\n context.log({ err });\r\n<\/pre>\n\ud83e\uddea Test your bot!<\/h2>\n
\n
\u23ed What’s next?<\/h2>\n
\n
\ud83d\udcda Learn more!<\/h2>\n
\n