slack

README

Joe Bot - Slack Adapter

Connecting joe with the Slack chat application. https://github.com/go-joe/joe

---

This repository contains a module for the Joe Bot library.

Getting Started

This library is packaged as Go module. You can get it via:

go get github.com/go-joe/slack-adapter

Example usage

In order to connect your bot to slack you can simply pass it as module when creating a new bot:

package main

import (
	"os"

	"github.com/go-joe/joe"
	"github.com/go-joe/slack-adapter/v2"
)

func main() {
	b := joe.New("example-bot",
		slack.Adapter(os.Getenv("SLACK_TOKEN")),
		…
    )
	
	b.Respond("ping", Pong)

	err := b.Run()
	if err != nil {
		b.Logger.Fatal(err.Error())
	}
}

If you want to use the Slack Events API you need to call the slack.EventsAPIAdapter(…) function instead.

The adapter will emit the following events to the robot brain:

• joe.ReceiveMessageEvent
• joe.UserTypingEvent
• reactions.Event

Built With

• slack-go/slack - Slack API in Go
• zap - Blazing fast, structured, leveled logging in Go
• testify - A simple unit test library

Contributing

The current implementation is rather minimal and there are many more features that could be implemented on the slack adapter so you are highly encouraged to contribute. If you want to hack on this repository, please read the short CONTRIBUTING.md guide first.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Friedrich Große - Initial work - fgrosse

See also the list of contributors who participated in this project.

License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

Documentation

Overview

Package slack implements a slack adapter for the joe bot library.

Index

• func Adapter(token string, opts ...Option) joe.Module
• func EventsAPIAdapter(listenAddr, token, verificationToken string, opts ...Option) joe.Module
• func SocketModeAdapter(token, appToken, verificationToken string, opts ...Option) joe.Module
• type BotAdapter
  • func NewAdapter(ctx context.Context, conf Config) (*BotAdapter, error)
  • func (a *BotAdapter) Close() error
  • func (a *BotAdapter) React(reaction reactions.Reaction, msg joe.Message) error
  • func (a *BotAdapter) RegisterAt(brain *joe.Brain)
  • func (a *BotAdapter) Send(text, channelID string) error
• type Config
• type EventsAPIConfig
• type EventsAPIServer
  • func NewEventsAPIServer(ctx context.Context, listenAddr string, conf Config) (*EventsAPIServer, error)
  • func (a *EventsAPIServer) Close() error
  • func (a *EventsAPIServer) RegisterAt(brain *joe.Brain)
• type Option
  • func WithDebug(debug bool) Option
  • func WithListenPassive() Option
  • func WithLogUnknownMessageTypes() Option
  • func WithLogger(logger *zap.Logger) Option
  • func WithMessageParams(params slack.PostMessageParameters) Option
  • func WithMiddleware(mw func(next http.Handler) http.Handler) Option
  • func WithReadTimeout(d time.Duration) Option
  • func WithTLS(certFile, keyFile string) Option
  • func WithTLSConfig(tlsConf *tls.Config) Option
  • func WithTimeouts(d time.Duration) Option
  • func WithWriteTimeout(d time.Duration) Option
• type SocketModeConfig
• type SocketModeServer
  • func NewSocketModeServer(ctx context.Context, conf Config) (*SocketModeServer, error)
  • func (a *SocketModeServer) Close() error
  • func (a *SocketModeServer) RegisterAt(brain *joe.Brain)

Functions

func Adapter

func Adapter(token string, opts ...Option) joe.Module

Adapter returns a new BotAdapter as joe.Module.

Apart from the typical joe.ReceiveMessageEvent event, this adapter also emits the joe.UserTypingEvent. The ReceiveMessageEvent.Data field is always a pointer to the corresponding github.com/slack-go/slack.MessageEvent instance.

func EventsAPIAdapter

func EventsAPIAdapter(listenAddr, token, verificationToken string, opts ...Option) joe.Module

EventsAPIAdapter returns a new EventsAPIServer as joe.Module. If you want to use the slack RTM API instead (i.e. using web sockets), you should use the slack.Adapter(…) function instead.

func SocketModeAdapter

func SocketModeAdapter(token, appToken, verificationToken string, opts ...Option) joe.Module

SocketModeAdapter returns a new SocketModeServer as joe.Module. If you want to use the slack RTM API instead (i.e. using web sockets), you should use the slack.Adapter(…) function instead. If you want to use the EventsAPI instead (receiving events through HTTPS), you should use the slack.EventsAPIAdapter(...) function instead.

Types

type BotAdapter

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

BotAdapter implements a joe.Adapter that reads and writes messages to and from Slack using the RTM API.

func NewAdapter

func NewAdapter(ctx context.Context, conf Config) (*BotAdapter, error)

NewAdapter creates a new *BotAdapter that connects to Slack using the RTM API. Note that you will usually configure the slack adapter as joe.Module (i.e. using the Adapter function of this package).

You need to close the adapter if it has been created without error in order to release the connection to the Slack RTM API.

func (*BotAdapter) Close

func (a *BotAdapter) Close() error

Close disconnects the adapter from the slack API.

func (*BotAdapter) React

func (a *BotAdapter) React(reaction reactions.Reaction, msg joe.Message) error

React implements joe.ReactionAwareAdapter by letting the bot attach the given reaction to the message.

func (*BotAdapter) RegisterAt

func (a *BotAdapter) RegisterAt(brain *joe.Brain)

RegisterAt implements the joe.Adapter interface by emitting the slack API events to the given brain.

func (*BotAdapter) Send

func (a *BotAdapter) Send(text, channelID string) error

Send implements joe.Adapter by sending all received text messages to the given slack channel ID.

type Config

type Config struct {
	Token             string
	AppToken          string
	VerificationToken string
	Name              string
	Debug             bool
	Logger            *zap.Logger
	SlackAPIURL       string // defaults to github.com/slack-go/slack.APIURL but can be changed for unit tests

	// SendMsgParams contains settings that are applied to all messages sent
	// by the BotAdapter.
	SendMsgParams slack.PostMessageParameters

	// Log unknown message types as error message for debugging. This option is
	// disabled by default.
	LogUnknownMessageTypes bool

	// Listen and respond to all messages not just those directed at the Bot User.
	ListenPassive bool

	// Options if you want to use the Slack Events API. Ignored on the normal RTM adapter.
	EventsAPI EventsAPIConfig

	// Options if you want to use the Slack Events API. Ignored on the normal RTM adapter.
	SocketMode SocketModeConfig
}

Config contains the configuration of a BotAdapter.

type EventsAPIConfig

type EventsAPIConfig struct {
	Middleware        func(next http.Handler) http.Handler
	ShutdownTimeout   time.Duration
	ReadTimeout       time.Duration
	WriteTimeout      time.Duration
	TLSConf           *tls.Config
	CertFile, KeyFile string
}

EventsAPIConfig contains the configuration of an EventsAPIServer.

type EventsAPIServer

type EventsAPIServer struct {
	*BotAdapter
	// contains filtered or unexported fields
}

EventsAPIServer is an adapter that receives messages from Slack using the events API. In contrast to the classical adapter, this server receives messages as HTTP requests instead of via a websocket.

See https://api.slack.com/events-api

func NewEventsAPIServer

func NewEventsAPIServer(ctx context.Context, listenAddr string, conf Config) (*EventsAPIServer, error)

NewEventsAPIServer creates a new *EventsAPIServer that connects to Slack using the events API. Note that you will usually configure this type of slack adapter as joe.Module (i.e. using the EventsAPIAdapter function of this package).

func (*EventsAPIServer) Close

func (a *EventsAPIServer) Close() error

Close shuts down the disconnects the adapter from the slack API.

func (*EventsAPIServer) RegisterAt

func (a *EventsAPIServer) RegisterAt(brain *joe.Brain)

RegisterAt implements the joe.Adapter interface by emitting the slack API events to the given brain.

type Option

type Option func(*Config) error

An Option is used to configure the slack adapter.

func WithDebug

func WithDebug(debug bool) Option

WithDebug enables debug messages of the slack client.

func WithListenPassive

func WithListenPassive() Option

WithListenPassive makes the adapter listen and respond to all messages not just those directed at it

func WithLogUnknownMessageTypes

func WithLogUnknownMessageTypes() Option

WithLogUnknownMessageTypes makes the adapter log unknown message types as error message for debugging. This option is disabled by default.

func WithLogger

func WithLogger(logger *zap.Logger) Option

WithLogger can be used to inject a different logger for the slack adapater.

func WithMessageParams

func WithMessageParams(params slack.PostMessageParameters) Option

WithMessageParams overrides the default parameters that are used when sending any message to slack.

func WithMiddleware

func WithMiddleware(mw func(next http.Handler) http.Handler) Option

WithMiddleware is an option for the EventsAPIServer that allows the user to inject an HTTP middleware to the HTTP server.

func WithReadTimeout

func WithReadTimeout(d time.Duration) Option

WithReadTimeout is an option for the EventsAPIServer that sets the servers maximum duration for reading the entire HTTP request, including the body.

func WithTLS

func WithTLS(certFile, keyFile string) Option

WithTLS is an option for the EventsAPIServer that enables serving HTTP requests via TLS.

func WithTLSConfig

func WithTLSConfig(tlsConf *tls.Config) Option

WithTLSConfig is an option for the EventsAPIServer that can be used in combination with the WithTLS(…) option to configure the HTTPS server.

func WithTimeouts

func WithTimeouts(d time.Duration) Option

WithTimeouts is an option for the EventsAPIServer that sets both the read and write timeout of the HTTP server to the same given value.

func WithWriteTimeout

func WithWriteTimeout(d time.Duration) Option

WithWriteTimeout is an option for the EventsAPIServer that sets the servers maximum duration before timing out writes of the HTTP response.

type SocketModeConfig

type SocketModeConfig struct {
	//Middleware        func(next http.Handler) http.Handler
	ShutdownTimeout time.Duration
	ReadTimeout     time.Duration
	WriteTimeout    time.Duration
}

SocketModeConfig contains the configuration of an SocketModeServer.

type SocketModeServer

type SocketModeServer struct {
	*BotAdapter
	SocketMode *socketmode.Client
	// contains filtered or unexported fields
}

SocketModeServer is an adapter that receives messages from Slack using socket mode.

See https://api.slack.com/apis/connections/socket

func NewSocketModeServer

func NewSocketModeServer(ctx context.Context, conf Config) (*SocketModeServer, error)

NewSocketModeServer creates a new *SocketModeServer that connects to Slack using socket mode (websockets). Note that you will usually configure this type of slack adapter as joe.Module (i.e. using the SocketModeAdapter function of this package).

func (*SocketModeServer) Close

func (a *SocketModeServer) Close() error

Close shuts down the disconnects the adapter from the slack API.

func (*SocketModeServer) RegisterAt

func (a *SocketModeServer) RegisterAt(brain *joe.Brain)

RegisterAt implements the joe.Adapter interface by emitting the slack API events to the given brain.