How to add slash commands (Modal) to your Slack Endpoint

Introduction

In Slack, is possible to add interaction to your App using some tools such as slash commands (/command) and modals. 

ONEiO utilizes Interactivity, Slash Commands, and Incoming Webhooks features of the Slack App. 

For any questions related to setting up the integration, please send mail to support@oneio.cloud.

You can sign up for a free trial of ONEiO from the following link: ONEiO Free Trial

Overview

In this article, we will show you how to add interactivity through modal, slash commands, and Webhooks to your Slack integration (bi-directional). If your integration needs also real-time messaging (Event subscriptions), please, contact our support.

In this example, we will show you how to configure slash commands using an integration between Slack and Jira.

Sending messages from Slack to ONEiO

Configuring your Slack endpoint

First, create a basic integration with your preferred system and Slack.

For setting up a basic (one-direction) Slack integration and configuring a basic Slack app, refer to this article: How to configure Slack for integration with ONEiO

Edit your Slack endpoint and generate a new password.

Click on Copy Target URL to clipboard

Store this copied URL, you will use it in the next steps when configuring Interactivity and slash commands.

Click on Save Changes.

For more details, you can check Endpoint Configuration Guide - Slack 

 

Configuring Interactivity

Let's configure the same App you created previously for sending messages to ONEiO. 

Go to (https://api.slack.com/apps) and edit your Slack App.

On your left navigation, select Interactivity & Shortcuts and turn on Interactivity.

Paste here the URI you copied in the previous step when generating the Slack Endpoint password

You may see a message telling you that you changed the permission scopes and need to reinstall your app. You can ignore it, we will reinstall your app in a further step.

 

Creating slash commands

Your App will be configured to send messages to ONEiO through slash commands.

Let's configure your first slash command. On your left navigation, select Slash commands and click on Create New Command.

Fill out the form with:

• your new slash command (ex: /newjiraissue)
• the same Request URL you filled in the previous step - Interactivity (copied from your ONEiO's Slack Endpoint)
• A short description of what this command does
• An usage hint

When you finnish, click on Save

You may see a message telling you that you changed the permission scopes and need to reinstall your app. You can ignore it, we will reinstall your app in a further step.

 

Configure Scopes for Slack App

For bilateral communication, we need to add some scopes. 

On your left navigation, select OAuth & Permissions and then go to Scopes.

You will need the following scopes: channels:history, channels:read, chat:write, commands, files:read, im:history, incoming-webhook, users:red, users:read.email

Now it's time to republish your App with the last changes.

On your left navigation, select Basic Information and then select Install your App.

Click on Reinstall to Workspace.

You will be forwarded to a page requesting permission to your App access your workspace. 

Select the desired channel your app will be allowed to send and read messages, and click on allow.

Note: As soon you click on allow with the new scopes, an incoming webhook is created for the selected channel.

This app should now be installed and allowed to send and read messages from the selected channel. If you didn't install your App in the channel selected above yet, please check in the basic configuration article how to do it.

 

Sending bi-directional messages from Slack to ONEiO

Creating rules for slash commands

When a user enters the configured slash command in a Slack channel, your Slack App will send a POST request to the URL configured as Request URL in the command settings. 

So, in this example, when you type /newjiraissue , your Slack App will send a POST request to your ONEiO's Slack endpoint and we will handle this payload through a Rule. This rule will check the received command and forward a Modal window back to Slack.

Later, when we fill this Modal, slack will send an Event to your ONEiO endpoint containing the filled information. 

We need to create 3 rules for dealing with modal interactions: One for receiving the command and sending the Modal form, a second one for receiving the submitted Modal form and sending it to your connected endpoint, and a third one to send a response to Slack.

 

Creating a rule for slash commands

Let's start by creating the rule responsible for dealing with slash commands.

Go to Routing Rules and Create New Rule;

Fill your rule name and set the Route information as shown below, just replacing the inbound and outbound endpoint with your Slack endpoint. 

• Rule name: Slack -> Slack: Retrieve command and send Modal (you can name your rule freely)
• Route information -> Inbound: Select your Slack as the Endpoint and the Entity Type view_submission
• Route information -> Outbound: Select your Slack as the Endpoint, the Entity Type view_submission, and the Message Type Response Template
• Add an attribute condition, where the attribute command is equal to your Slack-configured command.

Make sure to select Response Template as Message Type on the Outbound configuration.

Go to Mappings, and in Outbound mappings, we will add the mapping containing the callback id and the modal content. This content was built using the Slack Block kit.

You will find two identifiers in this block code:

• callback_id is used as an identifier for what modal template is used. It is used in rules.
• block_id is used as an identifier for the Modal field in block elements. It is used in rules.

Source value	Outbound attribute
${trigger_id}	trigger_id
block code* (see the block code below)	view

The example modal code can be found below the image.

{
    "type": "modal",
    "callback_id": "issue",
    "title": {
        "type": "plain_text",
        "text": "Create a new Jira issue"
    },
    "submit": {
        "type": "plain_text",
        "text": "Submit",
        "emoji": true
    },
    "close": {
        "type": "plain_text",
        "text": "Cancel",
        "emoji": true
    },
    "blocks": [
        {
            "type": "input",
            "block_id": "title",
            "label": {
                "type": "plain_text",
                "text": "Title"
            },
            "element": {
                "type": "plain_text_input",
		"initial_value": "${text}",
                "action_id": "add_title",
                "multiline": false,
               "focus_on_load": false
            },
            "optional": false
        },
        {
            "type": "input",
            "block_id": "description",
            "label": {
                "type": "plain_text",
                "text": "Description",
                "emoji": true
            },
            "element": {
                "type": "plain_text_input",
                "action_id": "add_description",
                "multiline": true,
                "focus_on_load": true
            },
            "optional": false
        }
    ]
}

For more details about Slack Modals you can follow Slack instructions.

You can also modify the example modal easily or create new Modals with Slack's Block Kit Builder

Now, go to Conversation variables and set the following variables:

Source Value	Conversation variable
${response_url}	response_url
${trigger_id}	trigger_id
${token}	slack_token
${channel_id}	channel_id

When adding the conversation variable, you don't need to add sf:conversation in front of it: The sf:conversation will be automatically added to the variable.

Save the rule and you are now ready to test the Modal interaction, without submitting the form.

Just go to the authorized Slack channel and type your slash command. This way, when you send, for instance, /newjiraissue My first Slack issue in the channel #jiranotifications, you will receive this Modal window back:

 

Creating a rule for receiving modal submitted content

Let's proceed to create another rule. This new rule will be responsible for receiving the Modal's submitted content (form), mapping it, and directing it to your other instance (in this example, Jira).

• Rule name: Slack -> Jira: Create Issue (you can name your rule freely)
• Route information -> Inbound: Select your Slack as the Endpoint and the Entity Type view_submission
• Route information -> Outbound: Select your other instance (ex: Jira) as the Endpoint, and the Entity Type incident
• Add an attribute condition, where the attribute payload.view.callback_id is equal to the one we set in the previous rule (modal code block): issue

Go to Mappings, and in Outbound mappings, we will map some outbound variables to Jira endpoint and add the mapping containing the modal submitted content

Source Value	Outbound attribute
[your jira project key]	fields.project.key
[your jira issuetype id]	fields.issuetype.id
${payload.view.state.values.title.add_title.value}	fields.summary
${payload.view.state.values.description.add_description.value}	fields.description

 

Go to Conversation variables and add a new conversation variable:

Source Value	Outbound attribute
${payload.view.state.values.title.add_title.value}	sf:conversation:jira_issue_title

Then save your rule. 

Creating a rule to send the response to Slack

Let's also create a rule to send a message to Slack when your issue is successfully created. For this, go to the tab Rule and Route in the rule you just created, Slack -> Jira: Create Issue, and n the section Response Rules, click on Create New

Then, fill in the rule fields as follow:

• Rule name: Slack -> Jira: Create Issue - Response (you can name your rule freely)
• The route information is already filled and is not possible to change it
• Add an attribute condition, where the attribute key exists
• Add another attribute condition, where webhookEvent not exists
• And in Outbound, change the Message Type to Message

Now, go to Mappings tabs, Outbound mappings, and let's map the message to Slack:

Source Value	Outbound attribute
Your channel id	channel
*Your issue was created successfully*: #${key}: ${sf:conversation:jira_issue_title}	text

 

You can also use code blocks when sending a message to Slack:

 

[
{
	"type": "section",
	"text": {
		"type": "mrkdwn",
		"text": "Your ticket #${key} was created successfully."
	}
},
{
	"type": "section",
	"fields": [
		{
			"type": "mrkdwn",
			"text": "*ID:*\n${key}"
		},
		{
			"type": "mrkdwn",
			"text": "*Jira ID:*\n${id}"
		},
		{
			"type": "mrkdwn",
			"text": "*Title:*\n${sf:conversation:jira_issue_title}"
		},

		{
			"type": "mrkdwn",
			"text": "*Channel:*\nSlack"
		}
	]
},
{
		"type": "divider"
}
]

 

Testing your Modal integration

Now, try to send a Modal through Slack, in this example, by opening a Jira Issue:

You can check this interaction in your message feed:

 

Congratulations!

Your Slack Modal integration is complete.