bot

README

go-bot

IRC, Slack & Telegram bot written in Go using go-ircevent for IRC connectivity, nlopes/slack for Slack and Syfaro/telegram-bot-api for Telegram.

See the bot in action on IRC

To see the bot in action, send a private message to go-bot on Freenode or join the channel #go-bot @ irc.freenode.org.

Type !help in the channel or send !help in private message.

Plugins

Please see the plugins repository for a complete list of plugins.

You can also write your own, it's really simple.

Protocols

Slack

To deploy your go-bot to Slack, you need to:

• Create a new bot user integration on Slack and get your token
• Import the package github.com/go-chat-bot/bot/slack
• Import the commands you would like to use
• Call slack.Run(token)

Here is a full example reading the Slack token from the SLACK_TOKEN env var:

package main

import (
    "os"

    "github.com/go-chat-bot/bot/slack"
    _ "github.com/go-chat-bot/plugins/catfacts"
    _ "github.com/go-chat-bot/plugins/catgif"
    _ "github.com/go-chat-bot/plugins/chucknorris"
    // Import all the commands you wish to use
)

func main() {
    slack.Run(os.Getenv("SLACK_TOKEN"))
}

IRC

To deploy your own go-bot to IRC, you need to:

• Import the package github.com/go-chat-bot/bot/irc
• Import the commands you would like to use
• Fill the Config struct
• Call irc.Run(config)

Here is a full example:

package main
	import (
		"github.com/go-chat-bot/bot/irc"
		_ "github.com/go-chat-bot/plugins/catfacts"
		_ "github.com/go-chat-bot/plugins/catgif"
		_ "github.com/go-chat-bot/plugins/chucknorris"
		// Import all the commands you wish to use
		"os"
		"strings"
	)

	func main() {
		irc.Run(&irc.Config{
			Server:   os.Getenv("IRC_SERVER"),
			Channels: strings.Split(os.Getenv("IRC_CHANNELS"), ","),
			User:     os.Getenv("IRC_USER"),
			Nick:     os.Getenv("IRC_NICK"),
			Password: os.Getenv("IRC_PASSWORD"),
			UseTLS:   true,
			Debug:    os.Getenv("DEBUG") != "",})
	}

To join channels with passwords just put the password after the channel name separated by a space:

Channels: []string{"#mychannel mypassword", "#go-bot"}

Telegram

To deploy your go-bot to Telegram, you need to:

• Follow Telegram instructions to create a new bot user and get your token
• Import the package github.com/go-chat-bot/bot/telegram
• Import the commands you would like to use
• Call telegram.Run(token, debug)

Here is a full example reading the telegram token from the TELEGRAM_TOKEN env var:

package main

import (
    "os"

    "github.com/go-chat-bot/bot/telegram"
    _ "github.com/go-chat-bot/plugins/catfacts"
    _ "github.com/go-chat-bot/plugins/catgif"
    _ "github.com/go-chat-bot/plugins/chucknorris"
    // Import all the commands you wish to use
)

func main() {
    telegram.Run(os.Getenv("TELEGRAM_TOKEN"), os.Getenv("DEBUG") != "")
}

Rocket.chat

To deploy your go-bot to Rocket.chat, you need to:

• Import the package github.com/go-chat-bot/bot/rocket
• Import the commands you would like to use
• Call rocket.Run(config)

Here is a full example:

package main

import (
	"os"

	"github.com/go-chat-bot/bot/rocket"
	_ "github.com/go-chat-bot/plugins/godoc"
	_ "github.com/go-chat-bot/plugins/catfacts"
	_ "github.com/go-chat-bot/plugins/catgif"
	_ "github.com/go-chat-bot/plugins/chucknorris"
)

func main() {
	config := &rocket.Config{
		Server:   os.Getenv("ROCKET_SERVER"),
		Port:     os.Getenv("ROCKET_PORT"),
		User:     os.Getenv("ROCKET_USER"),
		Email:    os.Getenv("ROCKET_EMAIL"),
		Password: os.Getenv("ROCKET_PASSWORD"),
		UseTLS:   false,
		Debug:    os.Getenv("DEBUG") != "",
	}
	rocket.Run(config)
}

Deploying your own bot

To see an example project on how to deploy your bot, please see my own configuration:

• IRC: https://github.com/fabioxgn/go-bot-heroku
• Slack: https://github.com/fabioxgn/go-bot-slack

Documentation

Overview

Package bot provides a simple to use IRC, Slack and Telegram bot

Index

• Constants
• func RegisterCommand(command, description, exampleArgs string, cmdFunc activeCmdFuncV1)
• func RegisterCommandV2(command, description, exampleArgs string, cmdFunc activeCmdFuncV2)
• func RegisterCommandV3(command, description, exampleArgs string, cmdFunc activeCmdFuncV3)
• func RegisterPassiveCommand(command string, cmdFunc func(cmd *PassiveCmd) (string, error))
• func RegisterPeriodicCommand(command string, config PeriodicConfig)
• type Bot
  • func New(h *Handlers) *Bot
  • func (b *Bot) Disable(cmds []string)
  • func (b *Bot) MessageReceived(channel *ChannelData, message *Message, sender *User)
  • func (b *Bot) SendMessage(target string, message string, sender *User)
• type ChannelData
  • func (c *ChannelData) URI() string
• type Cmd
• type CmdResult
• type CmdResultV3
• type Handlers
• type Message
• type PassiveCmd
• type PeriodicConfig
• type ResponseHandler
• type User

Constants

const (
	// CmdPrefix is the prefix used to identify a command.
	// !hello would be identified as a command
	CmdPrefix = "!"
)

Functions

func RegisterCommand

func RegisterCommand(command, description, exampleArgs string, cmdFunc activeCmdFuncV1)

RegisterCommand adds a new command to the bot. The command(s) should be registered in the Init() func of your package command: String which the user will use to execute the command, example: reverse decription: Description of the command to use in !help, example: Reverses a string exampleArgs: Example args to be displayed in !help <command>, example: string to be reversed cmdFunc: Function which will be executed. It will received a parsed command as a Cmd value

func RegisterCommandV2

func RegisterCommandV2(command, description, exampleArgs string, cmdFunc activeCmdFuncV2)

RegisterCommandV2 adds a new command to the bot. It is the same as RegisterCommand but the command can specify the channel to reply to

func RegisterCommandV3

func RegisterCommandV3(command, description, exampleArgs string, cmdFunc activeCmdFuncV3)

RegisterCommandV3 adds a new command to the bot. It is the same as RegisterCommand but the command return a chan

func RegisterPassiveCommand

func RegisterPassiveCommand(command string, cmdFunc func(cmd *PassiveCmd) (string, error))

RegisterPassiveCommand adds a new passive command to the bot. The command should be registered in the Init() func of your package Passive commands receives all the text posted to a channel without any parsing command: String used to identify the command, for internal use only (ex: logs) cmdFunc: Function which will be executed. It will received the raw message, channel and nick

func RegisterPeriodicCommand

func RegisterPeriodicCommand(command string, config PeriodicConfig)

RegisterPeriodicCommand adds a command that is run periodically. The command should be registered in the Init() func of your package config: PeriodicConfig which specify CronSpec and a channel list cmdFunc: A no-arg function which gets triggered periodically

Types

type Bot

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

Bot handles the bot instance

func New

func New(h *Handlers) *Bot

New configures a new bot instance

func (*Bot) Disable

func (b *Bot) Disable(cmds []string)

Disable allows disabling commands that were registered. It is usefull when running multiple bot instances to disabled some plugins like url which is already present on some protocols.

func (*Bot) MessageReceived

func (b *Bot) MessageReceived(channel *ChannelData, message *Message, sender *User)

MessageReceived must be called by the protocol upon receiving a message

func (*Bot) SendMessage

func (b *Bot) SendMessage(target string, message string, sender *User)

Sends a message to a target recipient, optionally from a particular sender.

type ChannelData

type ChannelData struct {
	Protocol  string // What protocol the message was sent on (irc, slack, telegram)
	Server    string // The server hostname the message was sent on
	Channel   string // The channel name the message appeared in
	IsPrivate bool   // Whether the channel is a group or private chat
}

ChannelData holds the improved channel info, which includes protocol and server

func (*ChannelData) URI

func (c *ChannelData) URI() string

URI gives back an URI-fied string containing protocol, server and channel.

type Cmd

type Cmd struct {
	Raw         string       // Raw is full string passed to the command
	Channel     string       // Channel where the command was called
	ChannelData *ChannelData // More info about the channel, including network
	User        *User        // User who sent the message
	Message     string       // Full string without the prefix
	MessageData *Message     // Message with extra flags
	Command     string       // Command is the first argument passed to the bot
	RawArgs     string       // Raw arguments after the command
	Args        []string     // Arguments as array
}

Cmd holds the parsed user's input for easier handling of commands

type CmdResult

type CmdResult struct {
	Channel string // The channel where the bot should send the message
	Message string // The message to be sent
}

CmdResult is the result message of V2 commands

type CmdResultV3

type CmdResultV3 struct {
	Channel string
	Message chan string
	Done    chan bool
}

CmdResultV3 is the result message of V3 commands

type Handlers

type Handlers struct {
	Response ResponseHandler
}

Handlers that must be registered to receive callbacks from the bot

type Message

type Message struct {
	Text     string // The actual content of this Message
	IsAction bool   // True if this was a '/me does something' message
}

Message holds the message info - for IRC and Slack networks, this can include whether the message was an action.

type PassiveCmd

type PassiveCmd struct {
	Raw         string       // Raw message sent to the channel
	MessageData *Message     // Message with extra
	Channel     string       // Channel which the message was sent to
	ChannelData *ChannelData // Channel and network info
	User        *User        // User who sent this message
}

PassiveCmd holds the information which will be passed to passive commands when receiving a message

type PeriodicConfig

type PeriodicConfig struct {
	CronSpec string                               // CronSpec that schedules some function
	Channels []string                             // A list of channels to notify
	CmdFunc  func(channel string) (string, error) // func to be executed at the period specified on CronSpec
}

PeriodicConfig holds a cron specification for periodically notifying the configured channels

type ResponseHandler

type ResponseHandler func(target, message string, sender *User)

ResponseHandler must be implemented by the protocol to handle the bot responses

type User

type User struct {
	ID       string
	Nick     string
	RealName string
	IsBot    bool
}

User holds user id, nick and real name