slacker

README

Slacker

Slacker is a Golang package to interface with Slack's API and Real Time Messaging API.

For full documentation, always check godoc.

Simple Examples

It's always fun to see quick ways to use a package. Here are some examples of how to use slacker for simple things.

Getting all channels for a team

c := slacker.NewAPIClient("your-slack-token", "")
channels, err := c.ChannelsList()
if err != nil {
	panic(err)
}

// Map channels so we can easily retrieve a channel by name.
mappedChannels := map[string]*slacker.Channel{}
for _, channel := range channels {
	mappedChannels[channel.Name] = channel
}

fmt.Printf("Channels: %+v", mappedChannels)

Getting all members for a team

c := slacker.NewAPIClient("your-slack-token", "")
users, err := c.UsersList()
if err != nil {
	panic(err)
}

mappedUsers := map[string]*slacker.User{}
for _, user := range users {
	mappedUsers[user.ID] = user
}

Starting an RTM broker (real time messaging)

This example starts a websocket to Slack's RTM API and displays events as they come in.

c := slacker.NewAPIClient("your-slack-token", "")
rtmStart, err := c.RTMStart()
if err != nil {
	panic(err)
}

broker := slacker.NewRTMBroker(rtmStart)
broker.Connect()

for {
	event := <-broker.Events()
	fmt.Println(event.Type)

	if event.Type == "message" {
		msg, err := event.Message()
		if err != nil {
			panic(err)
		}

		fmt.Println(msg.Text)
	}
}

License

Slacker is released under the MIT License.

Documentation

Overview

Package slacker is a Go package for working with the Slack integration tools. This includes the API and RTM endpoints.

To create a new slacker client, you can run

client := slacker.NewAPIClient("my-slack-api-token", "")

The first parameter is an OAuth2 token you should have obtained through either the Slack integrations dashboard, or the 3-legged OAuth2 token flow.

The second parameter is the base URL for the Slack API. If left empty, it will use https://slack.com/api for all RPC calls.

After you have created a client, you can call methods against the Slack API. For example, retrieving all user's of a team

users, err := client.UsersList()
if err != nil {
	panic(err)
}

for _, user := range users {
	fmt.Println(user.RealName)
}

If you want to run a method that is not supported by this package, you can call generic methods by running:

client.RunMethod("users.list")

This will return a []byte of the JSON returned by the Slack API.

Index

• Constants
• Variables
• func ParseResponse(r io.Reader, dest interface{}) error
• type APIClient
  • func NewAPIClient(token string, url string) *APIClient
  • func (c *APIClient) ChannelsList() ([]*Channel, error)
  • func (c *APIClient) RTMStart() (*RTMStartResult, error)
  • func (c *APIClient) RunMethod(name string) ([]byte, error)
  • func (c *APIClient) UsersList() ([]*User, error)
• type Channel
• type ChannelPurpose
• type ChannelTopic
• type ChannelsList
• type Profile
• type Publishable
• type RTMBroker
  • func NewRTMBroker(s *RTMStartResult) *RTMBroker
  • func (b *RTMBroker) Close() error
  • func (b *RTMBroker) Connect() error
  • func (b *RTMBroker) Events() <-chan RTMEvent
  • func (b *RTMBroker) Publish(e Publishable) error
• type RTMEvent
  • func (e RTMEvent) Message() (*RTMMessage, error)
• type RTMMessage
  • func (e RTMMessage) Publishable() ([]byte, error)
• type RTMStartResult
• type Response
• type User
• type UsersList

Constants

const DefaultAPIURL = "https://slack.com/api"

DefaultAPIURL is the default URL + Path for slack API requests

Variables

var (
	// ErrNotAuthed is returned when an API response returns with "not_authed"
	// as it's error attribute.
	ErrNotAuthed = errors.New("slacker: Not Authed")
)

Functions

func ParseResponse

func ParseResponse(r io.Reader, dest interface{}) error

ParseResponse parses an io.Reader (usually the result of an API request), and see's if the response actually contains error information. If it does, it will return an error, leaving `dest` untouched. Otherwise, it will json decode onto the destination passed in.

Types

type APIClient

type APIClient struct {
	SlackURL string
	// contains filtered or unexported fields
}

APIClient contains simple logic for starting the RTM Messaging API for Slack

func NewAPIClient

func NewAPIClient(token string, url string) *APIClient

NewAPIClient returns a new APIClient with a token set.

func (*APIClient) ChannelsList

func (c *APIClient) ChannelsList() ([]*Channel, error)

ChannelsList returns a list of Channels from Slack

func (*APIClient) RTMStart

func (c *APIClient) RTMStart() (*RTMStartResult, error)

RTMStart issues a start command for RTM. This is isually used for retrieving a WebSocket URL to start listening / posting messages into Slack.

func (*APIClient) RunMethod

func (c *APIClient) RunMethod(name string) ([]byte, error)

RunMethod runs an RPC method and returns the response body as a byte slice

func (*APIClient) UsersList

func (c *APIClient) UsersList() ([]*User, error)

UsersList returns all users in the team

type Channel

type Channel struct {
	Created    int      `json:"created"`
	Creator    string   `json:"creator"`
	ID         string   `json:"id"`
	IsArchived bool     `json:"is_archived"`
	IsChannel  bool     `json:"is_channel"`
	IsGeneral  bool     `json:"is_general"`
	IsMember   bool     `json:"is_member"`
	Members    []string `json:"members"`
	Name       string   `json:"name"`
	NumMembers int      `json:"num_members"`

	Purpose ChannelPurpose `json:"purpose"`
	Topic   ChannelTopic   `json:"topic"`
}

Channel represents a Slack channel https://api.slack.com/types/channel

type ChannelPurpose

type ChannelPurpose struct {
	Creator string `json:"creator"`
	LastSet int    `json:"last_set"`
	Value   string `json:"value"`
}

ChannelPurpose represents a channels' purpose in Slack

type ChannelTopic

type ChannelTopic struct {
	Creator string `json:"creator"`
	LastSet int    `json:"last_set"`
	Value   string `json:"value"`
}

ChannelTopic represents a channel's topic in Slack

type ChannelsList

type ChannelsList struct {
	Channels []*Channel `json:"channels"`
}

ChannelsList is a wrapper for a channels.list API call

type Profile

type Profile struct {
	AvatarHash         string `json:"avatar_hash"`
	Email              string `json:"email"`
	FirstName          string `json:"first_name"`
	LastName           string `json:"last_name"`
	Image192           string `json:"image_192"`
	Image24            string `json:"image_24"`
	Image32            string `json:"image_32"`
	Image48            string `json:"image_48"`
	Image512           string `json:"image_512"`
	Image72            string `json:"image_72"`
	RealName           string `json:"real_name"`
	RealNameNormalized string `json:"real_name_normalized"`
}

Profile represents a more detailed profile of a Slack user, including things like avatars.

type Publishable

type Publishable interface {
	Publishable() ([]byte, error)
}

Publishable is an interface that allows types to declare they are "publishable". Meaning that you can send the RTM API the data returned by the method Publishable

type RTMBroker

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

RTMBroker handles incoming and outgoing messages to a Slack RTM Websocket

func NewRTMBroker

func NewRTMBroker(s *RTMStartResult) *RTMBroker

NewRTMBroker returns a connected broker to Slack from a rtm.start result

func (*RTMBroker) Close

func (b *RTMBroker) Close() error

Close Closes the connection to Slack RTM

func (*RTMBroker) Connect

func (b *RTMBroker) Connect() error

Connect connects to the RTM Websocket

func (*RTMBroker) Events

func (b *RTMBroker) Events() <-chan RTMEvent

Events returns a receive-only channel for all Events RTM API pushes to the broker.

func (*RTMBroker) Publish

func (b *RTMBroker) Publish(e Publishable) error

Publish pushes an event to the RTM Websocket

type RTMEvent

type RTMEvent struct {
	Type       string `json:"type"`
	RawMessage json.RawMessage
}

RTMEvent repesents a simple event received from Slack

func (RTMEvent) Message

func (e RTMEvent) Message() (*RTMMessage, error)

Message converts an event to an RTMMessage. If the event type is not "message", it returns an error

type RTMMessage

type RTMMessage struct {
	Type    string `json:"type"`
	Text    string `json:"text"`
	Channel string `json:"channel"`
	User    string `json:"user"`
	Ts      string `json:"ts"`

	// This should only be set when publishing and is handled by Publishable()
	ID uint64 `json:"id"`
}

RTMMessage represents a posted message in a channel

func (RTMMessage) Publishable

func (e RTMMessage) Publishable() ([]byte, error)

Publishable implements Publishable

type RTMStartResult

type RTMStartResult struct {
	URL string `json:"url,omitempty"`
}

RTMStartResult contains the result of rtm.start in the Slack API

type Response

type Response struct {
	Ok    bool   `json:"ok"`
	Error string `json:"error"`
}

Response is the simplest representation of a Slack API response

type User

type User struct {
	ID       string `json:"id"`
	TeamID   string `json:"team_id"`
	Name     string `json:"name"`
	RealName string `json:"real_name"`
	Deleted  bool   `json:"deleted"`
	Color    string `json:"color"`
	IsAdmin  bool   `json:"is_admin"`
	IsOwner  bool   `json:"is_owner"`
	Has2fa   bool   `json:"has_2fa"`
	HasFiles bool   `json:"has_files"`

	Profile `json:"profile"`
}

User represents a Slack user object https://api.slack.com/types/user

type UsersList

type UsersList struct {
	Users []*User `json:"members"`
}

UsersList is a response object wrapper for users.list in Slack https://api.slack.com/methods/users.list