Set up Slack chat

This guide covers connecting a Slack workspace so people can ask Heplon questions in a direct message in Slack.

Every answer is produced using the entire system graph of Heplon, as well as live data from connectors that the asking user has permission to use in Heplon.

What you need

A tenant admin account and the tenant's Heplon URL.
Permission to create an app in your Slack workspace.

1. Create the Slack app from the manifest

Heplon connects to Slack over Socket Mode: our Heplon instance dials out to Slack.

A Socket Mode app cannot be listed in the Slack App Directory, so you need to create an app for Heplon.

Go to api.slack.com/apps, select Create New App, then From a manifest, choose your workspace, and paste this:

{
  "display_information": {
    "name": "Heplon",
    "description": "Ask about your systems: who owns a service, what runs where, why a deploy failed.",
    "background_color": "#101014"
  },
  "features": {
    "bot_user": {
      "display_name": "Heplon",
      "always_online": false
    },
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    }
  },
  "oauth_config": {
    "scopes": {
      "bot": ["im:history", "im:read", "im:write", "chat:write"]
    }
  },
  "settings": {
    "event_subscriptions": {
      "bot_events": ["message.im"]
    },
    "interactivity": {
      "is_enabled": false
    },
    "org_deploy_enabled": false,
    "socket_mode_enabled": true,
    "token_rotation_enabled": false
  }
}

Select Create, then Install to Workspace on the app's Basic Information page and approve the permissions.

2. Collect the two tokens

Heplon needs two credentials, which do different jobs.

The bot token is used by Heplon to post replies to user questions. On OAuth & Permissions, copy the Bot User OAuth Token — it starts with xoxb-.

The app-level token opens the connection from Heplon to Slack. On Basic Information → App-Level Tokens, select Generate Token and Scopes, give it any name, add the connections:write scope, and generate it. Copy the token — it starts with xapp- and is shown only once.

You also need the workspace id: the T… value in your workspace's Slack URL (https://app.slack.com/client/T0123ABCD/…), or from About this workspace.

3. Register the adapter in Heplon

curl -X POST "$HEPLON_URL/api/v1/chat-adapters" \
  -H "Authorization: Bearer $HEPLON_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "platform": "slack",
    "workspace": "T0123ABCD",
    "app_token": "xapp-…",
    "bot_token": "xoxb-…"
  }'

Using it

Send the bot a direct message. It answers in a thread under your question; replying in that thread continues the same conversation, and the follow-up keeps the context of what came before. Starting a new message starts a new conversation.

#Set up Slack chat

#What you need

#1. Create the Slack app from the manifest

#2. Collect the two tokens