Slack

This document consists of:

  1. Slack in yellow.ai
  2. How to create an app on Slack
  3. How to configure a workspace
  4. How to add Slack to Direct message/Channel
  5. Slack APIs integration
  6. Slack features supported by yellow.ai

1. Introduction#

Slack is a workplace communication tool, “a single place for messaging, tools, and files.” This means Slack is an instant messaging system with lots of add-ins for other workplace tools. Slack has an intuitive UI with both group and person-to-person messaging. These are more than 1500 apps and allow users to create their own app, which has evolved Slack to become a one-stop-shop for a lot of users.

1.1 Slack Context Management#

Slack provides threaded messaging. It is important to understand how Yellow.ai platform handles context in channel, threads, and DM.

Channel#

  1. Bot will always reply in the respective thread.
  2. Each thread has an independent context, if multiple threads are activated by same/different person → bot will maintain individual context/flow for each thread. Same flow can be run in parallel on different threads.
  3. User profiles are preserved across channels, threads, and DMs, ensuring that the sender is always the same.

DM#

  1. Bot will always reply in 1-1 a conversation (without threads formation).
  2. Bot ignores thread formation for a better conversational experience.
  3. User profiles are preserved across channels, threads, and DMs, ensuring that the sender is always the same.

2. Create an App#

Follow the steps below to create an app on Slack:

  1. Visit https://api.slack.com/apps and click Create a new app.
  2. Enter app name and select an app development workspace.
  3. After creating the app, goto the event subscription on the left panel. Enable the event subscription and add request URL to https://app.yellowmessenger.com/integrations/slack/receive/ botID

  1. Scroll down to the event subscription section and expand Subscribe to bot events. Add the events scope according to your bot requirement.

Some of the common events- references.

  • Required Events:
Event NameDescription
app_home_openedUser clicked into your App Home tab
message.channels A message was posted to a channel
message.groupsA message was posted to a private channel
message.imA message was posted in a direct message channel
message.mpimA message was posted in a multiparty direct message channel
  1. Open OAuth & Permission. Add redirect URL: https://app.yellow.ai/integrations/oauth/redirect and Bot Token Scope according to your requirement.

Click here for scope references.

  • Required Bot Token Scopes:
- [channels:history](https://api.slack.com/scopes/channels:history) View messages and other content in public channels that App has been added.
- [chat:write ](https://api.slack.com/scopes/chat:write)Send messages as @yourBot.
- [commands](https://api.slack.com/scopes/commands) Add shortcuts and/or slash commands that people can use.
- [groups:history](https://api.slack.com/scopes/groups:history) View messages and other content in private channels that App has been added.
- [groups:read](https://api.slack.com/scopes/groups:read) View basic information about private channels that App has been added to.
- [im:history](https://api.slack.com/scopes/im:history) View messages and other content in direct messages that App has been added.
- [im:read](https://api.slack.com/scopes/im:read) View basic information about direct messages that App has been added to.
- [incoming-webhook](https://api.slack.com/scopes/incoming-webhook) Post messages to specific channels in Slack.
- [mpim:history](https://api.slack.com/scopes/mpim:history) View messages and other content in group direct messages that App has been added to.
- [mpim:read](https://api.slack.com/scopes/mpim:read) View basic information about group direct messages that App has been added to.
- [team:read](https://api.slack.com/scopes/team:read) View the name, email domain, and icon for workspaces App is connected to.
- [users:read](https://api.slack.com/scopes/users:read) View people in a workspace.

  1. Open Interactivity & Shortcuts, enable and add request URL to: https://app.yellowmessenger.com/integrations/slack/interaction/ botID

3. Configure Single/Multi-workspace#

Slack App can be built for both single workspace use cases (example, apps for a particular organisation) or app can be built for multi-tenant workspaces (example, apps for marketplace).

3.1 Single Workspace#

Slack app uses a bot access token (xoxb) to communicate with workspace users. A Bot access token is obtained when the slack workspace admin adds the app to their workspace.

Follow these steps to configure a single workspace:

  1. Open OAuth & Permissions, Click Install App to Workspace.

  1. Select a channel, incase you have enabled external incoming webhooks

  1. After installing the app in workspace, go back to OAuth & Permission. Copy the Bot Access token (xoxb- ).
  2. Head to Channels > Messaging > Slack > Select token type > Slack tokens > Add the Slack access token > Save.

3.2 Multiple Workspace#

Slack multi-workspace can be handled using the OAuth token, and YM bot will map the accessToken to the requesting workspace's teamId.

Follow the steps to configure multi-workspace:

  1. Open https://api.slack.com/apps/ > Basic Information on the left panel. Copy the Client ID & Client Secret.

  1. Open Channels > Messaging > Slack > Select token type > OAuth tokens > Add the Client ID, Client Secret, Scope, User Scope > Save.

  1. Store the accessToken of every workspace if you want to use Slack APIs. Set up a flow to capture your accessToken <> teamId mapping in the Bot Table:
  • Add a custom event slack-oauth-access-token in Event Hub. You will receive this event each time your app is added to a workspace and will have the following schema:
{
"event": {
"code": "slack-oauth-access-token",
"data": {
"appId": "A03********",
"teamId": "T03********",
"teamName": "Slack Bot Testing",
"accessToken": "xoxb-*************-***********-****************"
}
}
}
  • Using the above event, you can trigger a flow.
  • In the triggered flow, you can access the accessToken with {{data.event.data.accessToken}} and teamId with {{data.event.data.teamId}}.
  • Store the above 2 mappings in the Bot Table using the Database Node.
  1. You can install a multi-workspace App through OAuth flow, using the following link https://app.yellow.ai/integrations/slack/install/ botId

4. Adding Slack app to Direct Message/Channel#

After adding the Slack app to the workspace, you are required to add the app to a group or DM for testing or interacting with the bot.

  • Adding slack app to DM: Use the +button near Apps and select the app > Add > Messages , or search for the App using the top workspace search.

DM: Bot will reply in 1-1 conversation fashion (no threads will be formed).

  • Adding slack app to Group/Channel: Open Channel details > More > View App in channels. You can add/remove the app to the channel.

Group/Channel: Bot will reply in the threads and context will be mentioned within the respective threads.

5. API#

The Slack Web API is an interface for querying information from and enacting change in a Slack workspace. Reference: https://api.slack.com/methods

Bot access token

For single workspace configuration

  • You would already have the accessToken.

For multi-workspace configuration

  • As a pre-requisite, you should complete Step3 mentioned in Multi-workspace configuration.
  • For every user who interacts with the bot, you can fetch their teamId using sender. Sender would include [teamId]_[userId].
  • Using the teamId, you can fetch the relevant accessToken from the Bot Table.

5.1 Slash Commands#

Slash Commands allows users to invoke the app by typing a string into the message composer box. Slash commands are not sent as a message but as a command to the bot. E.g: /channel invite @bob to #tech Reference: https://api.slack.com/interactivity/slash-commands

Follow the below steps to add slash command:

  1. Goto https://api.slack.com/apps/ > Select you App > Select the Slash Commands in left panel > Create New Command.

  1. Fill the command, Description and add Request URL > SAVE Request URL: https://app.yellowmessenger.com/integrations/slack/shortcuts/ botID

  1. Enable slack-shortcuts event in Event Hub. If a flow is triggered using this event, the Event Payload can be accessed in builder using {{data.event.[]}}. Schema for this event would be:
{
"event": {
"code": "slack-shortcuts",
"data": {
"command": "/raiseticket",
"text": "pc is not working",
"message": "pc is not working",
"userId": "U01BXXX9A7"
}
}
}

5.2 Shortcuts#

Similar to Slash command, this is used to send commands to the bot. Shortcut can be initiated from the shortcuts button the message composer or from within search. Reference: https://api.slack.com/interactivity/shortcuts/using

Follow the given steps to add shortcuts:

  1. Open api.slack.com > Interactivity & Shortcuts > Create new Shortcut.

6. Supported slack features#

Yellow.ai supports the following slack features:

FeatureSupported?
2-way conversationyes
Outbound messagingno
Interactive Featuresno
Slash Commands/Shortcutsyes
Ephemeral Messageno
V2 Notification APIno