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(&bot.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") != "")
}

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 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, text string, sender *User)
• type ChannelData
  • func (c *ChannelData) URI() string
• type Cmd
• type CmdResult
• type Handlers
• 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 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, text string, sender *User)

MessageReceived must be called by the protocol upon receiving a message

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
	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 Handlers

type Handlers struct {
	Response ResponseHandler
}

Handlers that must be registered to receive callbacks from the bot

type PassiveCmd

type PassiveCmd struct {
	Raw         string       // Raw message sent to the channel
	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