The Microsoft Teams Bot integration enables you to trigger Torq workflows and to access and interact with your Teams users, teams, channels, and messages as part of your Torq workflows. In addition, you can create a Teams bot that can post messages to users and channels, tag users with the @ command, and more.
To trigger Torq workflows from Teams, after you follow the steps below to create a Microsoft Teams Bot integration, you can either mention the bot in a chat or send a direct message to it. If you mention the bot in a chat, you can use free text describing what you want the bot to do (for example, check IP address) or select a command from the command list (which you'll create as part of this tutorial).
Add a Bot to Microsoft Teams
The Teams bot is simply a Teams app to which you assign bot capabilities. You can use the bot to send users and channels unidirectional messages or questions that expect user responses. You can also create one or more commands (commands menu) that users can execute within a chat. The commands can be used to trigger Torq workflows. For example, if you add a command called check-ip, you can define the trigger condition only to apply when that command is used in a chat.
Create a Custom Apps Policy
The custom apps policy enables the user creating the bot to install custom apps for their team, including the bot. If this user already has the required permissions, or a custom apps policy already exists with the required permissions, you can skip this section and go directly to Create a bot
Log in to your Teams admin console.
From the navigation menu, navigate to Setup policies and click Global (Org-wide default).
Confirm that Upload custom apps is set to On.
If the policy is set to Off, create a new custom app policy.
Go back to Setup policies and click Add.
Enter a meaningful name for the policy.
Set the Upload custom apps setting to On.
Click Save.
Apply the custom policy to the user that will create the bot.
Go to Users > Manage Users and locate the user.
Hover to the left of the user's name, click the check mark icon, and click Edit settings.
Click Edit setting, and for App setup policy, select the policy with the Upload custom apps setting set to On.
Click Apply.
Create a Bot
When you create the bot, it is assigned an ID, and you must generate a client secret. The ID and client secret are passed as input parameters for Teama steps in Torq workflows. The Torq icon is attached to this article.
Copy and save the client secret in a safe place, as you won't be able to access it again.
Click Apps > New app.
Define the app Basic information and click Save. The bot attributes in the table below can be customized for your organization so that the bot that sends messages in chats and group chats aligns with your brand. The values in the table below are based on creating a bot for Torq, but you can enter values for your company so the bot matches the company branding.
Define the app Branding. Branding enables you to upload custom icons for the app/bot, which will be displayed when messages are sent to users and groups. You might want to add your company's logo/icon.
Under Configure, click Branding.
Upload an image for the Color icon. This is displayed in the store and most other places. The icon must be 192x192 pixels total with a 96x96 pixel symbol in the center.
Upload an image for the Outline icon. This displays on the left side of Teams when the app is in use. The icon must be 32x32 pixels and either white or transparent.
Create and configure the bot.
Under Configure, click App features.
Select the Bot card.
Click the Create new bot link.
Click +New Bot, enter a name for the bot, and click Add.
In the Bot endpoint address field enter https://teams-app.torq.io/teams/v1/interactivity-hooks or for EU: https://teams-app.eu.torq.io/teams/v1/interactivity-hooks
Click Save.
From the left menu, click Client Secrets and then Add Client Secrets to your bot. Copy and save the secret to a location you can access later. When creating the Teams Bot integration in Torq, you'll need this for the Microsoft Teams Bot Client Secret field.
From the left navigation menu, click Apps.
Select the app you created.
In the left menu, click App features and then click the Bot card.
In the Identify your bot section, select the bot you created and click Save.
At the bottom of the page, under Select the scopes in which people can use this command, select all of the scopes (Personal, Team, and Group Chat).
Click Save.
Before publishing, see the table below for a guideline of how to fill in the required fields.
From the left menu, select Publish to org and then click Publish your app.
Field | Value |
|
Short name | Torq Bot |
|
App ID | You'll need this for the Microsoft Teams App ID field when creating the Teams Bot integration in Torq. |
|
Package Name | - |
|
Short description | Torq Security Automation Bot |
|
Full description | Torq’s no-code automation modernizes how security and operations teams work with easy workflow building, limitless integrations, and numerous prebuilt templates. |
|
Developer or company name | torq.io |
|
Website |
| |
Privacy statement |
| |
Terms of use |
| |
Full-Color Icon | Use the icon attached to this article. |
|
Grant the App Permission in the Teams Admin Portal
After publishing your app, you must have an admin approve the app in the Teams Admin portal.
Log in to the Teams Admin portal.
Navigate to Teams apps > Manage apps. The Pending Approval card will show at least one app that is pending approval.
In the search box for the table, search for the Teams app name you created above.
Click the application name, and in the ensuing window, click Approve.
Grant the App Permission in Azure Portal
The permissions granted to the app determine which actions you can perform as steps in Torq workflows.
Go to your Azure portal.
Go to App registrations.
Search for your app. It will have the same name as you gave the bot.
Under Overview, you'll see Directory (tenant) ID. Save this for later use. When creating the Teams Bot integration in Torq, you'll need it for the Microsoft Tenant ID field.
Under Supported account types, enable Accounts in any organizational directory/Multitenant.
Go to API permissions, click +Add a permission > Microsoft Graph > Application permissions and add the following permissions.
AppCatalog.Read.All
Group.Read.All
TeamsAppInstallation.ReadWriteForTeam.All
TeamsAppInstallation.ReadWriteForUser.All
User.Read.All
The following positions are optional, but should be added for using some of the Microsoft Teams steps.
Channel.ReadBasic.All
Chat.ReadWrite.All
Team.ReadBasic.All
TeamsAppInstallation.ReadForUser.All
Click Grant admin consent.
Create Bot Commands
Before you create bot commands, determine the actions you want your users to be able to perform from within a chat. In Torq, we'll use the command name to trigger a workflow. For example, if you create a command called check-ip, each time that command is used in a chat it will trigger a workflow that parses the IP address sent in the chat and submit it for analysis. The workflow can then return the analysis results to that same (or a different) chat.
In the Developer Portal, go to your Apps and select the app you created: https://dev.teams.microsoft.com/apps.
Click App features > Bot.
Click Add a command, configure the command, and click Add.
Enter a name for the command. This name will be displayed in chats.
Enter a description for the command that explains what the command does. This description will be displayed in chats.
Select all of the scopes.
To create additional commands, click the + icon in the commands table.
Create a Microsoft Teams Bot Integration
The Teams Bot integration stores all of the app and bot details, which authenticate access to the bot. Most of these details were created and saved earlier.
Some Microsoft Teams Bot steps require an authentication token, while others require an integration instance. Make sure you add the Generate Microsoft Teams Bot API Token step before other Teams Bot steps so you can pass the generated token in subsequent required steps.
Go to Build > Integrations > Microsoft Teams Bot, and click Add.
Enter the required details.
Integration name: Enter a unique and meaningful name
Microsoft Teams Bot Client ID: Navigate to aad.portal.azure.com, and under your tenant, click App registrations. Click the app for your Torq bot, and under the Overview page, copy the value for the Application (client) ID.
Microsoft Teams Bot Client Secret: You must have copied this value to a safe location when creating the Bot. It was available in step 6.
Microsoft Teams App ID: Navigate to dev.teams.microsoft.com. Click Apps -> Basic information. Copy the value under App ID.
Microsoft Tenant ID: Navigate to aad.portal.azure.com, and under your tenant, click App registrations. Click the app for your Torq bot and copy the value for the Directory (tenant) ID.
Click Add.