Slack integration development

Slack integration enables users to get notifications about various events from Tolgee like key creation, translation edition, imports. It also has some controlling elements that the platform can handle.

Workspace authorization

There are two ways, how workspaces are authorized to Slack. The first is with global bot token for single workspace or via oAuth to multiple workspaces.

Single workspace authorization

To make the Tolgee platform work with a single workspace, you can use the bot token, generated via Slack API Apps dashboard. There, you can select Settings -> Install App. You have to provide this token as tolgee.slack.token configuration option.

This configuration is the preferred way for self-hosted instances. In most cases self-hosted instances don't need to connect to multiple slack workspaces.

Multi workspace authorization

To make the Tolgee platform work with multiple workspaces, you have to set up the authorization via oAuth. In that case, for each workspace, Tolgee will have to store its own bot Token in the Tolgee Platform database. To do this, you will need to setup the oAuth client-id, and client-secret.

Setup

1. Crate the App in Slack API Apps dashboard

2. Provide signing-secret obtainable in the Basic information page of the Slack app dashboard as tolgee.slack.signing-secret configuration param in application-dev.yaml

3. Choose option 1 or 2 as the next step.

   1. option Setup with single workspace (simple)

      1. Get the bot token xoxo-... from the Settings -> Install App of the Slack app dashboard
      2. Provide the token as tolgee.slack.token configuration option
      3. Add bot token scopes in the OAuth & Permissions section of the Slack app dashboard: channels:read, chat:write, commands, users:read.

   2. option Setup for multiple workspaces (advanced)

      1. Get the client-id and client-secret from OAuth & Permissions section of the Slack app dashboard and provide it as tolgee.slack.client-id and tolgee.slack.client-secret in application-dev.yaml
      2. Get your front end publicly reachable using https (Slack requires this). We are using ngrok configuration for this:

      version: 2
      authtoken: <your token>
      tunnels:
        backend:
          proto: http
          addr: 8080
          domain: tolgee-backend-<name>.ngrok.dev
        frontend:
          proto: http
          addr: 8081
          domain: tolgee-frontend-<name>.ngrok.dev
      

      It requires a paid ngrok plan, but there are other ways around it.

      3. Setup redirect URL in OAuth & Permissions section of the Slack app dashboard. Set it to the public frontend URL https://tolgee-frontend-<name>.ngrok.dev
      4. In Event Subscriptions of the Slack app dashboard, set a Request URL to backend path /v2/public/slack/on-bot-event e.g. https://tolgee-backend-<your name>.ngrok.dev/v2/public/slack/on-bot-event. To complete this step, your backend has to be running so Slack can verify the configuration.
      5. Also, in the Event Subscriptions of the Slack app dashboard add app_uninstalled event in Subscribe to bot events.

4. In Slash commands page of the Slack app dashboard, add new slash command with these values

   Command: /tolgee
   Request URL: <The backend `/v2/public/slack` endpoint url. E.g., `https://tolgee-backend-<name>.ngrok.dev/v2/public/slack`>
   Short Description: Executes tolgee commands
   Usage Hint: [command]
   

5. In the Interactivity & Shortcuts set Interactivity request url to /v2/public/slack/on-event backend endpoint. E.g., https://tolgee-backend-<name>.ngrok.dev/v2/public/slack/on-event>

6. 🚀 You're done!