slack

package
v0.1.8-rc.21 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 28, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

README

Slack — Installation & Configuration Guide

This guide walks you through connecting Genie to your Slack workspace using Socket Mode (WebSocket-based — no public endpoint required).

Prerequisites

  • A Slack workspace where you have admin or app-management permissions.
  • Access to your Genie configuration file (.genie.toml).

Step 1: Create a Slack App

  1. Go to https://api.slack.com/apps and click Create New App.
  2. Choose From scratch.
  3. Enter an App Name (e.g., Genie Bot) and select your workspace.
  4. Click Create App.

Step 2: Enable Socket Mode

Socket Mode lets your app receive events over a WebSocket connection instead of requiring a public URL.

  1. In your app settings, navigate to Settings → Socket Mode.
  2. Toggle Enable Socket Mode to On.
  3. You will be prompted to generate an App-Level Token:
    • Give it a name (e.g., genie-socket).
    • Add the scope: connections:write.
    • Click Generate.
  4. Copy the generated token — it starts with xapp-. This is your app_token.

Step 3: Configure Bot Token Scopes

  1. Navigate to Features → OAuth & Permissions.
  2. Under Bot Token Scopes, add the following scopes:
Scope Purpose
chat:write Send messages as the bot
channels:history Read messages in public channels
groups:history Read messages in private channels
im:history Read direct messages
mpim:history Read group direct messages
users:read Look up user information

Tip: Add additional scopes as needed for your use case (e.g., files:read for file access).

Step 4: Subscribe to Events

  1. Navigate to Features → Event Subscriptions.
  2. Toggle Enable Events to On.
  3. Under Subscribe to bot events, add:
Event Description
message.channels Messages in public channels the bot is in
message.groups Messages in private channels the bot is in
message.im Direct messages to the bot
message.mpim Group DMs the bot is in
  1. Click Save Changes.

Step 5: Install the App to Your Workspace

  1. Navigate to Settings → Install App.
  2. Click Install to Workspace and authorize the requested permissions.
  3. Copy the Bot User OAuth Token — it starts with xoxb-. This is your bot_token.

Step 6: Configure Genie

Add the following to your .genie.toml configuration file:

[messenger]
platform = "slack"

[messenger.slack]
app_token = "xapp-1-A0XXXXXXXXX-0000000000000-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
bot_token = "xoxb-0000000000000-0000000000000-XXXXXXXXXXXXXXXXXXXXXXXX"

Security: Store tokens securely. You can also use environment variables by referencing them in your deployment configuration.

Step 7: Invite the Bot to Channels

Before Genie can respond in a channel, the bot must be invited:

  1. Open the desired Slack channel.
  2. Type /invite @Genie Bot (or whatever you named your app).
  3. Alternatively, mention @Genie Bot — Slack will prompt you to invite it.

For direct messages, simply open a DM with the bot — no invitation is needed.

Verification

After starting Genie, you should see the log message:

connected to Slack via Socket Mode

Send a message to the bot in Slack to confirm everything is working.

Troubleshooting

Issue Solution
slack.app_token should start with xapp- Ensure you copied the App-Level Token, not the Bot Token.
slack.bot_token should start with xoxb- Ensure you copied the Bot User OAuth Token from the Install App page.
Bot doesn't respond in a channel Make sure the bot has been invited to the channel.
No events received Verify Socket Mode is enabled and the correct event subscriptions are configured.
socket mode connection error Check that your app_token has the connections:write scope.

Required Tokens Summary

Token Format Where to Find
app_token xapp-… Settings → Socket Mode → App-Level Token
bot_token xoxb-… Settings → Install App → Bot User OAuth Token

Documentation

Overview

Package slack provides a DataSource connector that enumerates Slack channel messages for vectorization. It uses the Slack Web API (conversations.history) and requires a bot token with channels:history and channels:read.

Package slack provides a Messenger adapter for the Slack platform.

This file implements the HTTP Events API handler (eventsHTTPHandler), enabling Slack to receive events via HTTP push instead of Socket Mode. This allows the adapter to be mounted on a shared HTTP mux at a context path (e.g., /agents/{name}/slack/events) rather than requiring its own WebSocket connection or dedicated port.

The Events API is Slack's recommended approach for production apps that have a publicly accessible endpoint. It delivers events as signed HTTP POST requests. See: https://api.slack.com/events-api

Package slack provides a Messenger adapter for the Slack platform using Socket Mode for bi-directional communication without a public endpoint.

The adapter wraps github.com/slack-go/slack and its Socket Mode client. Incoming events are received over a WebSocket connection, and outgoing messages are sent via the Slack Web API.

Transport: Socket Mode (WebSocket — no public endpoint required).

Authentication

Two tokens are required:

  • An app-level token (xapp-…) with the connections:write scope for Socket Mode.
  • A bot user OAuth token (xoxb-…) with chat:write and other desired scopes.

Usage 

m := slack.New(slack.Config{
	AppToken: os.Getenv("SLACK_APP_TOKEN"),
	BotToken: os.Getenv("SLACK_BOT_TOKEN"),
})
if err := m.Connect(ctx); err != nil { /* handle */ }
defer m.Disconnect(ctx)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterSlackConnector 

func RegisterSlackConnector(api *slack.Client)

RegisterSlackConnector registers the slack connector with the datasource package.

Types

type Config 

type Config struct {
	// AppToken is the Slack app-level token (xapp-...) required for Socket Mode.
	// Not needed when using HTTP Events API mode (SigningSecret + SharedMux).
	AppToken string
	// BotToken is the Slack bot user OAuth token (xoxb-...).
	BotToken string
	// SigningSecret is used to verify incoming HTTP Events API requests.
	// When set together with WithSharedMux(), the adapter operates in HTTP
	// push mode instead of Socket Mode: incoming events arrive as signed
	// HTTP POST requests rather than over a WebSocket connection.
	// See: https://api.slack.com/authentication/verifying-requests-from-slack
	SigningSecret string
	// APIURL allows overriding the base URL for Slack API requests.
	// Used primarily to mock the Slack API during testing.
	APIURL string
}

Config holds Slack-specific configuration.

type Messenger 

type Messenger struct {
	// contains filtered or unexported fields
}

Messenger implements the messenger.Messenger interface for Slack. It supports two transport modes:

  • Socket Mode (default): outbound WebSocket, no public endpoint required.
  • HTTP Events API: inbound HTTP push, requires SigningSecret + SharedMux.

It manages the event routing, incoming message buffer, and connection state through an internal mutex.

func New 

func New(cfg Config, respondTo string, allowedUsers []string, opts ...messenger.Option) *Messenger

New creates a new Slack Messenger with the given config and options.

func (*Messenger) Connect 

func (m *Messenger) Connect(ctx context.Context) (http.Handler, error)

Connect establishes a connection to Slack and returns an optional http.Handler.

In HTTP Events API mode (SigningSecret set): returns a non-nil handler that the caller mounts at a context path. Events arrive as signed HTTP POST requests.

In Socket Mode (default): returns nil handler and opens an outbound WebSocket connection. No inbound HTTP required.

func (*Messenger) ConnectionInfo 

func (m *Messenger) ConnectionInfo() string

ConnectionInfo returns connection instructions for the Slack adapter.

func (*Messenger) Disconnect 

func (m *Messenger) Disconnect(ctx context.Context) error

Disconnect gracefully shuts down the Slack connection.

func (*Messenger) FormatApproval 

func (m *Messenger) FormatApproval(req messenger.SendRequest, info messenger.ApprovalInfo) messenger.SendRequest

FormatApproval builds a Slack Block Kit message for an approval notification. This satisfies the messenger.ApprovalFormatter interface, keeping all Slack-specific formatting inside the Slack adapter.

func (*Messenger) FormatClarification 

func (m *Messenger) FormatClarification(req messenger.SendRequest, info messenger.ClarificationInfo) messenger.SendRequest

FormatClarification builds a Slack Block Kit message for a clarification question.

func (*Messenger) Platform 

func (m *Messenger) Platform() messenger.Platform

Platform returns the Slack platform identifier.

func (*Messenger) Receive 

func (m *Messenger) Receive(_ context.Context) (<-chan messenger.IncomingMessage, error)

Receive returns a channel of incoming messages from Slack.

func (*Messenger) Send 

func (m *Messenger) Send(ctx context.Context, req messenger.SendRequest) (messenger.SendResponse, error)

Send delivers a message to a Slack channel or thread. If req.Type is SendTypeReaction, adds an emoji reaction to the message identified by ReplyToMessageID (format "channelID:ts"). If req.Metadata["blocks"] contains a []slack.Block, the message is sent with Block Kit formatting.

func (*Messenger) UpdateMessage 

func (m *Messenger) UpdateMessage(ctx context.Context, req messenger.UpdateRequest) error

UpdateMessage replaces the content of a previously sent Slack message using the chat.update API. Used to disarm approval/clarification buttons after resolution (e.g. replacing buttons with "✅ Approved by @user").

The MessageID must be in the "channelID:timestamp" format returned by Send. If Metadata["blocks"] is set, the blocks are used for the update.

type SlackConnector 

type SlackConnector struct {
	// contains filtered or unexported fields
}

SlackConnector implements datasource.DataSource for Slack channels. It fetches conversation history for each channel in scope and returns normalized items (one per message) for the sync pipeline to vectorize.

func NewSlackConnector 

func NewSlackConnector(api *slack.Client) *SlackConnector

NewSlackConnector returns a DataSource that lists messages from Slack channels. The caller must provide an authenticated slack.Client (e.g. from slack.New(botToken)); the connector uses conversations.history and does not connect via Socket Mode.

func (*SlackConnector) ListItems 

func (c *SlackConnector) ListItems(ctx context.Context, scope datasource.Scope) ([]datasource.NormalizedItem, error)

ListItems fetches messages from each channel in scope.SlackChannelIDs and returns them as NormalizedItems. Each message becomes one item with ID "slack:channelID:timestamp" and content equal to the message text.

func (*SlackConnector) Name 

func (c *SlackConnector) Name() string

Name returns the source identifier for Slack.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.