33 Slack

Here's what happens when you use Slack as a channel for your digital assistant (or standalone skill):

  • Slack hosts your digital assistant through the intermediary of a Slack app.
  • Users chat with your digital assistant through the Slack app in the Slack user interface.

See Building Slack apps for Slack's developer documentation for Slack apps.

Here are the steps for creating a Slack channel for Digital Assistant.

Step 1: Get a Slack Workspace

To make your digital assistant (or standalone bot) available in Slack, you need to have a Slack workspace available to you where you have the permissions necessary to create a Slack app.

If you don't have such a workspace available to you, you can create your own. See Slack's Create a new workspace page.

Step 2: Create a Slack App

  1. Go to Slack's Your Apps page.

  2. Click Create an App.

  3. In the Create a Slack App dialog, fill in the App Name and Development Slack Workspace fields and click Create App.

    Once the app is created, its Basic Information page appears.

  4. Scroll down to the App Credentials section of the page and note the values of the Client ID, Client Secret, and Signing Secret.

    You'll need these credentials when you set up the channel in Digital Assistant.

Step 3: Add OAuth Scopes for the Slack App

You add OAuth scopes for permissions that you want to give to the bot and to the user.

  1. In the left navigation of the web console for your Slack app, within the Features section, select OAuth and Permissions.

  2. Scroll to the Scopes section of the page.

  3. The scopes fall into these categories:
    • Bot Token Scopes
    • User Token Scopes
  4. In the Bot Token Scopes section, add the scopes that correspond to the bot-level permissions that you want to allow. The following bot token scopes are required:

    • chat:write
    • im:history
    • users:read
  5. In the User Token Scopes section, add the scopes that correspond to the user-level permissions that you want to allow. The following user token scope is required:

    • files:write

Depending on the requirements of your bot, you may need to add other scopes.

Step 4: Add the App to the Workspace

  1. Scroll back to the top of the OAuth & Permissions page.

  2. Within the OAuth Tokens & Redirect URLs section, click Install App to Your Workspace.

    A page will appear showing what the app will be able to do.

  3. At the bottom of the page, click Allow.

Once you have completed this step, you should be able to see the app in your Slack workspace by selecting Apps in the left navigation.

Step 5: Create a Channel in Digital Assistant

  1. In Digital Assistant, click Channels in the left menu and then choose Users.

  2. Click + Channel to open the Create Channel dialog.

  3. Give your channel a name.

  4. Choose Slack as the channel type.

  5. Fill in the the values for Client ID, Client Secret, and Signing Secret that you obtained when you created your Slack app.

    You can retrieve these values from the Settings page of your Slack app.

  6. Click Create.

  7. In the Channels page, copy the WebHook URL and paste it somewhere convenient on your system. You’ll need this to finish setting up the Slack app.

  8. Click icon for the Route To ... dropdown and select the digital assistant or skill that you want to associate with the channel.

  9. In the Route To dropdown, select the digital assistant or skill that you want to associate with the channel.

  10. Switch on the Channel Enabled control.

Step 6: Configure the Webhook URL in the Slack App

  1. In the left navigation of the web console for your Slack app, select Interactivity & Shortcuts.

  2. Turn the Interactivity switch ON.

  3. In both the Request URL and Options Load URL fields, paste the webhook URL that was generated when you created the channel in Digital Assistant .

  4. Click Save Changes.

  5. In the left navigation, select OAuth & Permissions.

  6. In the Redirect URLs field, click Add New Redirect URL.

  7. Paste the webhook URL, append /authorizeV2, and click Add.

  8. Click Save URLs.

  9. In the left navigation, select App Home.

  10. In the Your App’s Presence in Slack section, turn on the Always Show My Bot as Online switch.

  11. In the left navigation, select Event Subscriptions.

  12. Set the Enable Events switch to ON.

  13. In the Request URL field, paste the webhook URL.

    After you enter the URL, a green Verified label should appear next to the Request URL label.

  14. Expand the Subscribe to bot events section of the page and click Add a bot user.

  15. Click Add Bot User Event and add the following event:

    • message.im
  16. Click Save Changes.

  17. In the left navigation, select Manage Distribution.

  18. Under the heading Share Your App with Your Workspace, click Add to Slack and then click Allow.

    At this point, you should get the message You've successfully installed your App in Slack.

Step 7: Test Your Bot in Slack

With the Slack channel and messaging configuration complete, you can test your bot (digital assistant or skill) in Slack.

  1. Open the Slack workspace where you have installed the app.

  2. In the left navigation bar, select the app that is associated with your digital assistant.

  3. In the Message field, enter text to start communicating with the digital assistant.

"New" vs. "Classic" Slack Apps

Starting with version 20.6 of Oracle Digital Assistant, creation of Slack channels is based on an updated OAuth flow in Slack apps. This updated flow enables more granular scopes. The instructions for channel setup in this guide are based on the new OAuth flow.

See https://api.slack.com/authentication/oauth-v2 for details on the updated OAuth flow.

Note:

Any existing channels that were created before Digital Assistant 20.6 and that are based on "classic" Slack apps will continue to work. However, you should consider migrating those classic Slack apps to new Slack apps. See https://api.slack.com/authentication/migration for the details.

Supported Capabilities

Slack channels in Digital Assistant support the following capabilities:

  • text (both sending and receiving)
  • images (both sending and receiving)
  • files (partial support for sending, full support for receiving)
  • emojis (partial support for sending, full support for receiving)
  • links
  • postbacks
  • custom properties
  • carousel components (but rendered vertically instead of horizontally)
  • list components

Message Constraints

Slack channels in Digital Assistant have the following message constraints:

  • Text Messages
    • Maximum length of text message: 3000 characters. If the length exceeds 3000, the text is split over multiple messages.
    • Maximum length of text action label: 30 characters
    • Types of text actions allowed: Postback, URL
  • Horizontal Cards
    • Supported?: No. Card is layout is converted to vertical.
  • Vertical Cards
    • Maximum length of title: 3000 characters
    • Maximum length of description: 3000 characters
    • Maximum length of card action label: 30 characters
    • Maximum number of cards: 100
    • Types of card actions allowed: Postback, URL
    • Types of card list actions allowed: Postback, URL
  • Attachment Messages
    • Supported?: Yes
    • Types of Actions Allowed: Postback, URL
  • Action Buttons
    • Maximum length of global action label: 30 characters
    • Types of global actions allowed: Postback, URL

Slack Channel Extensions

For Slack channels, you can extend the functionality of System.CommonResponse components with capabilities that are specific to Slack.

You access the extensions by using the channelCustomProperties element in the System.CommonResponse component and setting the appropriate properties. The code has the following format:

...
            channelCustomProperties:
            - channel: "slack"
              properties:
                PROPERTY_NAME: "PROPERTY_VALUE"
...

Here are the available custom properties for Slack channels:

Name Allowed Values Applies To... Description
showImageInAccessory
  • true
  • false
Response items of type cards. Set to true to show the card image at the right as a small image instead of a larger centered image.
showDatePicker
  • true
  • false
  • a nested object with show, initialDate and placeholder properties
Response items of type text. Set to true to show a date picker next to the text message. See also https://api.slack.com/reference/messaging/block-elements#datepicker.
renderActionsAsDropDown
  • true
  • false
  • nested object with the following properties, each of which takes a Boolean value:
    • postbackActions
    • cardPostbackActions
    • globalPostbackActions
Response items By default (if you don't set this property), actions are displayed:
  • as buttons if there are five or fewer actions
  • in a dropdown list if there are six or more

If you want to display actions in a dropdown list, no matter how many actions there are, set this property to true.

If you want to display actions as buttons, no matter how many actions there are, set this propeorty to false.

If you want to have different behavior for different types of postback actions, you can use a nested object with Boolean values for each of the following type of actions:

  • postbackActions - postback actions defined at the response item level, including text, attachment, and card list items.
  • cardPostbackActions - postback actions defined for an individual card
  • globalPostbackActions - postback actions defined for global actions.

To render actions in a dropdown menu, Slack uses a select menu with static items. See https://api.slack.com/reference/messaging/block-elements#static-select.

dropDownPlaceholder
  • placeholder text
  • nested object with the following properties, each of which takes a string value:
    • postbackActions
    • cardPostbackActions
    • globalPostbackActions
Response items Use this property to specify the placeholder text shown within the dropdown list.
fields
  • an array of strings
Response items of type text. The string values specified in this property are displayed as fields in a two-column layout (desktop) or a single column layout (mobile).

Here's an example of using the renderActionsAsDropDown custom property.

responseItems:
- type:
 "text"
  text: "Here is a list of the UI features of the Common Response Component:"
  actions:
  - ...
  channelCustomProperties:
  - channel: "slack"
    properties:
      renderActionsAsDropDown: false

And here's an example of using the renderActionsAsDropDown custom property with nested properties for postbackActions, cardPostbackActions, and globalPostbackActions.

responseItems:
- type: "text"
  text: "Here is a list of the UI features of the Common Response Component:"
  actions:
  - ...
  channelCustomProperties:
  - channel: "slack"
    properties:
      renderActionsAsDropDown:
        postbackActions: false
        cardPostbackActions: true
        globalPostbackActions: true

For more general information on channelCustomProperties, see Channel-Specific Extensions.

Slack Dialog Window

You can create a button to invoke a Slack dialog in a System.CommonResponse component. To do so, you set the button's action property to system.openDialog and include a variable named system.dialogPayload. The action metadata should look something like this snippet:

            actions:
              - label: "Edit"
                type: "postback"
                payload:
                  action: "system.openDialog"
                  variables: system.dialogPayload: ${dialogPayload}

Note:

The Freemarker expression to reference the system.dialogPayload variable does not end with .value. This is because the variable holds a JSON object, and Freemarker expressions must always evaluate to a string. Using the expression ${dialogPayload.value} would throw an error. The JSON object-to-string conversion takes place when you omit .value.

The value of system.dialogPayload is typically set in a custom component, but also can be defined inline or using a System.SetVariable component.

Here is a simple example using a System.SetVariable component:

  setDialogPayload:
    component: "System.SetVariable"
    properties:
      variable: "dialogPayload"
      value:
        callback_id: "editExpense"
        title: "Edit expense"
        submit_label": "Submit"
        elements:
          - type: "select"
            label: "Expense Type"
            name: "Type"
            value: "${expense.value.Type!''}"
            options:
              - value: "Public transport"
                label: "Metro, bus, train"
              - value: "Taxi"
                label: "Taxi"
              - value: "Meal"
                label: "Breakfast, lunch, dinner"
              - value: "Flight"
                label: "Flight"
          - type: "text"
            label: "Amount"
            name: "Amount"
            value: "${expense.value.Amount?has_content?then(expense.value.Amount.totalCurrency,'')}"
          - type: "text"
            label: "Date"
            name: "Date"
            value: "${expense.value.Date?has_content?then(expense.value.Date.date?number_to_date,'')}"

Note:

If you set the system.dialogPayload variable in a custom component, you don't need to hard-code the entity values as options. Instead, you can iterate over all the entity values of a specific item and dynamically create a select element type with an options array for the allowable values.

When the user submits input in the Slack dialog, the System.CommonResponse component sets the system.dialogSubmitted transition to move to a state that processes the submitted values. The submitted values are stored in context variables with the same name. For a custom component equivalent of the preceding System.SetVariable example, you would need to define the context variables Type, Date and Amount, since those are are defined in dialogPayload.

  ...
    transitions:
      actions:
        cancel: "askTalkToAgent"
        match: "afterMatch"
        disambiguate: "disambiguate"
        system.dialogSubmitted: "processDialog"
 
  processDialog:
    component: "System.SetVariable"
    properties:
      variable: "submittedFields"
      value: "${Type} ${Amount} ${Date}"
    transitions: {}

It is up to you to determine how to process the submitted field values. The System.CommonResponse component does NOT perform any automatic updates of entity values. It only stores the values in context variables. You will typically process these values in a custom component, so you can do additional validations if needed. In its most simple form, you can store the submitted field values in a string variable and then use the System.MatchEntity component to update entity values. Here is an example on how you could use the submitted values to update the expense composite bag entity:


  matchEntity:
    component: "System.MatchEntity"
    properties:
      sourceVariable: "submittedFields"
      variable: "expense"  transitions:
      next: "resolveExpense"

For documentation on other properties and element types that are supported in the Slack dialog payload, see https://api.slack.com/dialogs#top-level_dialog_attributes. The structure of the dialog payload should be identical to the structure described in the Slack documentation.

Note:

The Slack dialog also supports having an error array sent back as the response when the dialog is submitted. However, this functionality is currently not supported within System.CommonResponse components. Instead, you should handle custom validation and user feedback associated with validation errors in a custom component.