- 11 Sep 2023
- 8 Minutes to read
- DarkLight
Torq Bot (Slack steps integration)
- Updated on 11 Sep 2023
- 8 Minutes to read
- DarkLight
The Torq bot is a feature of the Torq app for Slack. The Slack steps integration adds the Torq bot (Torq app) to your workspace, which enables you to perform common Slack actions as part of your workflows and also trigger Torq workflows directly from the Slack CLI by mentioning (@) the Torq bot or sending a message directly in the Torq app channel. Messages sent from Torq to Slack are done via the bot. By default, the bot is named Torq and uses the Torq logo. You can easily replace the name and logo to match your company's branding.
Slack steps can be used for posting textual or image updates inside Slack conversations and channels, as well as for providing multiple-choice questions to specific users or channels and later referring to the chosen responses in the workflow run.
To use Slack steps in a workflow, you'll need to create a Slack steps integration, customize your Torq bot, and add the steps to a workflow. We'll show you how to use the most common Slack steps.
Reauthorize the integration
You should reauthorize the integration when you need to authorize new scopes or re-install an existing integration.
- Go to Integrations > Steps and locate the Slack card.
- Click Edit for the integration you want to reauthorize.
- Click the Reauthorize button and when prompted, then click Allow.
1. Create a Slack integration
Perform these steps in Torq.
- Go to Integrations > Steps, search for the Slack card, and click Add.
- Enter a meaningful name for the integration and click Add.
- By default, mentions of the Torq bot and direct messages in the bot channel create Torq events that can be used to trigger workflows. Unselect the Receive events from Slack app mentions checkbox if you don't want to trigger Torq workflows from Slack.
- Select the Slack workspace to which you want to add the Torq bot (Torq app) and click Allow to grant Torq permission to your workspace.
2. Customize the Torq bot
If you want, you can change the name and logo of the Torq bot. The name and logo of the bot appear in Slack when a message is sent to a user or channel.
Change the bot user name
By default, the name of the bot user is Torq.
- Select the Torq app from the Apps section and then select Configuration from the menu that appears when you click the bot name at the top of the screen.
- Click Edit in the Bot User section and enter the name you want to appear when messages are sent from Torq to Slack, for example, Security Team.
Change the bot logo
You can also change the bot logo, but this can only be done on an individual step level by adding the logo image file as an input parameter.
If you want to change the app logo, it's recommended that you configure each Slack message/question step with the logo file, and save them as custom steps. This way you won't have to add the image file each time you use one of those steps.
- Send snippet
- Send Slack attachment message
3. Add the Torq app to a channel
To communicate with the bot in a channel, you need to add the Torq app to the channel. In most cases, if you mention the bot and it is not part of the channel you'll be prompted to add the bot.
There are a couple of ways to add an app to a channel:
- Use the Add apps to this channel Slack slash command.
- Click + Add this app to a channel in the app menu.
4. Run a Torq workflow from Slack
When you have a Slack steps integration set up you can run a Torq workflow directly from Slack:
- Sign in to your Torq workspace: /torq signin.
- Run a workflow: /torq run.
Select the workflow you want to run. You can see the name of the workspace in which the workflow will run. - You can also specify the workflow name in the run command: /torq run <worflow name>.
Switch to a different workspace
If the Slack workspace is associated with integrations in more than one Torq workspace and you want to run the workflow in a different workspace:
- In Slack, run: /torq signout.
- In Torq, switch to the workspace you want to log in to in Slack.
- In Slack, run: /torq signin.
5. Slack steps
You can find information about some of the main Slack steps below.
There are several important things to keep in mind when building a workflow that has the Torq bot communicating with users.
- The RECIPIENT field needs to include the hashtag symbol (#) as a prefix to any channel name, for example, #{{ $.event.channel }}.
- If you want to mention a user in the message, use the following syntax: <@{{ $.event.user }}>.
Send a message
This step is used for providing unidirectional information updates (i.e., from a Torq workflow to a Slack user or channel). It is intended for short messages. For longer messages, use the step Send a snippet.
Send a snippet
This step is used for delivering a large volume of data (configuration file, excerpt from logs, and so on) to a Slack channel. Since Slack messages are limited by size, sending snippets is the proper way to deliver any information that is longer than several lines of text.
Ask a question
This step enables you to send a question to a user or a channel with responses that you configure. For example, if you're confirming a suspicious login attempt, you can send the user a message asking if they attempted the login, and the user can click Yes or No. You might want to send a question to a channel, for example to a channel of managers to approve a request, and any member of the channel can respond.
In this example, you send a question to a user that reset their Okta password.
Send block form
This step enables you to send a form to a user or a channel. A form can include any of the supported interactive components: datepickers, checkboxes, user text input, multiple option selections, and many more. Use a form to collect all the information you need in one interaction and in the formats that best suit the type of information youโre trying to collect.
- Use the Slack Block Kit Builder to create the form you want to send.
- Copy the form payload to the BLOCKS field in the Send Block Form step. Click the cogwheel icon to add the optional timeout parameter. In this example, the user is asked to provide information to schedule a retry for a URL scan that didn't finish on time.
- By default, Cancel and Submitbuttons will be automatically added at the bottom of your form. If the user clicks Cancel, none of the information the user may have entered in the form will be included in the step output.
๐ Important You can add the RESPONSES optional parameter to replace the Cancel and Submit buttons with any number (up to 25) of buttons with customizable titles at the bottom of the form. The step output will include the button title the user clicks and any information entered in the form. Clicking any custom buttons at the bottom of the form will essentially submit the form.Since the Submit and Cancel buttons are the ones used for the submission of the form, other buttons or dispatch actions won't have this functionality. This means these components won't provide any information if included in the form. - The workflow is on hold until the user submits or cancels the form or until the form times out.
- After the user submits or cancels the form (or the form times out), the form is no longer available, and only a summary of the interaction is presented.
You can choose not to display the interaction summary by adding the optional POST_RESPONSE_MESSAGE parameter and setting it to false. - The Send Block Form step output contains the user response and the identity of the responding user. This information can be used to direct your workflow and for reference in other workflow steps.
- Find the path to the user response by typing $. and selecting Select from tree mode from the autocomplete options. Search for the block_id in the context tree to access the user response easily.
Send a message/question to a thread
When you're using a Slack step that sends a message/question to a user or channel, you can add the THREAD_TS input parameter (optional), which will send the message/question in a thread of the parent message. The value for the THREAD_TS parameter should be {{ $.<step_name>.message_ts }} of the parent message. For example, if you use the step Ask a question, wait for a response, and then want to respond in a thread based on the answer, the value would be {{ $.ask_a_question.message_ts }}.
In this example, an Okta user reset their password, which triggered the workflow. You get the user's details and send them a Slack question asking them to confirm that they reset their password. If the user confirms (responds, Yes) that they reset their password, use the step Send message to respond in a thread to the original Ask a question message.
Create a channel
This step will create a new Slack channel. A common use case is to create a channel dedicated to investigating an incident as part of a workflow.
Invite users to a channel
This step will invite the specified users to the specified channel.
6. Create a workflow in Torq
Create a basic Hello World workflow that will receive an event from a message that mentions the Torq bot and then send a reply message to the channel and mention the user that sent the original message.
- Go to the Workflows page and click Create Workflow.
- Type a meaningful name for the workflow, such as Slack Events Hello World.
- Click the trigger icon and then the Slack integration.
- Select the integration you created.
- In the Steps Library, search for Slack and add the step Send a message.
- Configure the step.
- Rename the step to something meaningful, such as, Acknowledge message.
- In the RECIPIENT field, enter #{{ $.event.channel }}.
- In the MESSAGE TEXT field, enter a message that mentions the user that sent the original message. In our example, the message mentions the user and quotes the text that they sent to the bot: <@{{ $.event.user }}>, I got your message: "{{ $.event.text }}
- Go to Slack, and from the command line, mention the Torq bot (@Torq) and type Hello World.
Wait a few seconds, and you should receive the reply message to the channel you mentioned the bot in.