Slack Bot Setup Guide

Prerequisites

• Ensure Node.js and Yarn are installed on your machine.
• You need a Slack workspace where you can set up a bot.

---

Steps to Run the Code

1. Clone the Repository

Clone the repository where your code is hosted.

git clone <repository-url>
cd <repository-folder>

---

2. Install Dependencies

Run the following command to install the project dependencies using Yarn.

yarn install

---

3. Run the Development Server

To start the development server, use the following command:

yarn run start:dev

This will run the application locally. The server should now be available on http://localhost:3000 (or whichever port is specified in your configuration).

---

4. Install Ngrok

Install Ngrok to expose your local server to the internet.

1. Install Ngrok via Homebrew (MacOS) or download directly from Ngrok.

   For MacOS:

   brew install ngrok

2. Sign up for an Ngrok account (if you haven't already), and get your authentication token from Ngrok's dashboard.

3. Authenticate Ngrok with your account token:

   ngrok authtoken <your-auth-token>

4. Start Ngrok to tunnel HTTP traffic on your local server’s port (typically port 3000):

   ngrok http 3000

   Ngrok will now provide a public URL that you can use for your Slack bot’s interactivity endpoint (e.g., https://<your-ngrok-id>.ngrok.io).

---

5. Set Up Slack Bot

Follow these steps to set up a Slack Bot for interactivity:

1. Go to Slack API and click on “Create New App”.
2. Choose the Slack workspace you want to install the bot in.
3. App Permissions:
   • Add Scopes under Bot Token Scopes such as chat:write, commands, users:read, and interactivity:write.
   • Under User Token Scopes, you can add additional permissions like users:read if needed.
4. Install the App to Workspace: Install the app and grant it necessary permissions.

---

6. Grab Slack Bot ID

1. Go to OAuth & Permissions in your Slack App settings.
2. Copy the Bot User OAuth Token. This is the token you will use to interact with the Slack API. Example: xoxb-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXX
3. Set up .env file with SLACK_BOT_TOKEN=xoxb-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXX.

---

7. Grab Slack User ID

To grab the Slack User ID of the user you wish to send messages to:

1. Use the Slack API to get the user ID by calling the users.list endpoint, or from Slack’s interface by typing /whois @username in a channel.
2. Example: If you have a user @john.doe, your user ID might look something like U08DAUKQ8KZ.
3. Paste your user ID in .env on SLACK_USER_ID.

---

8. Set Up Slack Interactivity Endpoint

Set the Interactivity Endpoint to your Ngrok URL:

1. In your Slack App settings, go to Interactivity & Shortcuts.
2. Turn on Interactivity and enter your Ngrok URL followed by the route for interactions (e.g., https://<your-ngrok-id>.ngrok.io/slack/forms/interaction).

Now Slack will send interaction events (like button clicks, menu selections, etc.) to your server’s endpoint.

---

9. Send POST Request to API

To send a POST request to your API, such as sending a form to a user, use the following:

Example: Sending Form Data

To send a form to a specific user:

1. POST Request to /slack/forms/send

   curl -X POST \
   https://<your-ngrok-id>.ngrok.io/slack/forms/send \
   -H "Content-Type: application/json" \
   -d '{
         "userId": "your-user-id"
       }'

   This will send the form to the user with the given Slack user ID.

Example: Receiving Interaction Data

2. POST Request to /slack/forms/interaction

   After the user interacts with your form (e.g., selects an option or submits the form), Slack will make a request to your /slack/forms/interaction endpoint with the interaction data.

   Your server should handle the request, and you can access the data in your endpoint handler. An example interaction payload might look like this:

   {
     "type": "block_actions",
     "user": {
       "id": "U08DAUKQ8KZ",
       "username": "john.doe"
     },
     "actions": [
       {
         "action_id": "task-001",
         "selected_option": {
           "value": "in-progress"
         }
       }
     ]
   }

   You can process this data to determine which actions the user has taken.

---

10. Handling Responses

Ensure that your server is properly responding to Slack's requests, including:

• Sending a confirmation message: After successfully sending the form or receiving an interaction, you should respond with appropriate messages to Slack's API (e.g., ok: true in JSON response).

  Example for sending a response after processing the interaction:

  {
    "response_action": "update",
    "view": {
      "type": "modal",
      "callback_id": "modal-001",
      "state": {
        "values": {
          "task-001": {
            "selected_option": {
              "value": "in-progress"
            }
          }
        }
      }
    }
  }

---

Key Endpoints:

• /slack/forms/send: Send a form to a specific user using their Slack User ID.
• /slack/forms/interaction: Handle user interactions with the form (such as button clicks, selections, etc.).