guac

README

Guac

Guac is a client library for the Slack Web and Real Time APIs in Go. Use it for writing bots and other integrations. It's not complete but allows basic conversation via the real time API.

The name comes from a phonetically mangled portmanteau of "Go" and "Slack" combined with my love of Mexican food.

go get github.com/doozr/guac

For details of the Guac API see the API reference.

Getting Started

Instantiating the client requires only a bot integration token, configured via the Custom Integrations section of the Slack admin panel. Bots can discover their own name and channels via the API itself so none of that information is required.

webClient := guac.New(token)

Connecting to the Real Time API is done via an existing client instance, and opens a websocket to communicate with the Slack service.

rtm, err := webClient.RealTime()

Close connections when they're done to clean up any goroutines that are handling incoming messages from the Slack websocket.

rtm.Close()

Receiving Real Time Events

Receive events via the Receive() method. All events are returned from the same function so the best way to handle them is with a type switch. this could call handlers, push the events onto channels, or anything else.

func receiveEvents(rtm slack.RealTimeClient,
                   done chan struct{},
                   messages chan guac.MessageEvent,
                   userChanges chan guac.UserChangeEvent) {
    defer func() {
        rtm.Close()
    }()
    for {
        select {
        case <-done:
            return
        default:
            e, err := rtm.Receive()
            if err != nil {
                // log the error
                return
            }
            switch event := e.(type) {
            case guac.MessageEvent:
                messages <- event
            case guac.UserChangeEvent:
                userChanges <- event
            default:
                // Unhandled
        }
    }
}

Close the connection with the Close() method to stop the Receive() method listening. If an error is received from Receive() method it is considered terminal. At this point, create a new connection or restart the program.

Ping Pong

It is recommended to send a Ping request via the RealTimeClient.Ping() method periodically to let Slack know you are still there. It will result in a pong response returned by the Receive() method.

This means that, at a minimum, you should expect a message from Slack at least as frequently as your pings. If there is no incoming message for a significant period, it may be that the connection has hung and should be reconnected.

The PersistentRealTime connection accepts a duration to be considered "inactive" and will reconnect if that timeout is exceeded between messages. Note that it does not send ping requests; it only times out if nothing comes back. Make sure pings are being sent to prevent timeout.

Limitations

Only a very small subset of the Slack API functionality is implemented, although the code is extensible enough to allow quick addition of new endpoints and event types. It should be enough to get started with a very basic conversational bot.

Documentation

Overview

Package guac contains a client for the Slack Web and Real Time APIs in Go.

Index

• func DecodeString(input string) string
• func EncodeString(input string) string
• type ChannelInfo
• type EventChan
• type MessageEvent
• type PingPongEvent
• type RealTimeClient
• type UserChangeEvent
• type UserInfo
• type WebClient
  • func New(token string) WebClient

Functions

func DecodeString

func DecodeString(input string) string

DecodeString performs limited URL decoding as per Slack encoding standards

func EncodeString

func EncodeString(input string) string

EncodeString performs limited URL encoding as per Slack encoding standards

Types

type ChannelInfo

type ChannelInfo struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	IsMember bool   `json:"is_member"`
}

ChannelInfo represents a channel or group's info.

type EventChan

type EventChan chan interface{}

EventChan is a channel of any type of event

type MessageEvent

type MessageEvent struct {
	Type    string `json:"type"`
	ID      uint64 `json:"id"`
	Channel string `json:"channel"`
	User    string `json:"user"`
	Text    string `json:"text"`
}

MessageEvent is a chat message sent to a user or channel.

type PingPongEvent

type PingPongEvent struct {
	Type string `json:"type"`
	ID   uint64 `json:"id"`
}

PingPongEvent is a ping and also the reciprocal pong.

type RealTimeClient

type RealTimeClient interface {
	WebClient
	ID() string
	Name() string
	Close()
	Ping() error
	Receive() (interface{}, error)
}

RealTimeClient is a client of the Slack RealTime API.

type UserChangeEvent

type UserChangeEvent struct {
	Type     string `json:"type"`
	UserInfo `json:"user"`
}

UserChangeEvent is a notification that something about a user has changed. Currently only username changes are supported.

type UserInfo

type UserInfo struct {
	ID   string
	Name string
}

UserInfo represents a single user's profile info.

type WebClient

type WebClient interface {
	RealTime() (RealTimeClient, error)
	UsersList() ([]UserInfo, error)
	ChannelsList() ([]ChannelInfo, error)
	GroupsList() ([]ChannelInfo, error)
	IMOpen(user string) (string, error)
	PostMessage(channel string, text string) error
	PostSnippet(channel string, content string, filename string, filetype string, title string, initialComment string) error
}

WebClient is an interface to the Slack Web API.

func New

func New(token string) WebClient

New Slack Web API client.