Slack Chatbot Setup Guide

Moveworks is an Agentic AI Platform that gives your employees one AI Assistant that can find answers, automate tasks & boost productivity. To do this, Moveworks needs access to the Slack environment. This document walks through the steps to successfully implement and integrate the Moveworks AI Assistant in Slack. The exact access requirements are outlined under step 3 in the manifest JSON file.

Note: Bot will refer to Slack specific steps and AI Assistant is used for Moveworks steps.

Account Needs

Moveworks requires the bot token and signing secret for your AI Assistant created by an admin on your Slack production environment.

Bot Creation

1. Navigate to https://api.slack.com/apps, click Create New App and choose From an app manifest

2. Select the appropriate workspace

3. Copy the code block on the following page into the JSON tab. If you know the name of your AI Assistant already, change the values for display_information.name and features.bot_user.display_name. There are three URLs that are set as placeholders (https://app.moveworks.ai/Bxxxxx/slack/*). These will be updated in the next step after the bot is created to generate the Bot ID. Note: This App Manifest would update the details on the UI, please do validate them on the respective pages.

   {
       "_metadata": {
           "major_version": 1,
           "minor_version": 1
       },
       "display_information": {
           "name": "MoveworksBot",
           "description": "I'm MoveworksBot an AI trained by the IT team"
       },
       "features": {
           "app_home": {
               "home_tab_enabled": false,
               "messages_tab_enabled": true,
               "messages_tab_read_only_enabled": false
           },
           "bot_user": {
               "display_name": "MoveworksAIAssistant",
               "always_online": true
           }
       },
       "oauth_config": {
           "scopes": {
               "bot": [
                   "im:history",
                   "chat:write",
                   "chat:write.customize",
                   "im:read",
                   "im:write",
                   "team:read",
                   "users:read",
                   "users:read.email",
                   "app_mentions:read",
                   "users.profile:read",
                   "channels:history",
                   "channels:read",
                   "groups:history",
                   "groups:read",
                   "reactions:read",
                   "reactions:write",
                   "emoji:read",
                   "mpim:history",
                   "mpim:read",
                   "files:read",
   								"usergroups:read"
               ]
           }
       },
       "settings": {
           "event_subscriptions": {
               "request_url": "https://app.moveworks.ai/Bxxxxx/slack/events",
               "bot_events": [
                   "message.im",
                   "member_joined_channel",
                   "member_left_channel",
                   "message.channels",
                   "message.groups",
                   "message.mpim",
                   "reaction_added",
                   "reaction_removed"
               ]
           },
           "interactivity": {
               "is_enabled": true,
               "request_url": "https://app.moveworks.ai/Bxxxxx/slack/actions",
               "message_menu_options_url": "https://app.moveworks.ai/Bxxxxx/slack/select_options"
           },
           "org_deploy_enabled": true,
           "socket_mode_enabled": false,
           "is_hosted": false
       }
   }

4. Reveal the Signing Secret and save this value. It will need to be added in Moveworks Setup in a later step.

5. Only If installing on Slack Enterprise Grid, click on Org Level Apps and opt-in to the Org apps program if not already opted in. Next, click Install App. This will direct you to an Authorize page if you are properly logged in as an admin. Click on Authorize to continue.

6. After authorizing the bot app, two tokens will appear under OAuth & Permissions → Tokens for Your Workspace. The Bot User OAuth Access Token is the required bot token to get all the required information for later chatbot setup.

   

   1. Please note that the token must start with xoxb and NOT xoxp.
   2. If you are installing the bot in a single workspace, it will say Access Level: Workspace under the token.
   3. If installed in Slack Enterprise Grid, it will say Access Level: Org.

7. Retrieve Bot information

   1. Get an API querying tool like Postman or prepare to query Slack APIs with curl from a terminal interface
   2. Query the following endpoint to get your bot information:
      curl

      curl --location 'https://slack.com/api/auth.test' \
      --header 'Authorization: Bearer xoxb-bot70k3N'

   3. You will get a response like the following, note the values as they will be needed later during the AI assistant setup. Especially the bot_id which needs to be updated in the App Manifest step above.
      JSON

      {
          "ok": true,
          "url": "https://org.slack.com/",
          "team": "org",
          "user": "ai-assitant-name",
          "team_id": "T123MW45" OR "E123MW45",
          "user_id": "U123MW45",
          "bot_id": "Bxxxxx",
          "is_enterprise_install": false or true
      }

   4. If your team_id starts with an E, you are using Enterprise Grid and will need to make an additional call:
      curl

      curl --location 'https://slack.com/api/auth.teams.list?limit=1000' \
      --header 'Authorization: Bearer xoxb-bot70k3N'

   5. The response will look like below :
      JSON

      {
          "ok": true,
          "teams": [
              {
                  "id": "T123MW45",
                  "name": "org"
              }
          ]
      }

      1. If you are using Enterprise Grid, you might notice there are multiple Teams listed in the response. Note : Here one of the team_ids would belong to the entire workspace. Setting up the Slack ChatBot with that ID would enable the bot in both Workspaces.
         JSON

         {
             "ok": true,
             "teams": [
                 {
                     "id": "T123MW45",
                     "name": "CS Org"
                 },
                 {
                     "id": "T098MW78",
                     "name": "All Company"
                 },
             ]
         }

   6. Note the team ID, this will be needed later when setting up the AI assistant config.

8. Under Interactivity & Shortcuts, ensure the correct Request URL (https://app.moveworks.ai/Bxxxxx/slack/actions) and the Options Load URL (https://app.moveworks.ai/Bxxxxx/slack/select_options ) has been generated making sure the Bxxxxx from the template URL has been replaced with your bot ID.

   1. This was updated when the BOT ID was added to the manifest since it runs an upwards sync.

9. Under Event Subscriptions, enter the Request URL e.g: https://app.moveworks.ai/Bxxxxx/slack/events making sure to replace Bxxxxx from the template URL with the bot ID of your bot.

   1. The link will not be editable in the display field. Click the change button to display the change field.

   

   1. Copy the existing link or the example above into the change field
   2. Ensure that you change the placeholder with your Bot ID

Additional Steps for Slack Enterprise Grid customers

1. Navigate to the Slack Admin console and select which workspaces to install the AI Assistant. Select Default for future workspaces so all new workspaces will have access to the app.
2. Confirm by clicking Add App

Moveworks Setup

You will need access to Moveworks setup. If you have not already created an SSO connection to your org, please contact your customer success team.

Slack Connector and Identity Setup

1. In Moveworks Setup navigate to Connectors -> Built-in Connectors.

   

2. Click Create New and choose the Slack option to create a new connector. Click Next: Add Creds

   

3. In the credentials step

   1. Name the connector. Recommendation is just slack
   2. Add a new workspace by clicking the plus button
   3. In the first field under Workspace Team ID input the Team ID you got from the Slack API call earlier
   4. In the second field under Workspace-specific Bot Token, input your bot token that starts with xoxb
   5. Click Save

4. In the left hand navigation menu proceed to User Identity -> Import Users

   1. If you do not already have your primary identity service set up, please refer to the documentation for it.
   2. Edit the import user config, in the next page add a new entry by clicking the + Add Source button
   3. In the dropdown that appears add the connector you just created called Slack.
   4. Proceed through the steps and save user import with your slack connector as a new source of user identity.

Chatbot Setup

1. In the left hand navigation menu, search for Manage Chatbots
2. Click Create
3. In the Channel dropdown choose slack
4. In the Select Connector dropdown choose your slack connector.
5. In Bot ID, paste the Bot ID you got from https://slack.com/api/auth.test

6. In Bot Name, input the name of the bot <org-slack> where org is your instance’s canonical name
7. You can confirm your org name in 2 ways:
   1. Referring to the subdomain of your moveworks url when logging into myMoveworks (org.moveworks.com)
   2. The redirect url of your myMoveworks sso configuration
8. Bot Friendly Name can be any string, but must be filled in, this is the name your end users will use to interact with it.
9. In the Channel Configurations drop down choose Slack Vars
10. Fill in the subsequently populated information from the auth test api or your slack app page at api.slack.com
    You will only need to add the Slack Workspace Signing Secret here.

11. Slack Region should be set to either Commercial or Gov based on your Slack instance.
12. Click Save and name your config title after your Bot Name value

FAQ

Q: Can I grant access to single-channel guests and/or multi-channel guests in addition to my full members? A: Yes, Moveworks will ingest all active members and guests from your workspace/org, provided they have access to the Slack app itself. Learn more about Slack guest policies for apps here

Q: Can I make the Moveworks bot a default app that shows in all user’s sidebars, instead of having them search for it? A: Slack does not allow admins to set default “starred” apps in user’s Slack client sidebars. We recommend leveraging the Employee Communications platform to send campaigns reminding users to “star” the Moveworks AI Assistant, so it always shows up in the sidebar.