Teams bot

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 the bot. If you mention the bot in a chat, you can either 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.

1. Create a custom apps policy

The custom apps policy enables the user that is 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

1. Log in to your Teams admin console.
2. From the navigation menu, ,navigate to Setup policies and click Global (Org-wide default).
3. Confirm that Upload custom apps is set to On.
4. If the policy is set to Off, create a new custom app policy.
   1. Go back to Setup policies and click Add.
   2. Enter a meaningful name for the policy.
   3. Set the Upload custom apps setting to On.
   4. Click Save.
5. Apply the custom policy to the user that will create the bot.
   1. Go to Users > Manage Users and locate the user.
   2. Hover to the left of the user's name, click the check mark icon, and click Edit settings.
   3. Click Edit setting and for App setup policy select the policy that has the Upload custom apps setting set to On.
   4. Click Apply.

2. Create a bot

When you create the bot, the bot is assigned an ID and you'll need to generate a client secret.Both the ID and client secret are passed as input parameters for Teams steps in Torq workflows. The Torq icon is attached to this article.

1.  Go to https://dev.teams.microsoft.com.
2. Click Apps > +New app.
3. 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 align 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 company branding.

   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	https://torq.io
   Privacy statement	https://torq.io/privacy
   Terms of use	https://torq.io/terms-conditions
   Full Color Icon	Use the icon attached to this article.

4. 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.
   1. Under Configure, click Branding.
   2. Upload an image for the Color icon. This displays in the store and in most other places. The icon must be 192x192 pixels total with a 96x96 pixel symbol in the center.
   3. 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.
5. Create and configure the bot.
   1. Under Configure, click App features.
   2. Select the Bot card.
   3. Click the Create new bot link.
   4. Click +New Bot, enter a name for the bot, and click Add.
   5. 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 
   6. Click Save. 
6. From the left menu click Client secrets and then click Add client secret to your bot. Make sure you copy and save the secret to a location from which you'll be able to access it later. You'll need this for the Microsoft Teams Bot Client Secret field when creating the Teams Bot integration in Torq.
7. From the left navigation menu, click Apps.
8. Select the app you created.
9. From the left menu click App features and then click the Bot card.
10. In the Identify your bot section, select the bot you created and click Save.
11. 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).
12. Click Save.
13. From the left menu, select Publish to org and then click Publish your app.

3. Grant the app permission in Teams Admin portal

After publishing your app, you must have an admin approve the app in the Teams Admin portal.

1. Log in to Teams Admin portal.
2. Navigate to Teams apps > Manage apps. The Pending Approval card will show at least one app that is pending approval.
3. In the search box for the table, search for the Teams app name that you created above.
4. Click the application name, and in the ensuing window, click Approve.

4. Grant the app permission in Azure portal

The permissions granted to the app determine which actions you can perform as steps in Torq workflows.

1. Go to your Azure portal.
2. Go to App registrations.
3. Search for your app. It will have the same name as you gave the bot.
4. Under Overview, you'll see Directory (tenant) ID. Save this for later use. You'll need it for the Microsoft Tenant ID field when creating the Teams Bot integration in Torq.
5. Go to API permissions, click +Add a permission > Microsoft Graph > Application permissionsand add the following permissions.
   1. AppCatalog.Read.All
   2. Group.Read.All
   3. TeamsAppInstallation.ReadWriteForTeam.All
   4. TeamsAppInstallation.ReadWriteForUser.All
   5. User.Read.All
6. Click Grant admin consent for....

5. 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 results of the analysis to that same (or a different) chat.

1. In the Developer Portal, go to your Apps and select the app you created: https://dev.teams.microsoft.com/apps.
2. Click App features > Bot.
3. Click Add a command, configure the command, and click Add.
   1. Enter a name for the command. This name will be displayed in chats.
   2. Enter a description for the command that explains what the command does. This description will be displayed in chats.
   3. Select all of the scopes.
4. To create additional commands, click the + icon in the commands table.

Collect the Teams app IDs

When using Teams steps in a workflow, you'll need to pass certain IDs as input parameters, such as tenant ID, app ID, and so on.

1. Go to your Teams dashboard.
2. Click the ellipsis button next to the team you associated the bot to
3. Select Get link to team and copy the link.
4. Extract the team ID and tenant ID from the team link. The team's link is structured as follows: https://teams.microsoft.com/l/team/XXXXXXXX/conversations?groupId=YYYYYYYY&tenantId=ZZZZZZZZ, where the (XXXXXXXX) is the team ID, (YYYYYYYY) is the group ID, and (ZZZZZZZZ) is the tenant ID.
   1. To get the team ID, take the (XXXXXXXX) value and change the %3a to : and change %40 to @. In the below example, the team ID is: 19:Qrnmk-m1VG-jNhgm3d6LqIL54z6qNrgdlThiPPSvJT81@thread.tacv2.
   2. To get the tenant ID, take the (ZZZZZZZ) value. In the below example, the tenant ID is: d4e6ae8c-ad1c-4af1-b64f-74356ipd2c5d.
      https://teams.microsoft.com/l/team/19%3aQrnmk-m1VG-jNhgm3d6LqIL54z6qNrgdlThiPPSvJT81%40thread.tacv2/conversations?groupId=176b0683-ae15-4a8b-8c85-666859825e08&tenantId=d4e6ae8c-ad1c-4af1-b64f-74356ipd2c5d
5. Get the bot ID.
6. Create a custom secret for each of the IDs so you can easily access them from context. These will be accessible from $.secrets.
   1. In Torq, go to the Integrations page, locate the Custom Secrets card, and click Add.
   2. Enter the Secret key, for example teams_tenant_id.
   3. Enter the Secret value, for example, d4e6ae8c-ad1c-4af1-b64f-74356ipd2c5d.

Create a Microsoft Teams Bot integration

The Teams Bot integration stores all of the app and bot details which authenticate an access to the bot. Most of these details were created and saved earlier.

1. Go to the Integrations page, locate the Microsoft Teams Bot card, and click Add.
2. Enter the required details.
   1. Integration name
   2. Microsoft Teams Bot Client ID - to get this value, navigate to add.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.
   3. Microsoft Teams Bot Client Secret - You need to have copied this value to a safe location when creating the Bot. It was available in step 6.
   4. Microsoft Teams App ID - to get this value, navigate to dev.teams.microsoft.com. Click Apps -> <appName> -> Basic information. Copy the value under App ID.
   5. Microsoft Tenant ID - to get this value, navigate to add.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.
3. Click Add.