hanu

README

hanu - Go for Slack Bots!

The Go framework hanu is your best friend to create Slack bots! hanu uses allot for easy command and request parsing (e.g. whisper <word>) and runs fine as a Heroku worker. All you need is a Slack API token and you can create your first bot within seconds! Just have a look at the hanu-example bot or read my tutorial …

Features

• Respond to mentions
• Respond to direct messages
• Auto-Generated command list for help
• Works fine as a worker on Heroku

Usage

Use the following example code or the hanu-example bot to get started.

package main

import (
	"log"
	"strings"

	"github.com/sbstjn/hanu"
)

func main() {
	slack, err := hanu.New("SLACK_BOT_API_TOKEN")

	if err != nil {
		log.Fatal(err)
	}

	Version := "0.0.1"

	slack.Command("shout <word>", func(conv hanu.ConversationInterface) {
		str, _ := conv.String("word")
		conv.Reply(strings.ToUpper(str))
	})

	slack.Command("whisper <word>", func(conv hanu.ConversationInterface) {
		str, _ := conv.String("word")
		conv.Reply(strings.ToLower(str))
	})

	slack.Command("version", func(conv hanu.ConversationInterface) {
		conv.Reply("Thanks for asking! I'm running `%s`", Version)
	})

	slack.Listen()
}

The example code above connects to Slack using SLACK_BOT_API_TOKEN as the bot's token and can respond to direct messages and mentions for the commands shout <word> , whisper <word> and version.

You don't have to care about help requests, hanu has it built in and will respond with a list of all defined commands on direct messages like this:

/msg @hanu help

Of course this works fine with mentioning you bot's username as well:

@hanu help

Slack

Use direct messages for communication:

/msg @hanu version

Or use the bot in a public channel:

@hanu version

Dependencies

• github.com/sbstjn/allot for parsing cmd <param1:string> <param2:integer> strings
• golang.org/x/net/websocket for websocket communication with Slack

Credits

• Host Go Slackbot on Heroku
• OpsDash article about Slack Bot
• Go coverage script from Mathias Lafeldt

Documentation

Index

• type Bot
  • func New(token string) (*Bot, error)
  • func (b *Bot) Command(cmd string, handler Handler)
  • func (b *Bot) Handshake() (*Bot, error)
  • func (b *Bot) Listen()
  • func (b *Bot) Register(cmd CommandInterface)
• type Command
  • func NewCommand(text string, description string, handler Handler) Command
  • func (c Command) Description() string
  • func (c Command) Get() allot.CommandInterface
  • func (c Command) Handle(conv ConversationInterface)
  • func (c *Command) Set(cmd allot.CommandInterface)
  • func (c *Command) SetDescription(text string)
  • func (c *Command) SetHandler(handler Handler)
• type CommandInterface
• type Connection
• type Conversation
  • func (c Conversation) Integer(name string) (int, error)
  • func (c Conversation) Match(position int) (string, error)
  • func (c *Conversation) Message() MessageInterface
  • func (c *Conversation) Reply(text string, a ...interface{})
  • func (c *Conversation) SetConnection(connection Connection)
  • func (c Conversation) String(name string) (string, error)
• type ConversationInterface
  • func NewConversation(match allot.MatchInterface, msg Message, socket *websocket.Conn) ConversationInterface
• type Handler
• type Message
  • func (m Message) IsDirectMessage() bool
  • func (m Message) IsFrom(user string) bool
  • func (m Message) IsHelpRequest() bool
  • func (m Message) IsMentionFor(user string) bool
  • func (m Message) IsMessage() bool
  • func (m Message) IsRelevantFor(user string) bool
  • func (m *Message) SetText(text string)
  • func (m *Message) StripLinkMarkup()
  • func (m *Message) StripMention(user string)
  • func (m Message) Text() string
  • func (m Message) User() string
• type MessageInterface

Types

type Bot

type Bot struct {
	Socket   *websocket.Conn
	Token    string
	ID       string
	Commands []CommandInterface
}

Bot is the main object

func New

func New(token string) (*Bot, error)

New creates a new bot

func (*Bot) Command

func (b *Bot) Command(cmd string, handler Handler)

Command adds a new command with custom handler

func (*Bot) Handshake

func (b *Bot) Handshake() (*Bot, error)

Handshake connects to the Slack API to get a socket connection

func (*Bot) Listen

func (b *Bot) Listen()

Listen for message on socket

func (*Bot) Register

func (b *Bot) Register(cmd CommandInterface)

Register registers a Command

type Command

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

Command a command

func NewCommand

func NewCommand(text string, description string, handler Handler) Command

NewCommand creates a new command

func (Command) Description

func (c Command) Description() string

Description returns the description

func (Command) Get

func (c Command) Get() allot.CommandInterface

Get returns the platzhalter command

func (Command) Handle

func (c Command) Handle(conv ConversationInterface)

Handle calls the command's handler

func (*Command) Set

func (c *Command) Set(cmd allot.CommandInterface)

Set defines the platzhalter command

func (*Command) SetDescription

func (c *Command) SetDescription(text string)

SetDescription sets the description

func (*Command) SetHandler

func (c *Command) SetHandler(handler Handler)

SetHandler sets the handler

type CommandInterface

type CommandInterface interface {
	Get() allot.CommandInterface
	Description() string
	Handle(conv ConversationInterface)
}

CommandInterface defines a command interface

type Connection

type Connection interface {
	Send(ws *websocket.Conn, v interface{}) (err error)
}

Connection is the needed interface for a connection

type Conversation

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

Conversation stores message, command and socket information and is passed to the handler function

func (Conversation) Integer

func (c Conversation) Integer(name string) (int, error)

Integer returns integer parameter

func (Conversation) Match

func (c Conversation) Match(position int) (string, error)

Match returns the parameter at the position

func (*Conversation) Message

func (c *Conversation) Message() MessageInterface

func (*Conversation) Reply

func (c *Conversation) Reply(text string, a ...interface{})

Reply sends message using the socket to Slack

func (*Conversation) SetConnection

func (c *Conversation) SetConnection(connection Connection)

SetConnection sets the conversation connection

func (Conversation) String

func (c Conversation) String(name string) (string, error)

String return string paramter

type ConversationInterface

type ConversationInterface interface {
	Integer(name string) (int, error)
	String(name string) (string, error)
	Reply(text string, a ...interface{})
	Match(position int) (string, error)
	Message() MessageInterface

	SetConnection(connection Connection)
	// contains filtered or unexported methods
}

ConversationInterface is the interface for a conversation

func NewConversation

func NewConversation(match allot.MatchInterface, msg Message, socket *websocket.Conn) ConversationInterface

NewConversation returns a Conversation struct

type Handler

type Handler func(ConversationInterface)

Handler is the interface for the handler function

type Message

type Message struct {
	ID      uint64 `json:"id"`
	Type    string `json:"type"`
	Channel string `json:"channel"`
	UserID  string `json:"user"`
	Message string `json:"text"`
}

Message is the Message structure for received and sent messages using Slack

func (Message) IsDirectMessage

func (m Message) IsDirectMessage() bool

IsDirectMessage checks if the message is received using a direct messaging channel

func (Message) IsFrom

func (m Message) IsFrom(user string) bool

IsFrom checks the sender of the message

func (Message) IsHelpRequest

func (m Message) IsHelpRequest() bool

IsHelpRequest checks if the user requests the help command

func (Message) IsMentionFor

func (m Message) IsMentionFor(user string) bool

IsMentionFor checks if the given user was mentioned with the message

func (Message) IsMessage

func (m Message) IsMessage() bool

IsMessage checks if it is a Message or some other kind of processing information

func (Message) IsRelevantFor

func (m Message) IsRelevantFor(user string) bool

IsRelevantFor checks if the message is relevant for a user

func (*Message) SetText

func (m *Message) SetText(text string)

SetText updates the text of a message

func (*Message) StripLinkMarkup

func (m *Message) StripLinkMarkup()

StripLinkMarkup converts <http://google.com|google.com> into google.com etc. https://api.slack.com/docs/message-formatting#how_to_display_formatted_messages

func (*Message) StripMention

func (m *Message) StripMention(user string)

StripMention removes the mention from the message beginning

func (Message) Text

func (m Message) Text() string

Text returns the message text

func (Message) User

func (m Message) User() string

User returns the message text

type MessageInterface

type MessageInterface interface {
	IsMessage() bool
	IsFrom(user string) bool
	IsHelpRequest() bool
	IsDirectMessage() bool
	IsMentionFor(user string) bool
	IsRelevantFor(user string) bool

	Text() string
	User() string
}

MessageInterface defines the message interface