Zero-dependencies Telegram Bot library with additional UI components

# Golang Telegram Bot

[![Go Report Card](https://goreportcard.com/badge/github.com/go-telegram/bot)](https://goreportcard.com/report/github.com/go-telegram/bot) [![codecov](https://codecov.io/gh/go-telegram/bot/branch/main/graph/badge.svg?token=57B1OR6PCK)](https://codecov.io/gh/go-telegram/bot)

✅ Present in the list of libraries https://core.telegram.org/bots/samples#go

> [Telegram Group](https://t.me/gotelegrambotui)

> Supports Bot API version: [7.10](https://core.telegram.org/bots/api#september-6-2024) from September 6, 2024

It's a Go zero-dependencies telegram bot framework

A simple example `echo-bot`:

```go
package main

import (
	"context"
	"os"
	"os/signal"

	"github.com/go-telegram/bot"
	"github.com/go-telegram/bot/models"
)

// Send any text message to the bot after the bot has been started

func main() {
	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
	defer cancel()

	opts := []bot.Option{
		bot.WithDefaultHandler(handler),
	}

	b, err := bot.New("YOUR_BOT_TOKEN_FROM_BOTFATHER", opts...)
	if err != nil {
		panic(err)
	}

	b.Start(ctx)
}

func handler(ctx context.Context, b *bot.Bot, update *models.Update) {
	b.SendMessage(ctx, &bot.SendMessageParams{
		ChatID: update.Message.Chat.ID,
		Text: update.Message.Text,
	})
}
```

You can find more examples in the [examples](examples) folder.

To run the examples, set the `EXAMPLE_TELEGRAM_BOT_TOKEN` environment variable to your bot token.

## Getting started

Go version: **1.18**

Install the dependencies:

```bash
go get -u github.com/go-telegram/bot
```

Initialize and run the bot:

```go
b, err := bot.New("YOUR_BOT_TOKEN_FROM_BOTFATHER")

b.Start(context.TODO())
```

On create bot will call the `getMe` method (with 5 sec timeout). And returns error on fail.
If you want to change this timeout, use option `bot.WithCheckInitTimeout`

You can define a default handler for the bot:

```go
b, err := bot.New("YOUR_BOT_TOKEN_FROM_BOTFATHER", bot.WithDefaultHandler(handler))

func handler(ctx context.Context, b *bot.Bot, update *models.Update) {
	// this handler will be called for all updates
}
```

## Webhooks

If you want to use webhooks, instead of using `bot.Start`, you should use the `bot.StartWebhook` method to start the bot.
Also, you should use `bot.WebhookHandler()` method as HTTP handler for your server.

```go
func main() {
	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
	defer cancel()

	opts := []bot.Option{
		bot.WithDefaultHandler(handler),
		bot.WithWebhookSecretToken(os.Getenv("EXAMPLE_TELEGRAM_WEBHOOK_SECRET_TOKEN"))
	}

	b, _ := bot.New(os.Getenv("EXAMPLE_TELEGRAM_BOT_TOKEN"), opts...)

	// call methods.SetWebhook if needed

	go b.StartWebhook(ctx)

	http.ListenAndServe(":2000", b.WebhookHandler())

	// call methods.DeleteWebhook if needed
}

func handler(ctx context.Context, b *bot.Bot, update *models.Update) {
	b.SendMessage(ctx, &bot.SendMessageParams{
		ChatID: update.Message.Chat.ID,
		Text: update.Message.Text,
	})
}
```

[Demo in examples](examples/echo_with_webhook/main.go)

Also, you can manually process updates with `bot.ProcessUpdate` method.

```go
update := models.Update{}

json.NewDecoder(req.Body).Decode(&update)

b.ProcessUpdate(ctx, &update)
```

## Middlewares

You can use middlewares with `WithMiddlewares(middlewares ...Middleware)` option.

See an example in [examples](examples/middleware/main.go)

## Available methods

All available methods are listed in the [Telegram Bot API documentation](https://core.telegram.org/bots/api)

You can use all these methods as bot funcs. All methods have name like in official documentation, but with capital first letter.

`bot.SendMessage`, `bot.GetMe`, `bot.SendPhoto`, etc

All methods have signature `(ctx context.Context, params <PARAMS>) (<response>, error)`.
Except `GetMe`, `Close` and `Logout` which are have not params

`<PARAMS>` is a struct with fields that corresponds to Telegram Bot API parameters.
All Params structs have name like for corresponded methods, but with `Params` suffix.

`SendMessageParams` for `SendMessage` method etc.

You should pass params by pointer

```go
bot.SendMessage(ctx, &bot.SendMessageParams{...})
```

## Options

You can use options to customize the bot.

```go
b, err := bot.New("YOUR_BOT_TOKEN_FROM_BOTFATHER", opts...)
```

### Options list (see [options.go](options.go) for more details)

- `WithCheckInitTimeout(timeout time.Duration)` - timeout for check init bot
- `WithMiddlewares(middlewares ...Middleware)` - add middlewares
- `WithMessageTextHandler(pattern string, matchType MatchType, handler HandlerFunc)` - add handler for Message.Text field
- `WithCallbackQueryDataHandler(pattern string, matchType MatchType, handler HandlerFunc)` - add handler for CallbackQuery.Data field
- `WithDefaultHandler(handler HandlerFunc)` - add default handler
- `WithDebug()` - enable debug mode
- `WithErrorsHandler(handler ErrorsHandler)` - add errors handler
- `WithDebugHandler(handler DebugHandler)` - add debug handler
- `WithHTTPClient(pollTimeout time.Duration, client HttpClient)` - set custom http client
- `WithServerURL(serverURL string)` - set server url
- `WithSkipGetMe()` - skip call GetMe on bot init
- `WithAllowedUpdates(params AllowedUpdates)` - set [allowed_updates](https://core.telegram.org/bots/api#getupdates) for getUpdates method
- `WithUpdatesChannelCap(cap int)` - set updates channel capacity, by default 1024
- `WithWebhookSecretToken(webhookSecretToken string)` - set X-Telegram-Bot-Api-Secret-Token header sent from telegram servers to confirm validity of update
- `WithWorkers` - set the number of workers that are processing the Updates channel, by default 1
- `UseTestEnvironment()` - use test environment

## Message.Text and CallbackQuery.Data handlers

For your convenience, you can use `Message.Text` and `CallbackQuery.Data` handlers.

An example:

```go
b, err := bot.New("YOUR_BOT_TOKEN_FROM_BOTFATHER")

b.RegisterHandler(bot.HandlerTypeMessageText, "/start", bot.MatchTypeExact, myStartHandler)

b.Start(context.TODO())
```

> also you can use bot init options `WithMessageTextHandler` and `WithCallbackQueryDataHandler`


In this example, the handler will be called when the user sends `/start` message. All other messages will be handled by the default handler.

Handler Types:
- `HandlerTypeMessageText` - for Update.Message.Text field
- `HandlerTypeCallbackQueryData` - for Update.CallbackQuery.Data field

RegisterHandler returns a handler ID string. You can use it to remove the handler later.

```
b.UnregisterHandler(handlerID)
```

Match Types:
- `MatchTypeExact`
- `MatchTypePrefix`
- `MatchTypeContains`

You can use `RegisterHandlerRegexp` to match by regular expression.

```go
re := regexp.MustCompile(`^/start`)

b.RegisterHandlerRegexp(bot.HandlerTypeMessageText, re, myStartHandler)
```

If you want to use custom handler, use `RegisterHandlerMatchFunc`

```go
matchFunc := func(update *models.Update) bool {
	// your checks
	return true
}

b.RegisterHandlerMatchFunc(bot.HandlerTypeMessageText, matchFunc, myHandler)
```

## InputFile

For some methods, like `SendPhoto`, `SendAudio` etc, you can send file by file path or file contents.

To send a file by URL or FileID, you can use `&models.InputFileString{Data: string}`:

```go
// file id of uploaded image
inputFileData := "AgACAgIAAxkDAAIBOWJimnCJHQJiJ4P3aasQCPNyo6mlAALDuzEbcD0YSxzjB-vmkZ6BAQADAgADbQADJAQ"
// or URL image path
// inputFileData := "https://example.com/image.png"

params := &bot.SendPhotoParams{
 ChatID: chatID,
 Photo: &models.InputFileString{Data: inputFileData},
}

bot.SendPhoto(ctx, params)
```

[Demo in examples](examples/send_photo/main.go)

To send an image file by its contents, you can use `&models.InputFileUpload{Filename: string, Data: io.Reader}`:

```go
fileContent, _ := os.ReadFile("/path/to/image.png")

params := &bot.SendPhotoParams{
 ChatID: chatID,
 Photo: &models.InputFileUpload{Filename: "image.png", Data: bytes.NewReader(fileContent)},
}

bot.SendPhoto(ctx, params)
```

[Demo in examples](examples/send_photo_upload/main.go)

## InputMedia

For methods like `SendMediaGroup` or `EditMessageMedia` you can send media by file path or file contents.

[Official documentation InputMedia](https://core.telegram.org/bots/api#inputmedia)

> field `media`: File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name.

If you want to use `attach://` format, you should to define `MediaAttachment` field with file content reader.

```go
fileContent, _ := os.ReadFile("/path/to/image.png")

media1 := &models.InputMediaPhoto{
	Media: "https://telegram.org/img/t_logo.png",
}

media2 := &models.InputMediaPhoto{
	Media: "attach://image.png",
	Caption: "2",
	MediaAttachment: bytes.NewReader(fileContent),
}

params := &bot.SendMediaGroupParams{
 ChatID: update.Message.Chat.ID,
 Media: []models.InputMedia{
 media1,
 media2,
 },
}

bot.SendMediaGroup(ctx, params)
```

[Demo in examples](examples/send_media_group/main.go)

## Helpers

### `EscapeMarkdown(s string) string`

Escape special symbols for Telegram MarkdownV2 syntax

### `EscapeMarkdownUnescaped(s string) string`

Escape only unescaped special symbols for Telegram MarkdownV2 syntax

### `RandomString(n int) string`

Returns fast random a-zA-Z string with n length

### `True() bool`, `False() bool`

Allows you to define `*bool` values for params, which require `*bool`, like `SendPollParams`

```go
p := &bot.SendPollParams{
 ChatID: chatID,
 Question: "Question",
 Options: []string{"Option 1", "Option 2"},
 IsAnonymous: bot.False(),
}

b.SendPoll(ctx, p)
```

### `ValidateWebappRequest(values url.Values, token string) (user *models.User, ok bool)`

Validate request from Telegram Webapp

https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app

```go
// get url values from request
values := req.URL.Query()

user, ok := bot.ValidateWebappRequest(values, os.Getenv("TELEGRAM_BOT_TOKEN"))
if !ok {
 http.Error(w, "Unauthorized", http.StatusUnauthorized)
 return
}
```

### `FileDownloadLink(f *models.File) string`

Return file download link after call method `GetFile`

See [documentation](https://core.telegram.org/bots/api#getfile)

## Errors

This library includes error handling. It provides the following error types:

- **ErrorForbidden (403):** This error occurs when the bot has no access to the action, such as when the user has blocked the bot.
- **ErrorBadRequest (400):** This error indicates a bad request made to the bot's API.
- **ErrorUnauthorized (401):** This error occurs when the bot's access is unauthorized for the requested action.
- **TooManyRequestsError: (429)** This error indicates that the bot has received too many requests within a short period. It includes a RetryAfter value indicating when to retry the request.
- **ErrorNotFound (404):** This error indicates that the requested resource was not found.
- **ErrorConflict (409):** This error indicates a conflict occurred during the request.

Usage:
```go
_, err := b.SendMessage(...)

if errors.Is(err, mybot.ErrorForbidden) {
 // Handle the ErrorForbidden (403) case here
}

if errors.Is(err, mybot.ErrorBadRequest) {
 // Handle the ErrorBadRequest (400) case here
}

if errors.Is(err, mybot.ErrorUnauthorized) {
 // Handle the ErrorUnauthorized (401) case here
}

if mybot.IsTooManyRequestsError(err) {
 // Handle the TooManyRequestsError (429) case here
 fmt.Println("Received TooManyRequestsError with retry_after:", err.(*mybot.TooManyRequestsError).RetryAfter)
}

if errors.Is(err, mybot.ErrorNotFound) {
 // Handle the ErrorNotFound (404) case here
}

if errors.Is(err, mybot.ErrorConflict) {
 // Handle the ErrorConflict (409) case here
}
```

## UI Components

In the repo https://github.com/go-telegram/ui you can find a some UI elements for your bot.

- datepicker
- inline_keyboard
- slider
- paginator

and more...

Please, check the repo for more information and live demo.

An elegant and concurrent library for Telegram Bots in Go.

| <img src="assets/readme_banner.png" alt="logo" width="800"> [![Language](https://img.shields.io/badge/Language-Go-blue.svg)](https://golang.org/) [![PkgGoDev](https://pkg.go.dev/badge/github.com/NicoNex/echotron/v3)](https://pkg.go.dev/github.com/NicoNex/echotron/v3) [![Go Report Card](https://goreportcard.com/badge/github.com/NicoNex/echotron/v3)](https://goreportcard.com/report/github.com/NicoNex/echotron/v3) [![codecov](https://codecov.io/gh/NicoNex/echotron/graph/badge.svg?token=LVJGOEYL5M)](https://codecov.io/gh/NicoNex/echotron) [![License](http://img.shields.io/badge/license-LGPL3.0-orange.svg?style=flat)](https://github.com/NicoNex/echotron/blob/master/LICENSE) [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) [![Telegram](https://img.shields.io/badge/Echotron%20News-blue?logo=telegram&style=flat)](https://t.me/echotronnews) |
| :------: |

**Echotron** is an elegant and concurrent library for the Telegram bot API in Go.

Fetch with

```bash
go get github.com/NicoNex/echotron/v3
```

## Example
### Simplest implementations
#### Long polling
```golang
package main

import "github.com/NicoNex/echotron/v3"

const token = "MY TELEGRAM TOKEN"

func main() {
	api := echotron.NewAPI(token)

	for u := range echotron.PollingUpdates(token) {
		if u.Message.Text == "/start" {
			api.SendMessage("Hello world", u.ChatID(), nil)
		}
	}
}
```
#### Webhook
```golang
package main

import "github.com/NicoNex/echotron/v3"

const token = "MY TELEGRAM TOKEN"

func main() {
	api := echotron.NewAPI(token)

	for u := range echotron.WebhookUpdates("https://example.com:443/my_token", token) {
		if u.Message.Text == "/start" {
			api.SendMessage("Hello world", u.ChatID(), nil)
		}
	}
}
```
For more scalable and recommended implementations see the other examples.

### Long Polling

```golang
package main

import (
	"log"
	"time"

	"github.com/NicoNex/echotron/v3"
)

// Struct useful for managing internal states in your bot, but it could be of
// any type such as `type bot int64` if you only need to store the chatID.
type bot struct {
	chatID int64
	echotron.API
}

const token = "MY TELEGRAM TOKEN"

// This function needs to be of type 'echotron.NewBotFn' and is called by
// the echotron dispatcher upon any new message from a chatID that has never
// interacted with the bot before.
// This means that echotron keeps one instance of the echotron.Bot implementation
// for each chat where the bot is used.
func newBot(chatID int64) echotron.Bot {
	return &bot{
		chatID,
		echotron.NewAPI(token),
	}
}

// This method is needed to implement the echotron.Bot interface.
func (b *bot) Update(update *echotron.Update) {
	if update.Message.Text == "/start" {
		b.SendMessage("Hello world", b.chatID, nil)
	}
}

func main() {
	// This is the entry point of echotron library.
	dsp := echotron.NewDispatcher(token, newBot)
	for {
		log.Println(dsp.Poll())
		// In case of connection issues wait 5 seconds before trying to reconnect.
		time.Sleep(5 * time.Second)
	}
}
```

## Design

**Echotron** makes a new instance of the struct bot for each open chat with a Telegram user, channel or group.
This allows to:
- safely call the `Update(*echotron.Update)` method concurrently
- give to the user a convenient way to manage the bot internal states across all the chats
- make sure that, even if one instance of the bot is deadlocked, the other ones keep running just fine, making the bot work for other users without any issues and/or slowdowns.

Please note that the the aforementioned behaviour is dictated by the `echotron.Dispatcher` object whose usage is not mandatory and for special needs can be ignored and implemented in different ways still keeping all the methods in the `echotron.API` object.

**Echotron** is designed to be as similar to the official [Telegram API](https://core.telegram.org/bots/api) as possible, but there are some things to take into account before starting to work with this library.

- The methods have the exact same name, but with a capital first letter, since in Go methods have to start with a capital letter to be exported.
_Example: `sendMessage` becomes `SendMessage`_
- The order of the parameters in some methods is different than in the official Telegram API, so refer to the [docs](https://pkg.go.dev/github.com/NicoNex/echotron/v3) for the correct one.
- The only `chat_id` (or, in this case, `chatID`) type supported is `int64`, instead of the "Integer or String" requirement of the official API. That's because numeric IDs can't change in any way, which isn't the case with text-based usernames.
- In some methods, you might find a `InputFile` type parameter. [`InputFile`](https://pkg.go.dev/github.com/NicoNex/echotron/v3#InputFile) is a struct with unexported fields, since only three combination of fields are valid, which can be obtained through the methods [`NewInputFileID`](https://pkg.go.dev/github.com/NicoNex/echotron/v3#NewInputFileID), [`NewInputFilePath`](https://pkg.go.dev/github.com/NicoNex/echotron/v3#NewInputFilePath) and [`NewInputFileBytes`](https://pkg.go.dev/github.com/NicoNex/echotron/v3#NewInputFileBytes).
- In some methods, you might find a `MessageIDOptions` type parameter. [`MessageIDOptions`](https://pkg.go.dev/github.com/NicoNex/echotron/v3#MessageIDOptions) is another struct with unexported fields, since only two combination of field are valid, which can be obtained through the methods [`NewMessageID`](https://pkg.go.dev/github.com/NicoNex/echotron/v3#NewMessageID) and [`NewInlineMessageID`](https://pkg.go.dev/github.com/NicoNex/echotron/v3#NewInlineMessageID).
- Optional parameters can be added by passing the correct struct to each method that might request optional parameters. If you don't want to pass any optional parameter, `nil` is more than enough. Refer to the [docs](https://pkg.go.dev/github.com/NicoNex/echotron/v3) to check for each method's optional parameters struct: it's the type of the `opts` parameter.
- Some parameters are hardcoded to avoid putting random stuff which isn't recognized by the Telegram API. Some notable examples are [`ParseMode`](https://github.com/NicoNex/echotron/blob/master/options.go#L21), [`ChatAction`](https://github.com/NicoNex/echotron/blob/master/options.go#L54) and [`InlineQueryType`](https://github.com/NicoNex/echotron/blob/master/inline.go#L27). For a full list of custom hardcoded parameters, refer to the [docs](https://pkg.go.dev/github.com/NicoNex/echotron/v3) for each custom type: by clicking on the type's name, you'll get the source which contains the possible values for that type.

## Additional examples
### Functional approach to state management
```golang
package main

import (
	"log"
	"strings"

	"github.com/NicoNex/echotron/v3"
)

// Recursive type definition of the bot state function.
type stateFn func(*echotron.Update) stateFn

type bot struct {
	chatID int64
	state stateFn
	name string
	echotron.API
}

const token = "MY TELEGRAM TOKEN"

func newBot(chatID int64) echotron.Bot {
	bot := &bot{
		chatID: chatID,
		API:	echotron.NewAPI(token),
	}
	// We set the default state to the bot.handleMessage method.
	bot.state = bot.handleMessage
	return bot
}

func (b *bot) Update(update *echotron.Update) {
	// Here we execute the current state and set the next one.
	b.state = b.state(update)
}

func (b *bot) handleMessage(update *echotron.Update) stateFn {
	if strings.HasPrefix(update.Message.Text, "/set_name") {
		b.SendMessage("Send me my new name!", b.chatID, nil)
		// Here we return b.handleName since next time we receive a message it
		// will be the new name.
		return b.handleName
	}
	return b.handleMessage
}

func (b *bot) handleName(update *echotron.Update) stateFn {
	b.name = update.Message.Text
	b.SendMessage(fmt.Sprintf("My new name is %q", b.name), b.chatID, nil)
	// Here we return b.handleMessage since the next time we receive a message
	// it will be handled in the default way.
	return b.handleMessage
}

func main() {
	dsp := echotron.NewDispatcher(token, newBot)
	log.Println(dsp.Poll())
}
```

### Self destruction for lower memory footprint
```golang
package main

import (
	"log"
	"time"

	"github.com/NicoNex/echotron/v3"
)

type bot struct {
	chatID int64
	echotron.API
}

const token = "MY TELEGRAM TOKEN"

var dsp *echotron.Dispatcher

func newBot(chatID int64) echotron.Bot {
	bot := &bot{
		chatID,
		echotron.NewAPI(token),
	}
	go bot.selfDestruct(time.After(time.Hour))
	return bot
}

func (b *bot) selfDestruct(timech <-chan time.Time) {
	<-timech
	b.SendMessage("goodbye", b.chatID, nil)
	dsp.DelSession(b.chatID)
}

func (b *bot) Update(update *echotron.Update) {
	if update.Message.Text == "/start" {
		b.SendMessage("Hello world", b.chatID, nil)
	}
}

func main() {
	dsp = echotron.NewDispatcher(token, newBot)
	log.Println(dsp.Poll())
}
```

### Webhook

```golang
package main

import "github.com/NicoNex/echotron/v3"

type bot struct {
	chatID int64
	echotron.API
}

const token = "MY TELEGRAM TOKEN"

func newBot(chatID int64) echotron.Bot {
	return &bot{
		chatID,
		echotron.NewAPI(token),
	}
}

func (b *bot) Update(update *echotron.Update) {
	if update.Message.Text == "/start" {
		b.SendMessage("Hello world", b.chatID, nil)
	}
}

func main() {
	dsp := echotron.NewDispatcher(token, newBot)
	dsp.ListenWebhook("https://example.com:443/my_bot_token")
}
```


### Webhook with a custom http.Server

This is an example for a custom http.Server which handles your own specified routes
and also the webhook route which is specified by ListenWebhook.

```golang
package main

import (
	"github.com/NicoNex/echotron/v3"

	"context"
	"log"
	"net/http"
)

type bot struct {
	chatID int64
	echotron.API
}

const token = "MY TELEGRAM TOKEN"

func newBot(chatID int64) echotron.Bot {
	return &bot{
		chatID,
		echotron.NewAPI(token),
	}
}

func (b *bot) Update(update *echotron.Update) {
	if update.Message.Text == "/start" {
		b.SendMessage("Hello world", b.chatID, nil)
	}
}

func main() {
	termChan := make(chan os.Signal, 1) // Channel for terminating the app via os.Interrupt signal
	signal.Notify(termChan, syscall.SIGINT, syscall.SIGTERM)

	mux := http.NewServeMux()
	mux.HandleFunc("/login", func(w http.ResponseWriter, r *http.Request) {
		// Handle user login
	})
	mux.HandleFunc("/logout", func(w http.ResponseWriter, r *http.Request) {
		// Handle user logout
	})
	mux.HandleFunc("/about", func(w http.ResponseWriter, r *http.Request) {
		// Tell something about your awesome telegram bot
	})

	// Set custom http.Server
	server := &http.Server{Addr: ":8080", Handler: mux}

	go func() {
		<-termChan
		// Perform some cleanup..
		if err := server.Shutdown(context.Background()); err != nil {
			log.Print(err)
		}
	}()

	// Capture the interrupt signal for app termination handling
	dsp := echotron.NewDispatcher(token, newBot)
	dsp.SetHTTPServer(server)
	// Start your custom http.Server with a registered /my_bot_token handler.
	log.Println(dsp.ListenWebhook("https://example.com/my_bot_token"))
}
```

echotron

A Discord bot for managing ephemeral roles based upon voice channel member presence.

# ephemeral-roles

| <a href="https://discordapp.com/api/oauth2/authorize?client_id=392419127626694676&permissions=268435456&scope=bot"><img src="https://raw.githubusercontent.com/ewohltman/ephemeral-roles/master/web/static/Testa_Anatomica-Filippo_Balbi.jpg" width="100"></a> [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) ![Build Status](https://github.com/ewohltman/ephemeral-roles/workflows/build/badge.svg?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/ewohltman/ephemeral-roles)](https://goreportcard.com/report/github.com/ewohltman/ephemeral-roles) [![Coverage Status](https://coveralls.io/repos/github/ewohltman/ephemeral-roles/badge.svg?branch=master)](https://coveralls.io/github/ewohltman/ephemeral-roles?branch=master) [![Dev Chat](https://img.shields.io/badge/discord-dev%20chat-blue)](https://discord.gg/yrxaJb5) |
| :------: |

### A Discord bot for managing ephemeral roles based upon voice channel member presence.

----

## Quickstart

1. Click on the `Ephemeral Roles` logo head above or use [this link](https://discordapp.com/api/oauth2/authorize?client_id=392419127626694676&permissions=268435456&scope=bot)
to invite `Ephemeral Roles` into your Discord server
 1. The 'Manage Roles' permission is required. The invite link above
 provides that by automatically creating an appropriate role in your server
 for `Ephemeral Roles` 
2. Ensure the new role for `Ephemeral Roles` is at the top (or as near as
possible) to the server's list of roles
 1. If you're not sure how or why to do that, take a quick read over
 Discord's excellent [Role Management 101](https://support.discordapp.com/hc/en-us/articles/214836687-Role-Management-101) guide
3. Enjoy!

----

## What does `Ephemeral Roles` do?

After the `Ephemeral Roles` bot is invited to your Discord server, it
immediately starts to watch for changes to your voice channels. When a member
joins a channel, `Ephemeral Roles` automatically assigns that member an
*ephemeral role* associated with the channel. If the *ephemeral role* doesn't
exist yet, `Ephemeral Roles` will create it.

By having your members auto-sorted into *ephemeral roles* in your member list,
it's clear to see who are available for chatting and the channels they are in.
This is because `Ephemeral Roles` leverages the Discord feature that the member
list in servers will group together members by role right out of the box.

When a member changes or disconnects from voice channels, even across Discord
servers, `Ephemeral Roles` will account for the change and automatically
revoke/reissue *ephemeral roles* as appropriate.

----

## Example Usage

| Orange roles below are automatically managed by `Ephemeral Roles` |
| :------: |
| ![Ephemeral Roles action example](https://raw.githubusercontent.com/ewohltman/ephemeral-roles/master/web/static/action.gif) |
| ![Ephemeral Roles static example](https://raw.githubusercontent.com/ewohltman/ephemeral-roles/master/web/static/static.png) |
| ![Ephemeral Roles example role list](https://raw.githubusercontent.com/ewohltman/ephemeral-roles/master/web/static/roles.png) |

----

## Monitoring

A **[Prometheus](https://prometheus.io/)** and **[Grafana](https://grafana.com/)** instance have been set up to monitor `Ephemeral Roles` metrics.

| [grafana.ephemeral-roles.net](http://grafana.ephemeral-roles.net/d/OqANQqtiz/ephemeral-roles-metrics?orgId=1&refresh=5s) |
| :------: |
| <a href="http://grafana.ephemeral-roles.net/d/OqANQqtiz/ephemeral-roles-metrics?orgId=1&refresh=5s"><img src="https://raw.githubusercontent.com/ewohltman/ephemeral-roles/master/web/static/bot-metrics.png"></a> |

----

## Architecture

| Architectural Diagram |
| :------: |
| ![Architecture](https://raw.githubusercontent.com/ewohltman/ephemeral-roles/master/web/static/architecture.png) |
| Architectural diagram created with [draw.io](https://draw.io/) |

* `ephemeral-roles`:
 * Runs in a Kubernetes cluster as a StatefulSet of 10 Pods. Each Pod contains
 a running instance of the bot
 * A StatefulSet is used so that each Pod has a predictable name so that the
 bot instance can inform the Discord API which of the 10 Pods it is
 * The Discord API will assign a number of the total guilds (servers) to each
 of the bot instances to balance the load of managing the guild events
 * If any of the Pods stop running for whatever reason, the StatefulSet will
 automatically restart them
* `pod-bouncer` (https://github.com/ewohltman/pod-bouncer):
 * Runs in a Pod and is responsible for receiving alerts from
 `Prometheus`/`AlertManager` and to act upon them by automatically causing
 unhealthy Pods for `ephemeral-roles` to restart
* `ephemeral-roles-informer` (https://github.com/ewohltman/ephemeral-roles-informer):
 * Runs in a Pod and is responsible for collecting metrics from the
 `ephemeral-roles` instances to update search services such as
 [discord.bots.gg](https://discord.bots.gg/) and [top.gg](https://top.gg/)

----

## Contributing to the project

Contributions are very welcome! Please follow the guidelines below:

* Open an issue describing the bug or enhancement
* Fork the `develop` branch and make your changes
 * Try to match current naming conventions as closely as possible
 * Try to keep changes small and incremental with appropriate new unit tests
* Create a Pull Request with your changes against the `develop` branch

This project is equipped with a full
[CI](https://en.wikipedia.org/wiki/Continuous_integration)
/
[CD](https://en.wikipedia.org/wiki/Continuous_deployment) pipeline:
 
* Linting and unit tests will be automatically run with the PR, providing
feedback if any additional changes need to be made
* Merge to `master` will automatically deploy the changes live

ephemeral-roles

# go-bot

[![Circle CI](https://circleci.com/gh/go-chat-bot/bot/tree/master.svg?style=svg)](https://circleci.com/gh/go-chat-bot/bot/tree/master) [![GoDoc](https://godoc.org/github.com/go-chat-bot/bot?status.png)](https://godoc.org/github.com/go-chat-bot/bot) [![Coverage Status](https://coveralls.io/repos/github/go-chat-bot/bot/badge.svg?branch=master)](https://coveralls.io/github/go-chat-bot/bot?branch=master) ![Go report](https://goreportcard.com/badge/github.com/go-chat-bot/bot) [![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)

IRC, Slack & Telegram bot written in [Go][go] using [go-ircevent][go-ircevent] for IRC connectivity, [nlopes/slack](https://github.com/nlopes/slack) for Slack and [Syfaro/telegram-bot-api](https://github.com/Syfaro/telegram-bot-api) for Telegram.

![2016-01-17 11 21 38 036](https://cloud.githubusercontent.com/assets/1084729/12377689/5bf7d5f2-bd0d-11e5-87d9-525481f01c3a.gif)

## Plugins

Please see the [plugins repository](https://github.com/go-chat-bot/plugins) for a complete list of plugins.

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

## Compiling and testing the bot and plugins (Debug)

This project uses the new [Go 1.11 modules](https://github.com/golang/go/wiki/Modules) if you have Go 1.11 installed, just clone the project and follow the instructions bellow, when you build Go will automatically download all dependencies.

To test the bot, use the [debug](https://github.com/go-chat-bot/bot/tree/master/debug) console app.

- Clone this repository or use `go get github.com/go-chat-bot/bot`
- Build everything: `go build ./...`
- Build and execute the debug app:
 - `cd debug`
 - `go build`
 - `./debug`
- This will open a console where you can type commands
- Type `!help` to see the list of available commands

### Testing your plugin

- Add your plugin to `debug/main.go` import list
- Build the debug app
- Execute it and test with the interactive console

## Protocols

### Slack

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

* [Create a new bot user](https://my.slack.com/services/new/bot) 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:

```Go
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:
```Go
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](https://core.telegram.org/bots#3-how-do-i-create-a-bot) 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:

```Go
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:

```Go
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)
}
```

### Google Chat

To deploy your go-bot to Google Chat (also known as Hangouts Chat, not plain
Hangouts) you will first need to follow documentation to [setup pub/sub
project](https://developers.google.com/hangouts/chat/how-tos/pub-sub) in Google
Cloud. This will enable your bot to receive messages even when it is behind a
firewall.

Condensed, the steps you will need to take are as follows:
* Create new project in google cloud console
 * ID of the project will be used in Config.PubSubProject
* Create service credentials for this project
 * Path to downloaded credentials file should be in env variable GOOGLE_APPLICATION_CREDENTIALS
 * Choose "Pub/Sub Editor" role for the credential
* Enable Pub/Sub API in cloud console
* Create new topic in the Pub/Sub (say "google-chat")
 * Use the value of "Topic Name" (**not** "Topic ID") for Config.TopicName (e.g. /project/<proj_name>/topics/<topic_name>)
* Modify permissions on created topic so that
 "chat-api-push@system.gserviceaccount.com" has Pub/Sub Publisher permissions
* Enable hangouts chat api in Cloud Console
* Go to hangouts chat API config in the Cloud Console and fill in info
 * Connection settings - use Pub/Sub and fill in topic string you created
 above

Config.SubscriptionName should be unique for each environment or you'll not
process messages correctly. If you encounter issues make sure your credentials
are correct and permissions for topics/queues are set up correctly.

Config.WelcomeMessage is sent each time the bot joins a new room or private chat.

Full example is here:
```Go
package main

import (
	"os"

	"github.com/go-chat-bot/bot/google-chat"
	_ "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() {
	googlechat.Run(&googlechat.Config{
		PubSubProject: os.Getenv("HANGOUTS_PROJECT"),
		TopicName: os.Getenv("HANGOUTS_TOPIC"),
		SubscriptionName: os.Getenv("HANGOUTS_SUB"),
		WelcomeMessage: os.Getenv("HANGOUTS_WELCOME"),
}

```

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

[go]: http://golang.org
[go-ircevent]: https://github.com/thoj/go-ircevent
[slack]: http://slack.com
[giphy.com]: http://giphy.com
[thecatapi.com]: http://thecatapi.com

go-chat-bot

Framework to build a bot for desired chat services including LINE, Slack, Gitter, and more.

[![Go Reference](https://pkg.go.dev/badge/github.com/oklahomer/go-sarah/v4.svg)](https://pkg.go.dev/github.com/oklahomer/go-sarah/v4)
[![Go Report Card](https://goreportcard.com/badge/github.com/oklahomer/go-sarah/v4)](https://goreportcard.com/report/github.com/oklahomer/go-sarah/v4)
![CI Status](https://github.com/oklahomer/go-sarah/actions/workflows/ci.yml/badge.svg?branch=master)
[![Coverage Status](https://coveralls.io/repos/github/oklahomer/go-sarah/badge.svg?branch=master)](https://coveralls.io/github/oklahomer/go-sarah?branch=master)
[![Maintainability](https://api.codeclimate.com/v1/badges/a2f0df359bec1552b28f/maintainability)](https://codeclimate.com/github/oklahomer/go-sarah/maintainability)
[![Join the chat at https://gitter.im/go-sarah-dev/community](https://badges.gitter.im/go-sarah-dev/community.svg)](https://gitter.im/go-sarah-dev/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

# Introduction
Sarah is a general-purpose bot framework named after the author's firstborn daughter.

This comes with a unique feature called "stateful command" as well as some basic features such as commands and scheduled tasks.
In addition to those fundamental features, this project provides rich life cycle management including _**[live configuration update](https://github.com/oklahomer/go-sarah/wiki/Live-Configuration-Update)**_, _**[customizable alerting mechanism](https://github.com/oklahomer/go-sarah/wiki/Alerter)**_, _**automated [command](https://github.com/oklahomer/go-sarah/wiki/CommandPropsBuilder)\/[task](https://github.com/oklahomer/go-sarah/wiki/ScheduledTaskPropsBuilder) (re)building**_, and _**[panic-proofed concurrent command/task execution](https://github.com/oklahomer/go-sarah/wiki/Worker)**_.

Such features are achieved with a composition of fine-grained components.
Each component has its own interface and a default implementation, so developers are free to customize their bot experience by replacing the default implementation for a particular component with their own implementation.
Thanks to such segmentalized lifecycle management architecture, the [adapter component](https://github.com/oklahomer/go-sarah/wiki/Default-Bot-and-Adapter) to interact with each chat service has fewer responsibilities compared to other bot frameworks;
An adapter developer may focus on implementing the protocol to interact with the corresponding chat service.
To take a look at those components and their relations, see [Components](https://github.com/oklahomer/go-sarah/wiki/Components).

# IMPORTANT NOTICE
## v4 Release
This is the fourth major version of `go-sarah`, which involves some architectural changes:
- `sarah.NewBot` now returns a single value: `sarah.Bot`
- Utility packages including logger, retry, and worker are now hosted by `github.com/oklahomer/go-kasumi`

## v3 Release
This is the third major version of `go-sarah`, which introduces the Slack adapter's improvement to support both RTM and Events API.
Breaking interface changes for the Slack adapter was inevitable and that is the sole reason for this major version up.
Other than that, this does not include any breaking change.
See [Migrating from v2.x to v3.x](https://github.com/oklahomer/go-sarah/wiki/Migrating-from-v2.x-to-v3.x) for details.

## v2 Release
The second major version introduced some breaking changes to `go-sarah`.
This version still supports and maintains all functionalities, while better interfaces for easier integration are introduced.
See [Migrating from v1.x to v2.x](https://github.com/oklahomer/go-sarah/wiki/Migrating-from-v1.x-to-v2.x) to migrate from the older version.

# Supported Chat Services/Protocols
Although a developer may implement `sarah.Adapter` to integrate with the desired chat service,
some adapters are provided as reference implementations:
- [Slack](https://github.com/oklahomer/go-sarah/tree/master/slack)
- [Gitter](https://github.com/oklahomer/go-sarah/tree/master/gitter)
- [XMPP](https://github.com/oklahomer/go-sarah-xmpp)
- [LINE](https://github.com/oklahomer/go-sarah-line)

# At a Glance
## General Command Execution
![hello world](/doc/img/hello.png)

Above is a general use of `go-sarah`.
Registered commands are checked against the user input and the matching one is executed;
when a user inputs ".hello," hello command is executed and a message "Hello, 世界" is returned.

## Stateful Command Execution
The below image depicts how a command with a user's **conversational context** works.
The idea and implementation of "user's conversational context" is `go-sarah`'s signature feature that makes a bot command "**state-aware**."

![](/doc/img/todo_captioned.png)

The above example is a good way to let a user input a series of arguments in a conversational manner.
Below is another example that uses a stateful command to entertain the user.

![](/doc/img/guess_captioned.png)

## Example Code
Following is the minimal code that implements such general command and stateful command introduced above.
In this example, two ways to implement [`sarah.Command`](https://github.com/oklahomer/go-sarah/wiki/Command) are shown.
One simply implements `sarah.Command` interface; while another uses `sarah.CommandPropsBuilder` for lazy construction.
Detailed benefits of using `sarah.CommandPropsBuilder` and `sarah.CommandProps` are described at its wiki page, [CommandPropsBuilder](https://github.com/oklahomer/go-sarah/wiki/CommandPropsBuilder).

For more practical examples, see [./examples](https://github.com/oklahomer/go-sarah/tree/master/examples).

```go
package main

import (
	"context"
	"fmt"
	"github.com/oklahomer/go-sarah/v4"
	"github.com/oklahomer/go-sarah/v4/slack"
	
	"os"
	"os/signal"
	"syscall"
	
	// Below packages register commands in their init().
	// Importing with a blank identifier will do the magic.
	_ "guess"
	_ "hello"
)

func main() {
	// Set up Slack adapter
	setupSlack()
	
	// Prepare Sarah's core context.
	ctx, cancel := context.WithCancel(context.Background())

	// Run
	config := sarah.NewConfig()
	err := sarah.Run(ctx, config)
	if err != nil {
		panic(fmt.Errorf("failed to run: %s", err.Error()))
	}
	
	// Stop when a signal is sent.
	c := make(chan os.Signal, 1)
 	signal.Notify(c, syscall.SIGTERM)
 	select {
 	case <-c:
 		cancel()
 
 	}
}

func setupSlack() {
	// Set up slack adapter.
	slackConfig := slack.NewConfig()
	slackConfig.Token = "REPLACE THIS"
	adapter, err := slack.NewAdapter(slackConfig, slack.WithRTMPayloadHandler(slack.DefaultRTMPayloadHandler))
	if err != nil {
		panic(fmt.Errorf("faileld to setup Slack Adapter: %s", err.Error()))
	}

	// Set up an optional storage so conversational contexts can be stored.
	cacheConfig := sarah.NewCacheConfig()
	storage := sarah.NewUserContextStorage(cacheConfig)

	// Set up a bot with Slack adapter and a default storage.
	bot := sarah.NewBot(adapter, sarah.BotWithStorage(storage))
	
	sarah.RegisterBot(bot)
}
```

---

```go
package guess

import (
	"context"
	"github.com/oklahomer/go-sarah/v4"
	"github.com/oklahomer/go-sarah/v4/slack"
	"math/rand"
	"strconv"
	"strings"
	"time"
)

func init() {
	sarah.RegisterCommandProps(props)
}

var props = sarah.NewCommandPropsBuilder().
	BotType(slack.SLACK).
	Identifier("guess").
	Instruction("Input .guess to start a game.").
	MatchFunc(func(input sarah.Input) bool {
		return strings.HasPrefix(strings.TrimSpace(input.Message()), ".guess")
	}).
	Func(func(ctx context.Context, input sarah.Input) (*sarah.CommandResponse, error) {
		// Generate an answer value at the very beginning.
		rand.Seed(time.Now().UnixNano())
		answer := rand.Intn(10)

		// Let a user guess the right answer.
		return slack.NewResponse(input, "Input number.", slack.RespWithNext(func(c context.Context, i sarah.Input) (*sarah.CommandResponse, error){
			return guessFunc(c, i, answer)
		}))
	}).
	MustBuild()

func guessFunc(_ context.Context, input sarah.Input, answer int) (*sarah.CommandResponse, error) {
	// For handiness, create a function that recursively calls guessFunc until the user input the right answer.
	retry := func(c context.Context, i sarah.Input) (*sarah.CommandResponse, error) {
		return guessFunc(c, i, answer)
	}

	// See if the user inputs a valid number.
	guess, err := strconv.Atoi(strings.TrimSpace(input.Message()))
	if err != nil {
		return slack.NewResponse(input, "Invalid input format.", slack.RespWithNext(retry))
	}

	// If the guess is right, tell the user and finish the current user context.
	// Otherwise, let the user input the next guess with bit of a hint.
	if guess == answer {
		return slack.NewResponse(input, "Correct!")
	} else if guess > answer {
		return slack.NewResponse(input, "Smaller!", slack.RespWithNext(retry))
	} else {
		return slack.NewResponse(input, "Bigger!", slack.RespWithNext(retry))
	}
}
```

---

```go
package hello

import (
	"context"
	"github.com/oklahomer/go-sarah/v4"
	"github.com/oklahomer/go-sarah/v4/slack"
	"strings"
)

func init() {
 sarah.RegisterCommand(slack.SLACK, &command{})	
}

type command struct {
}

var _ sarah.Command = (*command)(nil)

func (hello *command) Identifier() string {
	return "hello"
}

func (hello *command) Execute(_ context.Context, i sarah.Input) (*sarah.CommandResponse, error) {
	return slack.NewResponse(i, "Hello!")
}

func (hello *command) Instruction(input *sarah.HelpInput) string {
	if 12 < input.SentAt().Hour() {
		// This command is only active in the morning.
		// Do not show instruction in the afternoon.
		return ""
	}
	return "Input .hello to greet"
}

func (hello *command) Match(input sarah.Input) bool {
	return strings.TrimSpace(input.Message()) == ".hello"
}

```

# Supported Golang Versions
Official [Release Policy](https://golang.org/doc/devel/release.html#policy) says "each major Go release is supported
until there are two newer major releases." Following this policy would help this project enjoy the improvements
introduced in the later versions. However, not all projects can immediately switch to a newer environment. 
Migration could especially be difficult when this project cuts off the older version's support right after a new major Go
release.

As a transition period, this project includes support for one older version than the Go project does.
Such a version is guaranteed to be listed in [.travis.ci](https://github.com/oklahomer/go-sarah/blob/master/.travis.yml).
In other words, new features/interfaces introduced in 1.10 can be used in this project only after 1.12 is out.

# Further Readings
- [Project wiki](https://github.com/oklahomer/go-sarah/wiki)
- [GoDoc](https://pkg.go.dev/github.com/oklahomer/go-sarah/v4)
- [Example codes](https://github.com/oklahomer/go-sarah/tree/master/examples)

go-sarah

Generated from official docs Go client library for accessing Telegram Bot API, with batteries for building complex bots included.

go-tg

Pure Golang Telegram Bot API wrapper, generated from swagger file, session-based router, and middleware.

# go-tgbot [![godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/olebedev/go-tgbot)

> Pure Golang telegram bot API wrapper generated from swagger definition, session-based routing and middlewares.

### Usage benefits

1. **No need to learn any other library API.** You will use methods with payload exactly like it presented on telegram bot API description page. With only couple trade-offs, b/c of telegram bot API is generics a bit.
2. **All models and methods are being supported.** The models and methods were generated from `swagger.yaml` description file. So, new entities/methods could be added by describing in the YAML swagger file. This approach allows validating the description, avoid typos and develop fast.
3. `easyjson` is plugged. So, **it's fast**.
4. **`context.Context` based** HTTP client
5. **Session-based routing**, not only message text based.

### Client

Client package could be used as regular `go-swagger` client library without using Router. There are the only two additional features over `go-swagger`, a possibility to setup token by default(It solved as an [interface checking](https://github.com/olebedev/go-tgbot/blob/master/client.go#L36)) and [API throttling](https://github.com/olebedev/go-tgbot/blob/master/client.go#L26) for 30 calls per second([see more info](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits-how-do-i-avoid-this)). 

Example:

```go
package main

import (
	"context"
	"flag"
	"log"
	"time"

	tgbot "github.com/olebedev/go-tgbot"
	"github.com/olebedev/go-tgbot/client/users"
)

var token *string

func main() {
	token = flag.String("token", "", "telegram bot token")
	flag.Parse()

	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	api := tgbot.NewClient(ctx, *token)

	log.Println(api.Users.GetMe(nil))

	// Also, every calls could be done with given context
	ctx, cancel = context.WithTimeout(ctx, 10*time.Second)
	defer cancel()

	_, err := api.Users.GetMe(
		users.NewGetMeParams().
			WithContext(ctx),
	)

	if err != nil {
		// users.NewGetMeBadRequest()
		if e, ok := err.(*users.GetMeBadRequest); ok {
			log.Println(e.Payload.ErrorCode, e.Payload.Description)
		}
	}
}
```

Since swagger covers many other platforms/technologies the same libraries could be generated for them too. See the source here - [`swagger.yaml`](https://github.com/olebedev/go-tgbot/blob/master/swagger.yaml).  
Also, have a look at [Swagger UI for telegram API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/olebedev/go-tgbot/master/swagger.yaml#/)(`master` branch).

### Router

The Router allows binding between kinds of updates and handlers, which are being checked via regexp. Router includes client API library as embedded struct. Example:

```go
package main

import (
	"context"
	"flag"
	"log"
	"os"

	tgbot "github.com/olebedev/go-tgbot"
	"github.com/olebedev/go-tgbot/client/messages"
	"github.com/olebedev/go-tgbot/models"
)

var token *string

func main() {
	token = flag.String("token", "", "telegram bot token")
	flag.Parse()

	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	r := tgbot.New(ctx, *token)

	// setup global middleware
	r.Use(tgbot.Recover)
	r.Use(tgbot.Logger(os.Stdout))

	// modify path to be able to match user's commands via router
	r.Use(func(c *tgbot.Context) error {
		c.Path = c.Path + c.Text
		return nil
	})

	// bind handler
	r.Bind(`^/message/(?:.*)/text/start(?:\s(.*))?$`, func(c *tgbot.Context) error {
		log.Println(c.Capture)             // - ^ from path
		log.Println(c.Update.Message.Text) // or c.Text

		// send greeting message back
		message := "hi there what's up"
		resp, err := r.Messages.SendMessage(
			messages.NewSendMessageParams().WithBody(&models.SendMessageBody{
				Text:   &message,
				ChatID: c.Update.Message.Chat.ID,
			}),
		)
		if err != nil {
			return err
		}
		if resp != nil {
			log.Println(resp.Payload.Result.MessageID)
		}
		return nil
	})

	if err := r.Poll(ctx, models.AllowedUpdateMessage); err != nil {
		log.Fatal(err)
	}
}
```

Default string representation of any kind of an update could be found here - [`router.go`](https://github.com/olebedev/go-tgbot/blob/master/router.go#L96-L226).

Router implements `http.Handler` interface to be able to serve HTTP as well. But, it's not recommended because webhooks are much much slower than polling.

More examples can be found at [godoc](https://godoc.org/github.com/olebedev/go-tgbot).

---

See [the documentation](https://godoc.org/github.com/olebedev/go-tgbot) for more details.

### LICENSE

http://www.apache.org/licenses/LICENSE-2.0


go-tgbot

# go-twitch-irc [![Coverage Status](https://coveralls.io/repos/github/gempir/go-twitch-irc/badge.svg?branch=master)](https://coveralls.io/github/gempir/go-twitch-irc?branch=master)

This is an irc client for connecting to twitch. It handles the annoying stuff like irc tag parsing.
I highly recommend reading the documentation below, but this readme gives a basic overview of the functionality.

Documentation: https://pkg.go.dev/github.com/gempir/go-twitch-irc/v4?tab=doc

## Getting Started
```go
package main

import (
	"fmt"

	"github.com/gempir/go-twitch-irc/v4"
)

func main() {
	// or client := twitch.NewAnonymousClient() for an anonymous user (no write capabilities)
	client := twitch.NewClient("yourtwitchusername", "oauth:123123123")

	client.OnPrivateMessage(func(message twitch.PrivateMessage) {
		fmt.Println(message.Message)
	})

	client.Join("gempir")

	err := client.Connect()
	if err != nil {
		panic(err)
	}
}
```
### Available Data

The twitch.User and MessageType structs reflect the data Twitch provides, minus any fields that have been marked as deprecated:
```go
type User struct {
	ID            string
	Name          string
	DisplayName   string
	Color         string
	Badges        map[string]int
	IsBroadcaster bool
	IsMod         bool
	IsVip         bool
}

type WhisperMessage struct {
	User User

	Raw       string
	Type      MessageType
	RawType   string
	Tags      map[string]string
	Message   string
	Target    string
	MessageID string
	ThreadID  string
	Emotes    []*Emote
	Action    bool
}

type PrivateMessage struct {
	User User

	Raw     string
	Type    MessageType
	RawType string
	Tags    map[string]string
	Message string
	Channel string
	RoomID  string
	ID      string
	Time    time.Time
	Emotes  []*Emote
	Bits    int
	Action  bool
}

type ClearChatMessage struct {
	Raw            string
	Type           MessageType
	RawType        string
	Tags           map[string]string
	Message        string
	Channel        string
	RoomID         string
	Time           time.Time
	BanDuration    int
	TargetUserID   string
	TargetUsername string
}

type ClearMessage struct {
	Raw         string
	Type        MessageType
	RawType     string
	Tags        map[string]string
	Message     string
	Channel     string
	Login       string
	TargetMsgID string
}

type RoomStateMessage struct {
	Raw     string
	Type    MessageType
	RawType string
	Tags    map[string]string
	Message string
	Channel string
	RoomID  string
	State   map[string]int
}

type UserNoticeMessage struct {
	User User

	Raw       string
	Type      MessageType
	RawType   string
	Tags      map[string]string
	Message   string
	Channel   string
	RoomID    string
	ID        string
	Time      time.Time
	Emotes    []*Emote
	MsgID     string
	MsgParams map[string]string
	SystemMsg string
}

type UserStateMessage struct {
	User User

	Raw       string
	Type      MessageType
	RawType   string
	Tags      map[string]string
	Message   string
	Channel   string
	EmoteSets []string
}

type GlobalUserStateMessage struct {
	User User

	Raw       string
	Type      MessageType
	RawType   string
	Tags      map[string]string
	EmoteSets []string
}

type NoticeMessage struct {
	Raw     string
	Type    MessageType
	RawType string
	Tags    map[string]string
	Message string
	Channel string
	MsgID   string
}

type UserJoinMessage struct {
	// Channel name
	Channel string

	// User name
	User string
}

type UserPartMessage struct {
	// Channel name
	Channel string

	// User name
	User string
}
```

For unsupported message types, we return RawMessage:
```go
type RawMessage struct {
	Raw     string
	Type    MessageType
	RawType string
	Tags    map[string]string
	Message string
}
```

### Available Methods

ParseMessage parses a raw Twitch IRC message into a User and a message object. User can be nil.

```go
func ParseMessage(line string) (*User, interface{})
```

### Client Methods

These are the available methods of the client so you can get your bot going:

```go
func (c *Client) Say(channel, text string)
func (c *Client) Join(channel string)
func (c *Client) Depart(channel string)
func (c *Client) Userlist(channel string) ([]string, error)
func (c *Client) Connect() error
func (c *Client) Disconnect() error
func (c *Client) Latency() (latency time.Duration, err error)
```

### Options

On your client you can configure multiple options:
```go
client.IrcAddress = "127.0.0.1:3030" // for custom irc server
client.TLS = false // enabled by default, will connect to non TLS server of twitch when off or the given client.IrcAddress
client.SetupCmd = "LOGIN custom_command_here" // Send a custom command on successful IRC connection, before authentication.
client.Capabilities = []string{twitch.TagsCapability, twitch.CommandsCapability} // Customize which capabilities are sent
client.SetJoinRateLimiter(twitch.CreateVerifiedRateLimiter()) // If you have a verified bot or other needs use this to set a custom rate limiter
```

Option modifications must be done before calling Connect on the client.

#### Capabilities

By default, the client sends along these capabilities ([Tags](https://dev.twitch.tv/docs/irc/tags), [Commands](https://dev.twitch.tv/docs/irc/commands)).  

### Callbacks

These callbacks are available to pass to the client:
```go
client.OnConnect(func() {})
client.OnPrivateMessage(func(message PrivateMessage) {})
client.OnWhisperMessage(func(message WhisperMessage) {})
client.OnClearChatMessage(func(message ClearChatMessage) {})
client.OnClearMessage(func(message ClearMessage) {})
client.OnRoomStateMessage(func(message RoomStateMessage) {})
client.OnUserNoticeMessage(func(message UserNoticeMessage) {})
client.OnUserStateMessage(func(message UserStateMessage) {})
client.OnGlobalUserStateMessage(func(message GlobalUserStateMessage) {})
client.OnNoticeMessage(func(message NoticeMessage) {})
client.OnUserJoinMessage(func(message UserJoinMessage) {})
client.OnUserPartMessage(func(message UserPartMessage) {})
client.OnSelfJoinMessage(func(message UserJoinMessage) {})
client.OnSelfPartMessage(func(message UserPartMessage) {})
```

### Message Types

If you ever need more than basic PRIVMSG, this might be for you.
These are the message types currently supported:

    WHISPER
    PRIVMSG
    CLEARCHAT
    CLEARMSG
    ROOMSTATE
    USERNOTICE
    USERSTATE
    GLOBALUSERSTATE
    NOTICE
    JOIN
    PART


go-twitch-irc

A golang implementation of a console-based trading bot for cryptocurrency exchanges.

<img src="https://res.cloudinary.com/saniales-github/image/upload/v1541856660/saniales/golang-crypto-trading-bot/logo.png" width="360">

 <a href="https://github.com/avelino/awesome-go#other-software"><img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Listed on Awesome Go"></img></a>
 <a href="https://github.com/saniales/golang-crypto-trading-bot/actions"><img src="https://github.com/saniales/golang-crypto-trading-bot/workflows/Go%20Build/badge.svg?branch=develop" alt="Develop Branch Build Status"></img></a>
 <a href="https://godoc.org/github.com/saniales/golang-crypto-trading-bot"><img src="https://godoc.org/github.com/saniales/golang-crypto-trading-bot?status.svg" alt="Godoc reference"></a>
 <a href="https://github.com/saniales/golang-crypto-trading-bot/releases"><img src="https://img.shields.io/github/release/saniales/golang-crypto-trading-bot.svg" alt="Last Release"></a>
 <a href="https://github.com/saniales/golang-crypto-trading-bot/LICENSE"><img src="https://img.shields.io/github/license/saniales/golang-crypto-trading-bot.svg?maxAge=2592000" alt="License"></a>
 <a href="https://goreportcard.com/report/github.com/saniales/golang-crypto-trading-bot"><img src="https://goreportcard.com/badge/github.com/saniales/golang-crypto-trading-bot" alt="Goreportcard" /></a>


# Golang Crypto Trading Bot

A golang implementation of a console-based trading bot for cryptocurrency exchanges.

## Usage

Download a release or directly build the code from this repository.

``` bash
go get github.com/saniales/golang-crypto-trading-bot
```

If you need to, you can create a strategy and bind it to the bot:

``` go
import bot "github.com/saniales/golang-crypto-trading-bot/cmd"

func main() {
 bot.AddCustomStrategy(examples.MyStrategy)
 bot.Execute()
}
```

For strategy reference see the [Godoc documentation](https://godoc.org/github.com/saniales/golang-crypto-trading-bot).

## Simulation Mode

If enabled, the bot will do paper trading, as it will execute fake orders in a sandbox environment.

A Fake balance for each coin must be specified for each exchange if simulation mode is enabled.

## Supported Exchanges

| Exchange Name | REST Supported | Websocket Support |
| ------------- |------------------ | ----------------- |
| Bittrex | Yes | No |
| Poloniex | Yes | Yes |
| Kraken | Yes (no withdraw) | No |
| Bitfinex | Yes | Yes |
| Binance | Yes | Yes |
| Kucoin | Yes | No |
| HitBtc | Yes | Yes |

## Configuration file template

Create a configuration file from this example or run the `init` command of the compiled executable.

``` yaml
simulation_mode: true # if you want to enable simulation mode.
exchange_configs:
 - exchange: bitfinex
 public_key: bitfinex_public_key
 secret_key: bitfinex_secret_key
 deposit_addresses:
 BTC: bitfinex_deposit_address_btc
 ETH: bitfinex_deposit_address_eth
 ZEC: bitfinex_deposit_address_zec
 fake_balances: # used only if simulation mode is enabled, can be omitted if not enabled.
 BTC: 100
 ETH: 100
 ZEC: 100
 ETC: 100
 - exchange: hitbtc
 public_key: hitbtc_public_key
 secret_key: hitbtc_secret_key
 deposit_addresses:
 BTC : hitbtc_deposit_address_btc
 ETH: hitbtc_deposit_address_eth
 ZEC: hitbtc_deposit_address_zec
 fake_balances:
 BTC: 100
 ETH: 100
 ZEC: 100
 ETC: 100
strategies:
 - strategy: strategy_name
 markets:
 - market: ETH-BTC
 bindings:
 - exchange: bitfinex
 market_name: ETHBTC
 - exchange: hitbtc
 market_name: ETHBTC
 - market: ZEC-BTC
 bindings:
 - exchange: bitfinex
 market_name: ZECBTC
 - exchange: hitbtc
 market_name: ZECBTC
 - market: ETC-BTC
 bindings:
 - exchange: bitfinex
 market_name: ETCBTC
 - exchange: hitbtc
 market_name: ETCBTC
```

## Donate

Feel free to donate:

| METHOD | ADDRESS |
|-------- |-------------------------------------------- |
| Paypal | https://paypal.me/AlessandroSanino |
| BTC | 1DVgmv6jkUiGrnuEv1swdGRyhQsZjX9MT3 |
| XVG | DFstPiWFXjX8UCyUCxfeVpk6JkgaLBSNvS |
| ETH | 0x2fe7bd8a41e91e9284aada0055dbb15ecececf02 |
| USDT | 18obCEVmbT6MHXDcPoFwnUuCmkttLbK5Xo |

Golang CryptoTrading Bot

Simple Go [VK](https://vk.com) bot library.

# Go VK bot package
 
[![Build Status](https://travis-ci.org/nikepan/govkbot.svg?branch=master)](https://travis-ci.org/nikepan/govkbot)
[![codecov](https://codecov.io/gh/nikepan/govkbot/branch/master/graph/badge.svg)](https://codecov.io/gh/nikepan/govkbot)
[![Go Report Card](https://goreportcard.com/badge/github.com/nikepan/govkbot)](https://goreportcard.com/report/github.com/nikepan/govkbot)
[![godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/nikepan/govkbot)


This is simple VK.com bot API.


> At 2019-03-01 VK was restrict messages.send for user_tokens. This bot can work with group_token, and access to chat members if has admin rights in chat. You can use v1.0.1 also, if you need only user_token access.


It can:

* Reply to messages (private and chat)  
* Send greetings message when invited to chat
* Add and remove mutual friends
* Send notifies to admin

Installatioin:

Use `go mod`
For old Go versions you can also use
`go get github.com/nikepan/govkbot/v2`

For work you need get VK access token with rights: messages,friends,offline (see below).


# Quickstart

```Go
package main
import "github.com/nikepan/govkbot/v2"
import "log"

var VKAdminID = 3759927
var VKToken = "efjr98j9fj8jf4j958jj4985jfj9joijerf0fj548jf94jfiroefije495jf48"

func helpHandler(m *govkbot.Message) (reply string) {
  return "help received"
}

func startHandler(m *govkbot.Message) (reply govkbot.Reply) {
	keyboard := govkbot.Keyboard{Buttons: make([][]govkbot.Button, 0)}
	button := govkbot.NewButton("/help", nil)
	row := make([]govkbot.Button, 0)
	row = append(row, button)
	keyboard.Buttons = append(keyboard.Buttons, row)

	return govkbot.Reply{Msg: availableCommands, Keyboard: &keyboard}
}

func errorHandler(m *govkbot.Message, err error) {
  log.Fatal(err.Error())
}

func main() {
    //govkbot.HandleMessage("/", anyHandler)
    //govkbot.HandleMessage("/me", meHandler)
    govkbot.HandleMessage("/help", helpHandler)
    govkbot.HandleAdvancedMessage("/start", startHandler)

    //govkbot.HandleAction("chat_invite_user", inviteHandler)
    //govkbot.HandleAction("chat_kick_user", kickHandler)
    //govkbot.HandleAction("friend_add", addFriendHandler)
    //govkbot.HandleAction("friend_delete", deleteFriendHandler)

    govkbot.HandleError(errorHandler)

    govkbot.SetAutoFriend(true) // enable auto accept/delete friends

    govkbot.SetDebug(true) // log debug messages

    // Optional Direct VK API access
    govkbot.SetAPI(VKToken, "", "") // Need only before Listen, if you use direct API
    me, _ := govkbot.API.Me() // call API method
    log.Printf("current user: %+v\n", me.FullName())
    // Optional end

    govkbot.Listen(VKToken, "", "", VKAdminID)
}
```
# Getting group token

Open group manage and select "Work with API"

# Getting user token (most likely will not work for messages)

You need standalone vk app_id. You can use any app_id from https://vk.com/apps?act=wingames, for example 4775211 
 (Or you can create own app and get app_id on page https://vk.com/editapp?act=create (standalone app))

You can get token from you server ip with this node.js package:
https://www.npmjs.com/package/vk-auth (you need login, pass and app_id)


To manual get token you need:

1. Open in browser with logged in VK (you must use IP, where you want run bot)
```
 https://oauth.vk.com/authorize?client_id={{app_id}}&scope=offline,groups,messages,friends&display=page&response_type=token&redirect_uri=https://oauth.vk.com/blank.html
 ```
2. Copy token query parameter from URL string. Token valid only for IP from what you get it.


If you receive validation check (for example, you use ip first time)
```json
{"error":{"error_code":17,"error_msg":"Validation required: please open redirect_uri in browser ...", 
"redirect_uri":"https://m.vk.com/login?act=security_check&api_hash=Qwerty1234567890"}}
```
you can use https://github.com/Yashko/vk-validation-node.



govkbot

# hanu - Go for Slack Bots!

[![Current Release](https://badgen.now.sh/github/release/sbstjn/hanu)](https://github.com/sbstjn/hanu/releases)
[![MIT License](https://badgen.now.sh/badge/License/MIT/blue)](https://github.com/sbstjn/hanu/blob/master/LICENSE.md)
[![Read Tutorial](https://badgen.now.sh/badge/Read/Tutorial/orange)](https://sbstjn.com/host-golang-slackbot-on-heroku-with-hanu.html)
[![Code Example](https://badgen.now.sh/badge/Code/Example/cyan)](https://github.com/sbstjn/hanu-example)

The `Go` framework **hanu** is your best friend to create [Slack](https://slackhq.com) bots! **hanu** uses [allot](https://github.com/sbstjn/allot) for easy command and request parsing (e.g. `whisper <word>`) and runs fine as a [Heroku worker](https://devcenter.heroku.com/articles/background-jobs-queueing). All you need is a [Slack API token](https://api.slack.com/bot-users) and you can create your first bot within seconds! Just have a look at the [hanu-example](https://github.com/sbstjn/hanu-example) bot or [read my tutorial](https://sbstjn.com/host-golang-slackbot-on-heroku-with-hanu.html) …

### 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](https://github.com/sbstjn/hanu-example) bot to get started.

```go
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](https://github.com/sbstjn/allot) for parsing `cmd <param1:string> <param2:integer>` strings
- [golang.org/x/net/websocket](http://golang.org/x/net/websocket) for websocket communication with Slack

## Credits

- [Host Go Slackbot on Heroku](https://sbstjn.com/host-golang-slackbot-on-heroku-with-hanu.html)
- [OpsDash article about Slack Bot](https://www.opsdash.com/blog/slack-bot-in-golang.html)

hanu

official trading and market-making bot for the [Stellar](https://www.stellar.org/) DEX. Works out-of-the-box, written in Golang, compatible with centralized exchanges and custom trading strategies.

Kelp

Larry 🐦 is a really simple Twitter bot generator that tweets random repositories from Github built in Go.

# Larry 🐦
[![Go](https://github.com/ezeoleaf/larry/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/ezeoleaf/larry/actions/workflows/go.yml)
[![Coverage Status](https://coveralls.io/repos/github/ezeoleaf/larry/badge.svg?branch=main)](https://coveralls.io/github/ezeoleaf/larry?branch=main)
[![Go Report Card](https://goreportcard.com/badge/github.com/ezeoleaf/larry)](https://goreportcard.com/report/github.com/ezeoleaf/larry)
[![MIT License](https://img.shields.io/github/license/ezeoleaf/larry?style=flat-square)](https://github.com/ezeoleaf/larry/blob/main/LICENSE)
[![Contribute with Gitpod](https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod)](https://gitpod.io/#https://github.com/ezeoleaf/larry)

Larry is a Golang cli bot that tweets random Github repositories.

## Disclaimer

I hold no liability for what you do with this bot or what happens to you by using this bot. Abusing this bot *can* get you banned from Twitter, so make sure to read up on [proper usage](https://support.twitter.com/articles/76915-automation-rules-and-best-practices) of the Twitter API.

## Running bots

- [GolangRepos](https://twitter.com/GolangRepos): Tweets repositories from Github that contain the "golang" topic
- [RustRepos](https://twitter.com/RustRepos): Tweets repositories from Github that contain the "rust" topic
- [MLRepositories](https://twitter.com/MLRepositories): Tweets repositories from Github that contain the "machine-learning" topic
- [CryptoRepos](https://twitter.com/CryptoRepos): Tweets repositories from Github that contain the "crypto" topic

## Installation

You can install Larry by cloning the repo and using `go install`

```bash
git clone https://github.com/ezeoleaf/larry.git
cd larry/cmd/larry
go install
```

You can also use make for building the project and generating an executable:
```bash
git clone https://github.com/ezeoleaf/larry.git
cd larry
make build
```

Or you can just run it on the go
```bash
git clone https://github.com/ezeoleaf/larry.git
cd larry
go run . [options]
```

## Usage

### Configuring the bot

Before running the bot, you must first set it up so it can connect to Github and the publisher's API.

To do this, you will need to setup the following environment variables:

- GITHUB_ACCESS_TOKEN

For generating Github access token you can follow this [guide](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)

### Providers and Publishers

For information on publishers and providers click [here](PublishersAndProviders.md)

### Running the bot

To run the bot, you have two ways.

If you have installed the bot, you can run it using
 `larry [options]`

If you want to run it without installing it globally you can use
 `go run . [options]`

Example:

`larry -h`

As a response you will see the entire options available

```
NAME:
 Larry - Bot that publishes information from providers to different publishers

USAGE:
 larry [global options] command [command options] [arguments...]

AUTHORS:
 @ezeoleaf <ezeoleaf@gmail.com>
 @beesaferoot <hikenike6@gmail.com>
 @shubhcoder
 @kannav02
 @siddhant-k-code <siddhantkhare2694@gmail.com>
 @savagedev

COMMANDS:
 help, h Shows a list of commands or help for one command

GLOBAL OPTIONS:
 --topic value, -t value topic for searching repos
 --lang value, -l value language for searching repos
 --time value, -x value periodicity of tweet in minutes (default: 15)
 --cache value, -r value size of cache for no repeating repositories (default: 50)
 --hashtag value, --ht value list of comma separated hashtags
 --tweet-language, --tl bool for allowing twetting the language of the repo (default: false)
 --safe-mode, --sf bool for safe mode. If safe mode is enabled, no repository is published (default: false)
 --provider value, --pr value provider where publishable content comes from (default: "github")
 --publisher value, --pub value list of comma separated publishers (default: "twitter")
 --content-file value, --cf value file containing content to publish
 --skip-csv-header, --sh bool to skip CSV file header. If true, then first record of CSV file is skipped (default: false)
 --blacklist value, --bl value optional file containing blacklisted repository Ids
 --help, -h show help (default: false)
```

For running the bot, the command will depend on whatever you want to tweet, but, for tweeting about React repositories every 30 minutes, you could use

&nbsp;&nbsp;`larry --topic react --time 30 --safe-mode`

For running the bot for Rust tweets every 15 minutes

&nbsp;&nbsp;`larry --lang rust --time 15`

For running the bot for Golang every 15 minutes and specifying a blacklist file named blacklist.txt

&nbsp;&nbsp;`larry --topic golang --time 15 --blacklist ./blacklist.txt`

For running the bot every 60 minutes using the "contentfile" provider and JSON file for content

&nbsp;&nbsp;`larry --time 60 --provider contentfile --content-file ./content.json`

For running the bot every 60 minutes using the "contentfile" provider to read CSV file for content and skipping the header record

&nbsp;&nbsp;`larry --time 60 --provider contentfile --content-file ./content.csv --skip-csv-header`


## Content Files

The `contentfile` provider serves content from CSV and JSON files.

### JSON Content File

When the `contentfile` provider receives a `content-file` filename with a `.json` extension, the provider serves random content from the JSON file. This file consists of an array of objects in the following format. ExtraData is an array of strings.

```json
[{
 "Title": "larry",
 "Subtitle": "Larry 🐦 is a bot generator that publishes random content from different providers built in Go",
 "URL": "github.com/ezeoleaf/larry",
 "ExtraData": ["68", "ezeoleaf", "golang"]
}]
```

### CSV Content File

When the `contentfile` provider receives a `content-file` filename with a `.csv` extension, the provider serves random content from the CSV file. Each field may or may not be enclosed in double quotes. The ExtraData strings start at field 4 of the record and a record can contain any number of elements. 

The following file has one record with three ExtraData strings.

```csv
The title,The subtitle,URL,ExtraString1,"ExtraString2,has comma",ExtraString3
```

An example CSV file with a header record followed by one record:

```csv
Title,Subtitle,URL,Stars,Author,Language,ExtraData1,ExtraData2,ExtraData3
larry,Larry 🐦 is a bot generator that publishes random content from different providers built in Go,github.com/ezeoleaf/larry,68,ezeoleaf,golang
```

Note: Every record in the CSV file, including the header record, must have the same number of fields otherwise an error will occur. This means if the records will have a variable number of ExtraData fields, each record having fewer than the maximum ExtraData fields must include empty ExtraData fields to match the maximum.

## Blacklist File

### Github Provider

For the `github` provider, the optional blacklist file consists of numeric GitHub repository IDs to exclude from the publishing process. These IDs can be found on the GitHub repository page source in the meta tag `octolytics-dimension-repository_id`.

An example blacklist file containing GitHub repository IDs. The file can contain comments using the # character, everything on the line after this character is ignored.

```csv
# Blacklisted repositories
123 # description of the respository
456
```

### Contentfile Provider

For the `contentfile` provider, the optional blacklist file consists of content titles to exclude from the publishing process.

## Have questions? Need help with the bot?

If you're having issues with or have questions about the bot, [file an issue](https://github.com/ezeoleaf/larry/issues) in this repository so anyone can get back to you.

Or feel free to contact me <ezeoleaf@gmail.com> :)

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=ezeoleaf/larry&type=Date)](https://star-history.com/#ezeoleaf/larry)

[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/H2H47X7QW)

larry

[![Build Status](https://travis-ci.org/zhulik/margelet.svg?branch=master)](https://travis-ci.org/zhulik/margelet)
# Margelet
Telegram Bot Framework for Go is based on [telegram-bot-api](https://gopkg.in/telegram-bot-api.v4)

It uses Redis to store it's states, configs and so on.

Any low-level interactions with Telegram Bot API(downloading files, keyboards and so on) should be performed through
[telegram-bot-api](https://gopkg.in/telegram-bot-api.v4).

Margelet is just a thin layer, that allows you to solve
basic bot tasks quickly and easy.

## Installation
`go get github.com/zhulik/margelet`

## Simple usage
```go
package main

import (
	"github.com/zhulik/margelet"
)

func main() {
	bot, err := margelet.NewMargelet("<your awesome bot name>", "<redis addr>", "<redis password>", 0, "your bot token", false)

	if err != nil {
		panic(err)
	}

	err = bot.Run()
	if err != nil {
		panic(err)
	}
}
```

Out of the box, margelet supports only `/help` command, it responds something like this

`/help - Show bot help`

## Concept
Margelet is based on some concepts:
* Message handlers
* Command handlers
* Session handlers
* Chat configs
* Inline handlers

### Message handlers
Message handler is a struct that implements Handler interface. It receives all chat messages dependant on bot's
[Privacy mode](https://core.telegram.org/bots#privacy-mode). It doesn't receive commands.

Simple example:
```go
package margelet_test

import (
	"../margelet"
)

// EchoHandler is simple handler example
type EchoHandler struct {
}

// Response send message back to author
func (handler EchoHandler) HandleMessage(m margelet.Message) error {
	_, err := m.QuickSend(m.Message().Text)
	return err
}

```

This handler will repeat any user's message back to chat.

Message helpers can be added to margelet with `AddMessageHandler` function:
```go
bot, err := margelet.NewMargelet("<your awesome bot name>", "<redis addr>", "<redis password>", 0, "your bot token", false)
bot.AddMessageHandler(EchoHandler{})
bot.Run()
```

### Command handlers
Command handler is struct that implements CommandHandler interface. CommandHandler can be subscribed on any command you need
and will receive all message messages with this command, only if there is no active session with this user in this chat

Simple example:
```go
package margelet

import (
	"fmt"
	"strings"
)

// HelpHandler Default handler for /help command. Margelet will add this automatically
type HelpHandler struct {
	Margelet *Margelet
}

// HandleCommand sends default help message
func (handler HelpHandler) HandleCommand(message Message) error {
	lines := []string{}
	for command, h := range handler.Margelet.CommandHandlers {
		lines = append(lines, fmt.Sprintf("/%s - %s", command, h.handler.HelpMessage()))
	}

	for command, h := range handler.Margelet.SessionHandlers {
		lines = append(lines, fmt.Sprintf("/%s - %s", command, h.handler.HelpMessage()))
	}

	_, err := message.QuickSend(strings.Join(lines, "\n"))
	return err
}

// HelpMessage return help string for HelpHandler
func (handler HelpHandler) HelpMessage() string {
	return "Show bot help"
}
```

Command handlers can be added to margelet with `AddCommandHandler` function:
```go
bot, err := margelet.NewMargelet("<your awesome bot name>", "<redis addr>", "<redis password>", 0, "your bot token", false)
bot.AddCommandHandler("help", HelpHandler{bot})
bot.Run()
```

### Session handlers
Session here is an interactive dialog with user, like [@BotFather](https://telegram.me/botfather) does. User runs session
with a command and then response to bot's questions until bot collects all needed information. It can be used for bot
configuration, for example.

**Session handlers API is still developing**

Session handler is struct that implements SessionHandler interface. Simple example:
```go
package margelet_test

import (
	"fmt"
	"strconv"

	"../margelet"
	"gopkg.in/telegram-bot-api.v4"
)

// SumSession - simple example session, that can sum numbers
type SumSession struct {
}

// HandleResponse - Handlers user response
func (s SumSession) HandleSession(session margelet.Session) error {
	switch len(session.Responses()) {
	case 0:
		session.QuickReply("Hello, please, write one number per message, after some iterations write 'end'.")
	default:
		if session.Message().Text == "end" {
			var sum int
			for _, m := range session.Responses() {
				n, _ := strconv.Atoi(m.Text)
				sum += n
			}
			session.QuickReply(fmt.Sprintf("Your sum: %d", sum))
			session.Finish()
			return nil
		}

		_, err := strconv.Atoi(session.Message().Text)
		if err != nil {
			session.QuickReply("Sorry, not a number")
			return err
		}
	}

	return nil
}

// CancelResponse - Chance to clean up everything
func (s SumSession) CancelSession(session margelet.Session) {
	//Clean up all variables only used in the session

}

func (session SumSession) response(bot margelet.MargeletAPI, message *tgbotapi.Message, msg tgbotapi.MessageConfig) {
	msg.ChatID = message.Chat.ID
	msg.ReplyToMessageID = message.MessageID
	msg.ReplyMarkup = tgbotapi.ForceReply{ForceReply: true, Selective: true}
	bot.Send(msg)
}

// HelpMessage return help string for SumSession
func (session SumSession) HelpMessage() string {
	return "Sum your numbers and print result"
}
```

Session handlers can be added to margelet with `AddSessionHandler` function:
```go
bot, err := margelet.NewMargelet("<your awesome bot name>", "<redis addr>", "<redis password>", 0, "your bot token", false)
bot.AddSessionHandler("help", SumSession{})
bot.Run()
```

On each user response it receives all previous user responses, so you can restore session state. HandleResponse return values
it important:
* first(bool), means that margelet should finish session, so return true if you receive all needed info from user, false otherwise
* second(err), means that bot cannot handle user's message. This message will not be added to session dialog history.
Return any error if you can handle user's message and return nil if message is accepted.

### Inline handlers
Inline handler is struct that implements InlineHandler interface. InlineHandler can be subscribed on any inline queries.

Simple example:
```go
package margelet_test

import (
	"github.com/zhulik/margelet"
	"gopkg.in/telegram-bot-api.v4"
)

type InlineImage struct {
}

func (handler InlineImage) HandleInline(bot margelet.MargeletAPI, query *tgbotapi.InlineQuery) error {
	testPhotoQuery := tgbotapi.NewInlineQueryResultPhoto(query.ID, "https://telegram.org/img/t_logo.png")
	testPhotoQuery.ThumbURL = "https://telegram.org/img/t_logo.png"

	config := tgbotapi.InlineConfig{
		InlineQueryID: query.ID,
		CacheTime: 2,
		IsPersonal: false,
		Results: []interface{}{testPhotoQuery},
		NextOffset: "",
	}

	bot.AnswerInlineQuery(config)
	return nil
}
```

Inline handler can be added to margelet by `InlineHandler` assignment:
```go
bot, err := margelet.NewMargelet("<your awesome bot name>", "<redis addr>", "<redis password>", 0, "your bot token", false)
m.InlineHandler = &InlineImage{}
bot.Run()
```

### Callback handlers
Callback handler is struct that implements CallbackHandler interface. CallbackHandler can be subscribed on any callback queries.

Simple example:
```go
package margelet_test

import (
	"../margelet"
	"gopkg.in/telegram-bot-api.v4"
)

type CallbackMessage struct {
}

func (handler CallbackMessage) HandleCallback(query margelet.CallbackQuery) error {
	config := tgbotapi.CallbackConfig{
		CallbackQueryID: query.Query().ID,
		Text: "Done!",
		ShowAlert: false,
	}

	query.Bot().AnswerCallbackQuery(config)
	return nil
}
```

Callback handler can be added to margelet by `CallbackHandler` assignment:
```go
bot, err := margelet.NewMargelet("<your awesome bot name>", "<redis addr>", "<redis password>", 0, "your bot token", false)
m.CallbackHandler = &CallbackMessage{}
bot.Run()
```

### Chat configs
Bots can store any config string(you can use serialized JSON) for any chat. It can be used for storing user's
configurations and other user-related information. Simple example:
```go
bot, err := margelet.NewMargelet("<your awesome bot name>", "<redis addr>", "<redis password>", 0, "your bot token", false)
...
bot.GetConfigRepository().Set(<chatID>, "<info>")
...
info := bot.GetConfigRepository().Get(<chatID>)

OR

type userInfo struct{
 FavColor string // First character has to be Capital otherwise it wont be saved
}
...
user := userInfo{FavColor: "Green"}
bot.GetConfigRepository().SetWithStruct(<chatID>, user)
...
var user userInfo
bot.GetConfigRepository().GetWithStruct(<chatID>, &user)
```
Chat config repository can be accessed from session handlers.

## Example project
Simple and clean example project can be found [here](https://github.com/zhulik/cat_bot). It provides command handling
and session configuration.

margelet

# Micha

[![Tests](https://github.com/onrik/micha/workflows/Tests/badge.svg)](https://github.com/onrik/micha/actions)
[![Coverage Status](https://coveralls.io/repos/github/onrik/micha/badge.svg?branch=master)](https://coveralls.io/github/onrik/micha?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/onrik/micha)](https://goreportcard.com/report/github.com/onrik/micha)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/onrik/micha)](https://pkg.go.dev/github.com/onrik/micha)

Client lib for [Telegram bot api](https://core.telegram.org/bots/api).

### Simple echo bot
```go
package main

import (
 "log"
	
 "github.com/onrik/micha"
)

func main() {
 bot, err := micha.NewBot("<token>")
 if err != nil {
 log.Println(err)
 return
 }

 go bot.Start()

 for update := range bot.Updates() {
 if update.Message != nil {
 bot.SendMessage(update.Message.Chat.ID, update.Message.Text, nil)
 }
 }
}

```


### Custom [Telegram Bot API](https://github.com/tdlib/telegram-bot-api)
```go
package main

import (
 "log"
	
 "github.com/onrik/micha"
)

func main() {
 bot, err := micha.NewBot(
 "<token>",
 micha.WithAPIServer("http://127.0.0.1:8081"),
 )
 if err != nil {
 log.Println(err)
 return
 }

 err = bot.Logout()
 if err != nil {
 log.Println(err)
 return
 }


 go bot.Start()

 for update := range bot.Updates() {
 if update.Message != nil {
 bot.SendMessage(update.Message.Chat.ID, update.Message.Text, nil)
 }
 }
}

```

micha

A chatbot built with an artificial neural network.

<h1 align="center">
 
 <img src="https://olivia-ai.org/img/icons/olivia-with-text.png" alt="Olivia's character" width="300">
 
</h1>

<h4 align="center">💁‍♀️ Your new best friend</h4>


 <a href="https://goreportcard.com/report/github.com/olivia-ai/olivia"><img src="https://goreportcard.com/badge/github.com/olivia-ai/olivia"></a>
 <a href="https://godoc.org/github.com/olivia-ai/olivia"><img src="https://godoc.org/github.com/olivia-ai/olivia?status.svg" alt="GoDoc"></a>
 <a href="https://app.fossa.io/projects/git%2Bgithub.com%2Folivia-ai%2Folivia?ref=badge_shield"><img src="https://app.fossa.io/api/projects/git%2Bgithub.com%2Folivia-ai%2Folivia.svg?type=shield"></a>
 <a href="https://codecov.io/gh/olivia-ai/olivia"><img src="https://codecov.io/gh/olivia-ai/olivia/branch/master/graph/badge.svg" /></a>
 
 <img src="https://github.com/olivia-ai/olivia/workflows/Code%20coverage/badge.svg">
 <img src="https://github.com/olivia-ai/olivia/workflows/Docker%20CI/badge.svg">
 <img src="https://github.com/olivia-ai/olivia/workflows/Format%20checker/badge.svg">



 <a href="https://twitter.com/oliv_ai"><img alt="Twitter Follow" src="https://img.shields.io/twitter/follow/oliv_ai"></a>
 <a href="https://discord.gg/wXDwTdy"><img src="https://img.shields.io/discord/699567909235720224?label=Discord&style=social"></a>



 <a href="https://www.youtube.com/watch?v=JRSNnW05suo"><img width="250" src="https://i.imgur.com/kEKJjJn.png"></a>



 <a href="https://olivia-ai.org">Website</a> —
 <a href="https://docs.olivia-ai.org">Documentation</a> —
 <a href="#getting-started">Getting started</a> —
 <a href="#introduction">Introduction</a> —
 <a href="#translations">Translations</a> —
 <a href="#contributors">Contributors</a> —
 <a href="#license">License</a>



 ⚠️ Please check the <a href="https://github.com/olivia-ai/olivia/issues">Call for contributors</a>


## Introduction

 <img alt="introduction" height="100" src="https://i.imgur.com/Ygm9CMc.png">


### Description
Olivia is an open-source chatbot built in Golang using Machine Learning technologies.
Its goal is to provide a free and open-source alternative to big services like DialogFlow. 

You can chat with her by speaking (STT) or writing, she replies with a text message but you can enable her voice (TTS).

You can clone the project and customize it as you want using [GitHub](https://github.com/olivia-ai/olivia)
Try it on [her website!](https://olivia-ai.org)

### Why Olivia?
- The only chatbot project in Go that could be modulable and customizable.
- Using daily a privacy-friendly chatbot is great.
- The Website is a Progressive Web Application, which means you can add it to your phone and it seems like a native app!


## Getting started
### Installation 
#### Login to Github 

To get a personal access token from Github go to `Setings > Developer settings > Personal Access Tokens`

Click on Generate new Token and name it you MUST have read and write packages ticked on.
Then click Generate new token

Replace `TOKEN` with the Token that you just made.
```bash
$ export PAT=TOKEN
```

Login to Github (Note: change USERNAME to Gthub username)
```bash
$ echo $PAT | docker login docker.pkg.github.com -u USERNAME --password-stdin
```

#### Docker


 <img alt="docker installation" height="100" src="https://i.imgur.com/5NDCfF3.png">


Pull the image from GitHub Packages
```bash
$ docker pull docker.pkg.github.com/olivia-ai/olivia/olivia:latest
```

Then start it
```bash
$ docker run -d -e PORT=8080 -p 8080:8080 docker.pkg.github.com/olivia-ai/olivia/olivia:latest
```

You can just use the websocket of Olivia now.

To stop it, get the container id:
```bash
$ docker container ls
```
```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
311b3abb963a olivia "./main" 7 minutes ago Up 7 minutes 0.0.0.0:8080->8080/tcp quizzical_mayer
```

and stop it
```bash
$ docker container stop 311b3abb963a 
```

The app will automatically check for `res/datasets/training.json` file which contains the save of the neural network.
By default when you clone the repository from Github you have a stable save.
If you want to train a new model just delete this file and rerun the app.

#### GitHub

 <img height="100" src="https://i.imgur.com/RRPoP69.png">


Clone the project via GitHub:

```bash 
$ git clone git@github.com:olivia-ai/olivia.git
```

Then download the dependencies
```bash
$ go mod download
```

And run it
```bash
$ go run main.go
```

### Frontend and Backend
To install the frontend and the backend together, please use the `docker-compose.yml` file:

```bash
$ docker-compose up
```

And all done!

## Architecture

 <img alt="architecture" height="85" src="https://i.imgur.com/95h8WIU.png">
 
 <img src="https://i.imgur.com/G9BYf4Y.png">


## Translations


 <img alt="introduction" height="130" src="https://i.imgur.com/MDKbP0R.png">


### Languages supported
- <img src="https://i.imgur.com/URqxsb0.png" width="25"> English
- <img src="https://i.imgur.com/Oo5BNk0.png" width="25"> Spanish
- <img src="https://i.imgur.com/2DWxeF9.png" width="25"> Catalan
- <img src="https://i.imgur.com/0dVqbjf.png" width="25"> French
- <img src="https://i.imgur.com/sXLQp8e.png" width="25"> German
- <img src="https://i.imgur.com/DGNcrRF.png" width="25"> Italian
- <img src="https://i.imgur.com/kB0RoFZ.png" width="25"> Brazilian portuguese - not completed

### Coverage
The coverage of the translations is given [here](https://olivia-ai.org/dashboard/language).
To add a language please read [the documentation for that](https://docs.olivia-ai.org/translations.html).

## Contributors


 <img alt="docker installation" height="85" src="https://i.imgur.com/6xr2zdp.png">

 
### Contributing
Please refer to the [contributing file](.github/CONTRIBUTING.md)
 
### Code Contributors
Thanks to the people who contribute to Olivia. 

[Contribute](.github/CONTRIBUTING.md)
<a href="https://github.com/olivia-ai/olivia/graphs/contributors"><img src="https://opencollective.com/olivia-ai/contributors.svg?width=950&button=false" /></a>

### Financial Contributors
Become a financial contributor and help Olivia growth. 

Contribute on the GitHub page of [hugolgst](https://github.com/sponsors/hugolgst) ❤️

## License


 <img src="https://i.imgur.com/9Xxtchv.png" height="90">


[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Folivia-ai%2Folivia.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Folivia-ai%2Folivia?ref=badge_large)


 <img width="60" src="https://olivia-ai.org/img/icons/olivia.png">



 Made with ❤️ by <a href="https://github.com/hugolgst">Hugo Lageneste</a>


![Olivia's wave](https://olivia-ai.org/img/background-olivia.png)

olivia

Ready to use Slack Bot for lazy developers: Custom commands, Jenkins, Jira, Bitbucket, Github...

slack-bot

Easy to use framework to create Slack bots.

# slacker [![Slack](https://img.shields.io/badge/slack-%23slacker--framework-orange)](https://gophers.slack.com/archives/C051MGM3GFL) [![Go Report Card](https://goreportcard.com/badge/github.com/slack-io/slacker)](https://goreportcard.com/report/github.com/slack-io/slacker) [![GoDoc](https://pkg.go.dev/badge/github.com/slack-io/slacker?utm_source=godoc)](https://pkg.go.dev/github.com/slack-io/slacker) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) 

Built on top of the Slack API [github.com/slack-go/slack](https://github.com/slack-go/slack), Slacker is a low-friction framework for creating Slack Bots.

## Features

- Supports Slack Apps using [Socket Mode](https://api.slack.com/apis/connections/socket)
- Easy definitions of commands and their input
- Built-in `help` command
- Bot responds to mentions and direct messages
- Simple parsing of String, Integer, Float and Boolean parameters
- Customizable, intuitive and with many examples to follow
- Replies can be new messages or in threads
- Replies can be ephemeral, scheduled, updated or deleted
- Supports Slash Commands and Interactive Messages
- Supports `slog.Logger`
- Supports `context.Context`
- Supports middlewares & grouping of commands
- Supports Cron Jobs using [https://github.com/robfig/cron](https://github.com/robfig/cron)
- Handlers run concurrently via goroutines
- Full access to the Slack API [github.com/slack-go/slack](https://github.com/slack-go/slack)

# Install

```
go get github.com/slack-io/slacker
```

# Examples

We wrote extensive [examples](./examples) to help you familiarize yourself with Slacker!

# Preparing your Slack App

To use Slacker you'll need to create a Slack App, either [manually](#manual-steps) or with an [app manifest](#app-manifest). The app manifest feature is easier, but is a beta feature from Slack and thus may break/change without much notice.

## Manual Steps

Slacker works by communicating with the Slack [Events API](https://api.slack.com/apis/connections/events-api) using the [Socket Mode](https://api.slack.com/apis/connections/socket) connection protocol.

To get started, you must have or create a [Slack App](https://api.slack.com/apps?new_app=1) and enable `Socket Mode`, which will generate your app token (`SLACK_APP_TOKEN` in the examples) that will be needed to authenticate.

Additionally, you need to subscribe to events for your bot to respond to under the `Event Subscriptions` section. Common event subscriptions for bots include `app_mention` or `message.im`.

After setting up your subscriptions, add scopes necessary to your bot in the `OAuth & Permissions`. The following scopes are recommended for getting started, though you may need to add/remove scopes depending on your bots purpose:

* `app_mentions:read`
* `channels:history`
* `chat:write`
* `groups:history`
* `im:history`
* `mpim:history`

Once you've selected your scopes install your app to the workspace and navigate back to the `OAuth & Permissions` section. Here you can retrieve yor bot's OAuth token (`SLACK_BOT_TOKEN` in the examples) from the top of the page.

With both tokens in hand, you can now proceed with the examples below.

## App Manifest

Slack [App Manifests](https://api.slack.com/reference/manifests) make it easy to share a app configurations. We provide a [simple manifest](./app_manifest/manifest.yml) that should work with all the examples provided below.

The manifest provided will send all messages in channels your bot is in to the bot (including DMs) and not just ones that actually mention them in the message.

If you wish to only have your bot respond to messages they are directly messaged in, you will need to add the `app_mentions:read` scope, and remove:

- `im:history`       # single-person dm
- `mpim:history`     # multi-person dm
- `channels:history` # public channels
- `groups:history`   # private channels

You'll also need to adjust the event subscriptions, adding `app_mention` and removing:

- `message.channels`
- `message.groups`
- `message.im`
- `message.mpim`

# Contributing / Submitting an Issue

Please review our [Contribution Guidelines](CONTRIBUTING.md) if you have found
an issue with Slacker or wish to contribute to the project.

# Troubleshooting

## My bot is not responding to events

There are a few common issues that can cause this:

* The OAuth (bot) Token may be incorrect. In this case authentication does not fail like it does if the App Token is incorrect, and the bot will simply have no scopes and be unable to respond.
* Required scopes are missing from the OAuth (bot) Token. Similar to the incorrect OAuth Token, without the necessary scopes, the bot can not respond.
* The bot does not have the correct event subscriptions setup, and is not receiving events to respond to.


slacker

Another framework for building Slack bots.

[![License](https://img.shields.io/github/license/alexandre-normand/slackscot.svg)](LICENSE)
[![GoDoc](https://godoc.org/github.com/alexandre-normand/slackscot?status.svg)](https://pkg.go.dev/github.com/alexandre-normand/slackscot?tab=doc)
[![Build](https://github.com/alexandre-normand/slackscot/workflows/Go/badge.svg)](https://github.com/alexandre-normand/slackscot/actions)
[![Go Report Card](https://goreportcard.com/badge/github.com/alexandre-normand/slackscot)](https://goreportcard.com/report/github.com/alexandre-normand/slackscot)
[![Test Coverage](https://api.codeclimate.com/v1/badges/9fe1722ab2f31036c44c/test_coverage)](https://codeclimate.com/github/alexandre-normand/slackscot/test_coverage)
[![Maintainability](https://api.codeclimate.com/v1/badges/9fe1722ab2f31036c44c/maintainability)](https://codeclimate.com/github/alexandre-normand/slackscot/maintainability)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) 
[![Latest Version](https://img.shields.io/github/tag/alexandre-normand/slackscot.svg?label=version)](https://github.com/alexandre-normand/slackscot/releases)

![logo.svg](logo.svg)

![name.svg](name.svg)



- [Overview](#overview)
- [Requirements](#requirements)
- [Features](#features)
- [Demo](#demo)
- [The Name](#the-name)
- [Concepts](#concepts)
- [Create Your Own Slackscot](#create-your-own-slackscot)
 - [Assembling the Parts and Bringing Your `slackscot` to Life](#assembling-the-parts-and-bringing-your-slackscot-to-life)
 - [Configuration Example](#configuration-example)
 - [Creating Your Own Plugins](#creating-your-own-plugins)
- [Contributing](#contributing)
 - [Open-telemetry integration](#open-telemetry-integration)
- [Some Credits](#some-credits)



# Overview 

`Slackscot` is a [slack](https://slack.com) `bot` core written in [Go](golang.org). 
Think of it as the assembly kit to making your own friendly `slack` `bot`. It comes
with a set of plugins you might enjoy and a friendly `API` for you to realize
your ambitious dreams (if you dreams include this sort of thing).

# Requirements

`Go 1.11` or above is required, mostly for [go module support](https://github.com/golang/go/wiki/Modules). 

# Features 

* Support for reactions to message updates. `slackscot` does the following:
 * Keeps track of plugin action responses and the message that triggered
 them

 * On message updates:
 1. Update responses for each triggered action

 2. Delete responses that aren't triggering anymore (or result in 
 errors during the message update)

 * On deletion of triggering messages, responses are also deleted

 * *Limitation*: Sending a `message` automatically splits it into 
 multiple slack messages when it's too long. When updating messages,
	 this spitting doesn't happen and results in an `message too long` 
	 error. Effectively, the last message in the initial response might get
	 `deleted` as a result. Handling of this could be better but that is 
	 the current limitation 😕

* Support for threaded replies to user message with option to also 
 `broadcast` on channels (disabled by `default`). 
 See [configuration example](#configuration-example) below where 
 both are enabled. 
 * Plugin actions may also explicitely reply in threads with/without
 broadcasting via [AnswerOption](answer.go)

* Concurrent processing of unrelated messages with guarantees of proper 
 ordering of message updates/deletions

* Simple extensible storage `API` for persistence in two flavors: 
 `StringStorer` and `BytesStorer`. Both are basic `key:value` maps. 
 A default file-based implementation is provided backed by
 [leveldb](https://github.com/syndtr/goleveldb)

* Implementation of `StringStorer` backed by
 [Google Cloud Datastore](https://cloud.google.com/datastore/docs/reference/libraries).
 See [datastoredb's godoc](https://godoc.org/github.com/alexandre-normand/slackscot/store/datastoredb) 
 for documentation, usage and example.

* In-memory implementation of `StringStorer` wrapping any `StringStorer` implementation
 to offer low-latency and potentially cost-saving storage implementation well-suited for
 small datasets. Plays well with cloud storage like the 
 [datastoredb]((https://godoc.org/github.com/alexandre-normand/slackscot/store/datastoredb) 
 See [inmemorydb's godoc](https://godoc.org/github.com/alexandre-normand/slackscot/store/inmemorydb) 
 for documentation, usage and example.

* Support for various configuration sources/formats via 
 [viper](https://github.com/spf13/viper)

* Support for various ways to implement functionality: 
 1. `scheduled actions`: run something every second, minute, hour, week. 
 [Oh Monday](plugins/ohmonday.go) is a plugin that demos this by 
 sending a `Monday` greeting every Monday at 10am (or the time you 
 configure it to).
 2. `commands`: respond to a _command_ directed at your `slackscot`. That 
 means something like `@slackscot help` or a direct message `help`
 sent to `slackscot`.
 3. `hear actions` (aka "listeners"): actions that evaluated for a match
 on every message that `slackscot` hears. You'll want to make sure
 your `Match` function isn't too heavy. An example is the "famous" 
 [finger quoter plugin](plugins/fingerquoter.go)

* *Experimental and subject to change*: 
 Testing functions to help validate plugin action behavior (see example in 
 [triggerer_test.go](plugins/triggerer_test.go)). Testing functions
 are found in 
 [assertplugin](https://godoc.org/github.com/alexandre-normand/slackscot/test/assertplugin) and 
 [assertanswer](https://godoc.org/github.com/alexandre-normand/slackscot/test/assertanswer)

* Built-in `help` plugin supporting a decently formatted help message
 as a command listing all plugins' actions. If you'd like some actions 
 to not be shown in the help, you can set `Hidden` to `true` in 
 its `ActionDefinition` (especially useful for `hear actions`)

* The plugin interface as a logical grouping of one or many `commands` and 
 `hear actions` and/or `scheduled actions` 

* Support for injected services providing plugins easy access to an optionally caching 
 `user info` and a `logger`. 

# Demo

* `slackscot` deleting a triggered reaction after seeing a message updated 
 that caused the first action to *not* trigger anymore and a new action 
 to now trigger (it makes sense when you see it)

![different-action-triggered-on-message-update](https://www.dropbox.com/s/r325jn1sqb7a93g/slackscot-update-message-trigger-different-action.gif?raw=1)

* `slackscot` updating a triggered reaction after seeing a triggering message 
 being updated

![same-action-answer-update-on-message-update](https://www.dropbox.com/s/ge8p38bl977ugld/slackscot-update-same-action.gif?raw=1)

* `slackscot` deleting a reaction after seeing the triggering message being
 deleted

![reaction-deletion-on-message-delete](https://www.dropbox.com/s/bwhq20m1b2obvx6/slackscot-delete-message-delete-answers.gif?raw=1)

* `slackscot` threaded replies enabled (with `broadcast => on`)

![threaded-reply-with-broadcast](https://www.dropbox.com/s/yfinvpbrla9pth8/slackscot-threaded-replies-with-broadcast.gif?raw=1)

# The Name

The first concrete bot implementation using this code was 
[youppi](https://github.com/alexandre-normand/youppi), named after the 
[great mascot](https://en.wikipedia.org/wiki/Youppi!) of the Montreal Expos 
and, when the Expos left Montreal, the Montreal Canadiens. 

`Slackscot` is a variation on the expected theme of *slackbot* with the 
implication that this is the core to *more* than just a regular `bot`. 
You know, a friendly company *mascot* that hangs out on your `slack`. 

# Concepts

* `Commands`: commands are well-defined actions with a format. `Slackscot` 
 handles all direct messages as implicit commands as well as 
 `@mention <command>` on channels. Responses to commands are directed 
 to the person who invoked it.

* `Hear actions`: those are listeners that can potentially match on any 
 message sent on channels that `slackscot` is a member of. This can 
 include actions that will randomly generate a response. Note that 
 responses are not automatically directed to the person who authored 
 the message triggering the response (although an implementation is 
 free to use the user id of the triggering message if desired). 

# Create Your Own Slackscot

`Slackscot` provides the pieces to make your mascot but you'll have to 
assemble them for him/her to come alive. The easiest to get started is
to look at a real example: [youppi](https://github.com/alexandre-normand/youppi).

![youppi running](https://media.giphy.com/media/4K1HwWtmvT07sW7enp/giphy.gif)

The [godoc](https://godoc.org/github.com/alexandre-normand/slackscot) is also a 
good reference especially if you're looking to implement something like a 
new implementation of the [storer interfaces](https://godoc.org/github.com/alexandre-normand/slackscot/store).

## Assembling the Parts and Bringing Your `slackscot` to Life

Here's an abbreviated example of how [youppi](https://github.com/alexandre-normand/youppi) 
[does it](https://github.com/alexandre-normand/youppi/blob/master/youppi.go):

```go
package main

import (
	"github.com/alexandre-normand/slackscot"
	"github.com/alexandre-normand/slackscot/config"
	"github.com/alexandre-normand/slackscot/plugins"
	"github.com/alexandre-normand/slackscot/store"
	"github.com/spf13/viper"
	"gopkg.in/alecthomas/kingpin.v2"
	"log"
	"os"
	"io"
)

const (
	name = "youppi"
)

func main() {
	kingpin.Version(VERSION)
	kingpin.Parse()

	// TODO: initialize storer implementations required by plugins and do any other initialization 
	// required
	...

	// This is the where we create youppi with all of its plugins
	youppi, err := slackscot.NewBot(name, v, options...).
		WithPlugin(plugins.NewKarma(karmaStorer)).
		WithPlugin(plugins.NewTriggerer(triggererStorer)).
		WithConfigurablePluginErr(plugins.FingerQuoterPluginName, func(conf *config.PluginConfig) (p *slackscot.Plugin, err error) { return plugins.NewFingerQuoter(conf) }).
		WithConfigurablePluginCloserErr(plugins.EmojiBannerPluginName, func(conf *config.PluginConfig) (c io.Closer, p *slackscot.Plugin, err error) {
			return plugins.NewEmojiBannerMaker(conf)
		}).
		WithConfigurablePluginErr(plugins.OhMondayPluginName, func(conf *config.PluginConfig) (p *slackscot.Plugin, err error) { return plugins.NewOhMonday(conf) }).
		WithPlugin(plugins.NewVersionner(name, version)).
		Build()
	defer youppi.Close()

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

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

## Configuration Example

You'll also need to define your configuration for the `core`, used 
built-in plugins and any configuration required by your own custom plugins 
(not shown here). `Slackscot` uses 
[viper](https://github.com/spf13/viper) for loading configuration
which means that you are free to use a different file format 
(`yaml`, `toml`, `env variables`, etc.) as desired. 

```json
{
 "token": "your-slack-bot-token",
 "debug": false,
 "responseCacheSize": 5000,
 "userInfoCacheSize": 0,
 "maxAgeHandledMessages": 86400,
 "timeLocation": "America/Los_Angeles",
 "storagePath": "/your-path-to-bot-home",
 "replyBehavior": {
 "threadedReplies": true,
 "broadcastThreadedReplies": true
 },
 "plugins": {
 "ohMonday": {
 	 "channelIDs": ["slackChannelId"]
 },
 "fingerQuoter": {
 "frequency": "100",
 "channelIDs": []
 },
 "emojiBanner": {
 "figletFontUrl": "http://www.figlet.org/fonts/banner.flf"
 }
 }
}
```

## Creating Your Own Plugins

It might be best to look at examples in this repo to guide you through it:

* The simplest plugin with a single `command` is the [versioner](plugins/versioner.go)
* One example of `scheduled actions` is [oh monday](plugins/ohmonday.go)
* One example of a mix of `hear actions` / `commands` that also uses the
 `store` api for persistence is the [karma](plugins/karma.go)

# Contributing

1. Fork it (preferrably, outside the `GOPATH` as per the new 
 [go modules guidelines](https://github.com/golang/go/wiki/Modules#how-to-install-and-activate-module-support))
2. Make your changes, commit them (don't forget to `go build ./...` and 
 `go test ./...`) and push your branch to your fork
3. Open a PR and fill in the template (you don't have to but I'd appreciate context)
4. Check the `code climate` and `travis` PR builds. You might have to fix things and
 there's no shame if you do. I probably won't merge something that doesn't pass
 `CI` build but I'm willing to help to get it to pass 🖖. 

## Open-telemetry integration

`Slackscot` now supports integration with [opentelemetry](https://opentelemetry.io/). To aid with the addition
of new metrics, you can find a [gowrap](https://github.com/hexdigest/gowrap) template [here](./opentelemetry.template). 
To add a metrics to a new interface, you can do something like

```bash
gowrap gen -p . -i <interfaceName> -t opentelemetry.template -o <interfaceName>metrics.go
```

When updating the [template](./opentelemetry.template), you should consider running `go generate` in order to refresh
the already generated files with the template changes. 

# Some Credits
`slackscot` uses [Norberto Lopes](https://github.com/nlopes)'s 
[Slack API Integration](https://github.com/nlopes/slack) found at 
[https://github.com/nlopes/slack](https://github.com/nlopes/slack). The core
functionality of the bot is previously used 
[James Bowman](https://github.com/james-bowman)'s 
[Slack RTM API integration](https://github.com/james-bowman/slack) and 
was heavily inspired by [talbot](https://github.com/james-bowman/talbot), 
also written by [James Bowman](https://github.com/james-bowman).

slackscot

Telegram bot server with API similar to net/http.

# tbot - Telegram Bot Server [![GoDoc](https://godoc.org/github.com/yanzay/tbot?status.svg)](https://godoc.org/github.com/yanzay/tbot) [![Go Report Card](https://goreportcard.com/badge/github.com/yanzay/tbot)](https://goreportcard.com/report/github.com/yanzay/tbot) [![GitHub Actions](https://github.com/yanzay/tbot/workflows/Test/badge.svg)](https://github.com/yanzay/tbot/actions)

![logo](https://raw.githubusercontent.com/yanzay/tbot/master/logo.png)

## Features

- Full Telegram Bot API **4.7** support
- **Zero** dependency
- Type-safe API client with functional options
- Capture messages by regexp
- Middlewares support
- Can be used with go modules
- Support for external logger
- MIT licensed

## Installation

With go modules:

```bash
go get github.com/yanzay/tbot/v2
```

Without go modules:

```bash
go get github.com/yanzay/tbot
```

## Support

Join [telegram group](https://t.me/tbotgo) to get support or just to say thank you.

## Documentation

Documentation: [https://yanzay.github.io/tbot-doc/](https://yanzay.github.io/tbot-doc/).

Full specification: [godoc](https://godoc.org/github.com/yanzay/tbot).

## Usage

Simple usage example:

[embedmd]:# (examples/basic/main.go)
```go
package main

import (
	"log"
	"os"
	"time"

	"github.com/yanzay/tbot/v2"
)

func main() {
	bot := tbot.New(os.Getenv("TELEGRAM_TOKEN"))
	c := bot.Client()
	bot.HandleMessage(".*yo.*", func(m *tbot.Message) {
		c.SendChatAction(m.Chat.ID, tbot.ActionTyping)
		time.Sleep(1 * time.Second)
		c.SendMessage(m.Chat.ID, "hello!")
	})
	err := bot.Start()
	if err != nil {
		log.Fatal(err)
	}
}
```

## Examples

Please take a look inside [examples](https://github.com/yanzay/tbot/tree/master/examples) folder.


tbot

# Telebot
>"I never knew creating Telegram bots could be so _sexy_!"

[![GoDoc](https://godoc.org/gopkg.in/telebot.v3?status.svg)](https://godoc.org/gopkg.in/telebot.v3)
[![GitHub Actions](https://github.com/tucnak/telebot/actions/workflows/go.yml/badge.svg)](https://github.com/tucnak/telebot/actions)
[![codecov.io](https://codecov.io/gh/tucnak/telebot/coverage.svg?branch=v3)](https://codecov.io/gh/tucnak/telebot)
[![Discuss on Telegram](https://img.shields.io/badge/telegram-discuss-0088cc.svg)](https://t.me/go_telebot)

```bash
go get -u gopkg.in/telebot.v3
```

* [Overview](#overview)
* [Getting Started](#getting-started)
	- [Context](#context)
	- [Middleware](#middleware)
	- [Poller](#poller)
	- [Commands](#commands)
	- [Files](#files)
	- [Sendable](#sendable)
	- [Editable](#editable)
	- [Keyboards](#keyboards)
	- [Inline mode](#inline-mode)
* [Contributing](#contributing)
* [Donate](#donate)
* [License](#license)

# Overview
Telebot is a bot framework for [Telegram Bot API](https://core.telegram.org/bots/api).
This package provides the best of its kind API for command routing, inline query requests and keyboards, as well
as callbacks. Actually, I went a couple steps further, so instead of making a 1:1 API wrapper I chose to focus on
the beauty of API and performance. Some strong sides of Telebot are:

* Real concise API
* Command routing
* Middleware
* Transparent File API
* Effortless bot callbacks

All the methods of Telebot API are _extremely_ easy to memorize and get used to. Also, consider Telebot a
highload-ready solution. I'll test and benchmark the most popular actions and if necessary, optimize
against them without sacrificing API quality.

# Getting Started
Let's take a look at the minimal Telebot setup:

```go
package main

import (
	"log"
	"os"
	"time"

	tele "gopkg.in/telebot.v3"
)

func main() {
	pref := tele.Settings{
		Token: os.Getenv("TOKEN"),
		Poller: &tele.LongPoller{Timeout: 10 * time.Second},
	}

	b, err := tele.NewBot(pref)
	if err != nil {
		log.Fatal(err)
		return
	}

	b.Handle("/hello", func(c tele.Context) error {
		return c.Send("Hello!")
	})

	b.Start()
}

```

Simple, innit? Telebot's routing system takes care of delivering updates
to their endpoints, so in order to get to handle any meaningful event,
all you got to do is just plug your function into one of the Telebot-provided
endpoints. You can find the full list
[here](https://godoc.org/gopkg.in/telebot.v3#pkg-constants).

There are dozens of supported endpoints (see package consts). Let me know
if you'd like to see some endpoint or endpoint ideas implemented. This system
is completely extensible, so I can introduce them without breaking
backwards compatibility.

## Context
Context is a special type that wraps a huge update structure and represents
the context of the current event. It provides several helpers, which allow
getting, for example, the chat that this update had been sent in, no matter
what kind of update this is.

```go
b.Handle(tele.OnText, func(c tele.Context) error {
	// All the text messages that weren't
	// captured by existing handlers.

	var (
		user = c.Sender()
		text = c.Text()
	)

	// Use full-fledged bot's functions
	// only if you need a result:
	msg, err := b.Send(user, text)
	if err != nil {
		return err
	}

	// Instead, prefer a context short-hand:
	return c.Send(text)
})

b.Handle(tele.OnChannelPost, func(c tele.Context) error {
	// Channel posts only.
	msg := c.Message()
})

b.Handle(tele.OnPhoto, func(c tele.Context) error {
	// Photos only.
	photo := c.Message().Photo
})

b.Handle(tele.OnQuery, func(c tele.Context) error {
	// Incoming inline queries.
	return c.Answer(...)
})
```

## Middleware
Telebot has a simple and recognizable way to set up middleware — chained functions with access to `Context`, called before the handler execution.

Import a `middleware` package to get some basic out-of-box middleware
implementations:
```go
import "gopkg.in/telebot.v3/middleware"
```

```go
// Global-scoped middleware:
b.Use(middleware.Logger())
b.Use(middleware.AutoRespond())

// Group-scoped middleware:
adminOnly := b.Group()
adminOnly.Use(middleware.Whitelist(adminIDs...))
adminOnly.Handle("/ban", onBan)
adminOnly.Handle("/kick", onKick)

// Handler-scoped middleware:
b.Handle(tele.OnText, onText, middleware.IgnoreVia())
```

Custom middleware example:
```go
// AutoResponder automatically responds to every callback update.
func AutoResponder(next tele.HandlerFunc) tele.HandlerFunc {
	return func(c tele.Context) error {
		if c.Callback() != nil {
			defer c.Respond()
		}
		return next(c) // continue execution chain
	}
}
```

## Poller
Telebot doesn't really care how you provide it with incoming updates, as long
as you set it up with a Poller, or call ProcessUpdate for each update:

```go
// Poller is a provider of Updates.
//
// All pollers must implement Poll(), which accepts bot
// pointer and subscription channel and start polling
// synchronously straight away.
type Poller interface {
	// Poll is supposed to take the bot object
	// subscription channel and start polling
	// for Updates immediately.
	//
	// Poller must listen for stop constantly and close
	// it as soon as it's done polling.
	Poll(b *Bot, updates chan Update, stop chan struct{})
}
```

## Commands
When handling commands, Telebot supports both direct (`/command`) and group-like
syntax (`/command@botname`) and will never deliver messages addressed to some
other bot, even if [privacy mode](https://core.telegram.org/bots#privacy-mode) is off.

For simplified deep-linking, Telebot also extracts payload:
```go
// Command: /start <PAYLOAD>
b.Handle("/start", func(c tele.Context) error {
	fmt.Println(c.Message().Payload) // <PAYLOAD>
})
```

For multiple arguments use:
```go
// Command: /tags <tag1> <tag2> <...>
b.Handle("/tags", func(c tele.Context) error {
	tags := c.Args() // list of arguments splitted by a space
	for _, tag := range tags {
		// iterate through passed arguments
	}
})
```

## Files
>Telegram allows files up to 50 MB in size.

Telebot allows to both upload (from disk or by URL) and download (from Telegram)
files in bot's scope. Also, sending any kind of media with a File created
from disk will upload the file to Telegram automatically:
```go
a := &tele.Audio{File: tele.FromDisk("file.ogg")}

fmt.Println(a.OnDisk()) // true
fmt.Println(a.InCloud()) // false

// Will upload the file from disk and send it to the recipient
b.Send(recipient, a)

// Next time you'll be sending this very *Audio, Telebot won't
// re-upload the same file but rather utilize its Telegram FileID
b.Send(otherRecipient, a)

fmt.Println(a.OnDisk()) // true
fmt.Println(a.InCloud()) // true
fmt.Println(a.FileID) // <Telegram file ID>
```

You might want to save certain `File`s in order to avoid re-uploading. Feel free
to marshal them into whatever format, `File` only contain public fields, so no
data will ever be lost.

## Sendable
Send is undoubtedly the most important method in Telebot. `Send()` accepts a
`Recipient` (could be user, group or a channel) and a `Sendable`. Other types other than
the Telebot-provided media types (`Photo`, `Audio`, `Video`, etc.) are `Sendable`.
If you create composite types of your own, and they satisfy the `Sendable` interface,
Telebot will be able to send them out.

```go
// Sendable is any object that can send itself.
//
// This is pretty cool, since it lets bots implement
// custom Sendables for complex kinds of media or
// chat objects spanning across multiple messages.
type Sendable interface {
	Send(*Bot, Recipient, *SendOptions) (*Message, error)
}
```

The only type at the time that doesn't fit `Send()` is `Album` and there is a reason
for that. Albums were added not so long ago, so they are slightly quirky for backwards
compatibilities sake. In fact, an `Album` can be sent, but never received. Instead,
Telegram returns a `[]Message`, one for each media object in the album:
```go
p := &tele.Photo{File: tele.FromDisk("chicken.jpg")}
v := &tele.Video{File: tele.FromURL("http://video.mp4")}

msgs, err := b.SendAlbum(user, tele.Album{p, v})
```

### Send options
Send options are objects and flags you can pass to `Send()`, `Edit()` and friends
as optional arguments (following the recipient and the text/media). The most
important one is called `SendOptions`, it lets you control _all_ the properties of
the message supported by Telegram. The only drawback is that it's rather
inconvenient to use at times, so `Send()` supports multiple shorthands:
```go
// regular send options
b.Send(user, "text", &tele.SendOptions{
	// ...
})

// ReplyMarkup is a part of SendOptions,
// but often it's the only option you need
b.Send(user, "text", &tele.ReplyMarkup{
	// ...
})

// flags: no notification && no web link preview
b.Send(user, "text", tele.Silent, tele.NoPreview)
```

Full list of supported option-flags you can find
[here](https://pkg.go.dev/gopkg.in/telebot.v3#Option).

## Editable
If you want to edit some existing message, you don't really need to store the
original `*Message` object. In fact, upon edit, Telegram only requires `chat_id`
and `message_id`. So you don't really need the Message as a whole. Also, you
might want to store references to certain messages in the database, so I thought
it made sense for *any* Go struct to be editable as a Telegram message, to implement
`Editable`:
```go
// Editable is an interface for all objects that
// provide "message signature", a pair of 32-bit
// message ID and 64-bit chat ID, both required
// for edit operations.
//
// Use case: DB model struct for messages to-be
// edited with, say two columns: msg_id,chat_id
// could easily implement MessageSig() making
// instances of stored messages editable.
type Editable interface {
	// MessageSig is a "message signature".
	//
	// For inline messages, return chatID = 0.
	MessageSig() (messageID int, chatID int64)
}
```

For example, `Message` type is Editable. Here is the implementation of `StoredMessage`
type, provided by Telebot:
```go
// StoredMessage is an example struct suitable for being
// stored in the database as-is or being embedded into
// a larger struct, which is often the case (you might
// want to store some metadata alongside, or might not.)
type StoredMessage struct {
	MessageID int `sql:"message_id" json:"message_id"`
	ChatID int64 `sql:"chat_id" json:"chat_id"`
}

func (x StoredMessage) MessageSig() (int, int64) {
	return x.MessageID, x.ChatID
}
```

Why bother at all? Well, it allows you to do things like this:
```go
// just two integer columns in the database
var msgs []tele.StoredMessage
db.Find(&msgs) // gorm syntax

for _, msg := range msgs {
	bot.Edit(&msg, "Updated text")
	// or
	bot.Delete(&msg)
}
```

I find it incredibly neat. Worth noting, at this point of time there exists
another method in the Edit family, `EditCaption()` which is of a pretty
rare use, so I didn't bother including it to `Edit()`, just like I did with
`SendAlbum()` as it would inevitably lead to unnecessary complications.
```go
var m *Message

// change caption of a photo, audio, etc.
bot.EditCaption(m, "new caption")
```

## Keyboards
Telebot supports both kinds of keyboards Telegram provides: reply and inline
keyboards. Any button can also act as endpoints for `Handle()`.

```go
var (
	// Universal markup builders.
	menu = &tele.ReplyMarkup{ResizeKeyboard: true}
	selector = &tele.ReplyMarkup{}

	// Reply buttons.
	btnHelp = menu.Text("ℹ Help")
	btnSettings = menu.Text("⚙ Settings")

	// Inline buttons.
	//
	// Pressing it will cause the client to
	// send the bot a callback.
	//
	// Make sure Unique stays unique as per button kind
	// since it's required for callback routing to work.
	//
	btnPrev = selector.Data("⬅", "prev", ...)
	btnNext = selector.Data("➡", "next", ...)
)

menu.Reply(
	menu.Row(btnHelp),
	menu.Row(btnSettings),
)
selector.Inline(
	selector.Row(btnPrev, btnNext),
)

b.Handle("/start", func(c tele.Context) error {
	return c.Send("Hello!", menu)
})

// On reply button pressed (message)
b.Handle(&btnHelp, func(c tele.Context) error {
	return c.Edit("Here is some help: ...")
})

// On inline button pressed (callback)
b.Handle(&btnPrev, func(c tele.Context) error {
	return c.Respond()
})
```

You can use markup constructor for every type of possible button:
```go
r := b.NewMarkup()

// Reply buttons:
r.Text("Hello!")
r.Contact("Send phone number")
r.Location("Send location")
r.Poll(tele.PollQuiz)

// Inline buttons:
r.Data("Show help", "help") // data is optional
r.Data("Delete item", "delete", item.ID)
r.URL("Visit", "https://google.com")
r.Query("Search", query)
r.QueryChat("Share", query)
r.Login("Login", &tele.Login{...})
```

## Inline mode
So if you want to handle incoming inline queries you better plug the `tele.OnQuery`
endpoint and then use the `Answer()` method to send a list of inline queries
back. I think at the time of writing, Telebot supports all of the provided result
types (but not the cached ones). This is what it looks like:

```go
b.Handle(tele.OnQuery, func(c tele.Context) error {
	urls := []string{
		"http://photo.jpg",
		"http://photo2.jpg",
	}

	results := make(tele.Results, len(urls)) // []tele.Result
	for i, url := range urls {
		result := &tele.PhotoResult{
			URL: url,
			ThumbURL: url, // required for photos
		}

		results[i] = result
		// needed to set a unique string ID for each result
		results[i].SetResultID(strconv.Itoa(i))
	}

	return c.Answer(&tele.QueryResponse{
		Results: results,
		CacheTime: 60, // a minute
	})
})
```

There's not much to talk about really. It also supports some form of authentication
through deep-linking. For that, use fields `SwitchPMText` and `SwitchPMParameter`
of `QueryResponse`.

# Contributing

1. Fork it
2. Clone v3: `git clone -b v3 https://github.com/tucnak/telebot`
3. Create your feature branch: `git checkout -b v3-feature`
4. Make changes and add them: `git add .`
5. Commit: `git commit -m "add some feature"`
6. Push: `git push origin v3-feature`
7. Pull request

# Donate

I do coding for fun, but I also try to search for interesting solutions and
optimize them as much as possible.
If you feel like it's a good piece of software, I wouldn't mind a tip!

Litecoin: `ltc1qskt5ltrtyg7esfjm0ftx6jnacwffhpzpqmerus`

Ethereum: `0xB78A2Ac1D83a0aD0b993046F9fDEfC5e619efCAB`

# License

Telebot is distributed under MIT.

telebot

Telegram Bot API library for Golang with full one-to-one API implementation.

telego

# Golang bindings for the Telegram Bot API

[![Go Reference](https://pkg.go.dev/badge/github.com/go-telegram-bot-api/telegram-bot-api/v5.svg)](https://pkg.go.dev/github.com/go-telegram-bot-api/telegram-bot-api/v5)
[![Test](https://github.com/go-telegram-bot-api/telegram-bot-api/actions/workflows/test.yml/badge.svg)](https://github.com/go-telegram-bot-api/telegram-bot-api/actions/workflows/test.yml)

All methods are fairly self-explanatory, and reading the [godoc](https://pkg.go.dev/github.com/go-telegram-bot-api/telegram-bot-api/v5) page should
explain everything. If something isn't clear, open an issue or submit
a pull request.

There are more tutorials and high-level information on the website, [go-telegram-bot-api.dev](https://go-telegram-bot-api.dev).

The scope of this project is just to provide a wrapper around the API
without any additional features. There are other projects for creating
something with plugins and command handlers without having to design
all that yourself.

Join [the development group](https://telegram.me/go_telegram_bot_api) if
you want to ask questions or discuss development.

## Example

First, ensure the library is installed and up to date by running
`go get -u github.com/go-telegram-bot-api/telegram-bot-api/v5`.

This is a very simple bot that just displays any gotten updates,
then replies it to that chat.

```go
package main

import (
	"log"

	tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
)

func main() {
	bot, err := tgbotapi.NewBotAPI("MyAwesomeBotToken")
	if err != nil {
		log.Panic(err)
	}

	bot.Debug = true

	log.Printf("Authorized on account %s", bot.Self.UserName)

	u := tgbotapi.NewUpdate(0)
	u.Timeout = 60

	updates := bot.GetUpdatesChan(u)

	for update := range updates {
		if update.Message != nil { // If we got a message
			log.Printf("[%s] %s", update.Message.From.UserName, update.Message.Text)

			msg := tgbotapi.NewMessage(update.Message.Chat.ID, update.Message.Text)
			msg.ReplyToMessageID = update.Message.MessageID

			bot.Send(msg)
		}
	}
}
```

If you need to use webhooks (if you wish to run on Google App Engine),
you may use a slightly different method.

```go
package main

import (
	"log"
	"net/http"

	"github.com/go-telegram-bot-api/telegram-bot-api/v5"
)

func main() {
	bot, err := tgbotapi.NewBotAPI("MyAwesomeBotToken")
	if err != nil {
		log.Fatal(err)
	}

	bot.Debug = true

	log.Printf("Authorized on account %s", bot.Self.UserName)

	wh, _ := tgbotapi.NewWebhookWithCert("https://www.example.com:8443/"+bot.Token, "cert.pem")

	_, err = bot.Request(wh)
	if err != nil {
		log.Fatal(err)
	}

	info, err := bot.GetWebhookInfo()
	if err != nil {
		log.Fatal(err)
	}

	if info.LastErrorDate != 0 {
		log.Printf("Telegram callback failed: %s", info.LastErrorMessage)
	}

	updates := bot.ListenForWebhook("/" + bot.Token)
	go http.ListenAndServeTLS("0.0.0.0:8443", "cert.pem", "key.pem", nil)

	for update := range updates {
		log.Printf("%+v\n", update)
	}
}
```

If you need, you may generate a self-signed certificate, as this requires
HTTPS / TLS. The above example tells Telegram that this is your
certificate and that it should be trusted, even though it is not
properly signed.

    openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 3560 -subj "//O=Org\CN=Test" -nodes

Now that [Let's Encrypt](https://letsencrypt.org) is available,
you may wish to generate your free TLS certificate there.


telegram-bot-api

# Teleterm
Telegram Bot Exec Terminal Command 

[![codecov](https://codecov.io/gh/alfiankan/teleterm/branch/main/graph/badge.svg?token=ZQ4Z1ZU4EM)](https://codecov.io/gh/alfiankan/teleterm)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) 
[![Go Reference](https://pkg.go.dev/badge/github.com/alfiankan/teleterm/v2.svg)](https://pkg.go.dev/github.com/alfiankan/teleterm/v2)
[![Go report card](https://goreportcard.com/badge/github.com/alfiankan/teleterm)](https://goreportcard.com/badge/github.com/alfiankan/teleterm)

![teleterm2-demo](https://user-images.githubusercontent.com/40946917/178386328-3795dc02-b30a-437a-a46b-20db141601d5.gif)



## Use Case
- Running command on IoT Device through telegram bot
- Transfering Files through telegram bot

## How To Install

1. Prebuilt Binary
	you can download prebuild binary depends on your os and arch, available prebuilts here:

	https://github.com/alfiankan/teleterm/releases/tag/v2.1.0
	
	Once the binary is downloaded, you can move the binary to /usr/local/bin

2. Build From Source
	If your arch os is not listed in the prebuilt binary you can build from source.
	
	Required :
	- Go ^1.18
	- gcc

	How to build :
	- clone `git clone https://github.com/alfiankan/teleterm`
	- build `go build -o teleterm-bin ./cmd...`

## How To Run :
Required :
- Telegram bot tokens, to get tokens please refer to [Telegram Docs](https://core.telegram.org/bots#6-botfather)

1. Setting Up Config

	To setup fresh teleterm run 
	
	```bash
	teleterm fresh
	```
	
	![Teleterm Fresh Configure](docs/teleterm-running.png)

	teleterm will create folder on your home folder with name `.teleterm` contains :
	- config.yaml
		config yaml hold teleterm config :

		| Key |Value |
		| ------------- |-------------|
		| telegram_token | telegram token from bot father |
		| shell_executor | `/bin/bash` or `/bin/sh` .etc default is `/bin/bash`|

		example config.yaml
		```yaml
			teleterm:
 				telegram_token: "my_tele_token"
 				shell_executor: "/bin/bash"
		```

2. Run teleterm

	To run teleterm simply run `teleterm` and log info will displayed.

	![Teleterm Running](docs/teleterm-running-on.png)




## Available Bot Command
| Command |Desc |Example |
| ------------- |:-------------|:-------------|
|/refresh |Refresh the bot system | /refresh |
| /run `<command>`| executing command | /run ping -c 5 8.8.8.8 |
| /getfile `<filepath>`| transfer donwload file from bot server | /getfile /home/raspi/myfile.txt |
|/addbutton `<button_name>!!<command>`| add button shortcut | /addbutton ping!!ping -c 5 8.8.8.8 |
|/deletebutton `<button_name>`|delete button shortcut | /deletebutton ping |


## Run Command
To execute commands from telegram just send a message using the following format :
```bash
/run <command>
```
for example :
```bash
/run ping -c 5 8.8.8.8
```
output replied by telegram bot :

![Run command](docs/teleterm-run-cmd.png)

## Add Button Shortcut
To execute commands from the telegram button, you need to add a button, just send a message using the following format :
```bash
/addbutton <button_name>!!<command>
```
for example :
```bash
/addbutton ping!!ping -c 5 8.8.8.8
```
output replied by telegram bot :

![Add Button](docs/teleterm-addbutton.png)

a new button will appear :

![Show Buttons](docs/teleterm-buttons.png)

## Shortcut Button
To run a command using a shortcut just click the telegram button the bot will find the exec command from the database.

## Delete Button Shortcut
To remove a shortcut simply send a message using the following format:
```bash
/deletebutton <button_name>
```
for example :
```bash
/deletebutton ping
```
output replied by telegram bot :

![Delete Button](docs/teleterm-deletebutton.png)

then updated buttons will appear.

## Uploading File
To upload a file just send the document on telegram :

![Upload File](docs/teleterm-upload.png)

By default it will upload in cwd path if you don't add target path on file mention.

output replied by telegram bot :

![Upload Success](docs/teleterm-upload-success.png)

## Download file
To download the file simply send a message using the following format :
```bash
/getfile <filepath>
```

Filepath is the filepath where teleterm runs

for example :
```bash
/getfile /home/raspi/hello.txt
```
output replied by telegram bot :

![Downloaded File](docs/teleterm-downloadfile.png)

teleterm

Service oriented IRC bot using Redis and JSON for messaging.

[![Build Status](https://travis-ci.org/kyleterry/tenyks.svg?branch=master)](https://travis-ci.org/kyleterry/tenyks)
```Textile
 _ _ 
 | | | | 
 | |_ ___ _ __ _ _| | _____ 
 | __/ _ \ '_ \| | | | |/ / __| 
 | || __/ | | | |_| | <\__ \ The IRC bot for hackers.
 \__\___|_| |_|\__, |_|\_\___/ 
 __/ | 
 |___/ 
```

Tenyks is a computer program designed to relay messages between connections to
IRC networks and custom built services written in any number of languages.
More detailed, Tenyks is a service oriented IRC bot rewritten in Go.
Service/core communication is handled by ZeroMQ 4 PubSub via json payloads.

The core acts like a relay between IRC channels and remote services. When a
message comes in from IRC, that message is turned into a json data structure,
then sent over the pipe on a Pub/Sub channel that services can subscribe to.
Services then parse or pattern match the message, and possibly respond back via
the same method.

This design, while not anything new, is very flexible because one can write
their service in any number of languages. The current service implementation
used for proof of concept is written in Python. You can find that
[here](https://github.com/kyleterry/tenyks-service). It's also beneficial because you can take down
or bring up services without the need to restart the bot or implement a
complicated hot pluggable core. Services that crash also don't run the risk of
taking everything else down with it.

## Installation and whatnot

### Building

Current supported Go version is 1.7. All packages are vendored with Godep and
stored in the repository. I update these occasionally. Make sure you have a
functioning Go 1.7 environment.

1. Install ZeroMQ4 (reference your OSs package install documentation) and make
 sure libzmq exists on the system.
1. `go get github.com/kyleterry/tenyks`
1. `cd ${GOPATH}/src/github.com/kyleterry/tenyks`
1. `make` - this will run tests and build
1. `sudo make install` - otherwise you can find it in `./bin/tenyks`
1. `cp config.json.example config.json`
1. Edit `config.json` to your liking.

### Uninstall

Why would you ever want to do that?

```bash
cd ${GOPATH}/src/github.com/kyleterry/tenyks
sudo make uninstall
```

### Docker

There is a Docker image on Docker hub called `kyleterry/tenyks`. No
configuration is available in the image so you need to use it as a base image.
You can pass your own configuration in like so:

```docker
FROM kyleterry/tenyks:latest
COPY my-config.json /etc/tenyks/config.json
```

Then you can build your image: `docker build -t myuser/tenyks .` and run it
with: `docker run -d -P --name tenyks myuser/tenyks`.

### Binary Release

You can find binary builds on [bintray](https://dl.bintray.com/kyleterry/tenyks/).

I cross compile for Linux {arm,386,amd64} and Darwin {386,amd64}.

### Configuration

Configuration is just json. The included example contains everything you need to
get started. You just need to swap out the server information.

```bash
cp config.json.example ${HOME}/tenyks-config.json
```

### Running

`tenyks ${HOME}/tenyks-config.json`

If a config file is excluded when running, Tenyks will look for configuration
in `/etc/tenyks/config.json` first, then
`${HOME}/.config/tenyks/config.json` then it will give up. These are defined
in tenyks/tenyks.go and added with ConfigSearch.AddPath(). If you feel more
paths should be searched, please feel free to add it and submit a pull request.

### Vagrant

If you want to play _right fucking now_, you can just use vagrant: `vagrant up`
and then `vagrant ssh`. Tenyks should be built and available in your `$PATH`.
There is also an IRC server running you can connect to server on `192.168.33.66` with your IRC client.

Just run `tenyks & && disown` from the vagrant box and start playing.

## Testing

I'm a horrible person. ~~There aren't tests yet. I'll get right on this...~~.
There are only a few tests.

## Builtins

Tenyks comes with very few commands that the core responds to directly. You can
get a list of services and get help for those services.

`tenyks: !services` will list services that have registered with the bot
through the service [registration API.](#service-registration). 
`tenyks: !help` will show a quick help menu of all the commands available to
tenyks. 
`tenyks: !help servicename` will ask the service to sent their help message to
the user.

## Services

### Libraries
* [tenyksservice](https://github.com/kyleterry/tenyks-service) (Python)
* [quasar](https://github.com/kyleterry/quasar) (Go)

### To Services

Example JSON payload sent to services:

```json
{
 "target":"#tenyks",
 "command":"PRIVMSG",
 "mask":"unaffiliated/vhost-",
 "direct":true,
 "nick":"vhost-",
 "host":"unaffiliated/vhost-",
 "full_message":":vhost-!~vhost@unaffiliated/vhost- PRIVMSG #tenyks :tenyks-demo: weather 97217",
 "user":"~vhost",
 "from_channel":true,
 "connection":"freenode",
 "payload":"weather 97217",
 "meta":{
 "name":"Tenyks",
 "version":"1.0"
 }
}
```

### To Tenyks for IRC

Example JSON response from a service to Tenyks destined for IRC

```json
{
 "target":"#tenyks",
 "command":"PRIVMSG",
 "from_channel":true,
 "connection":"freenode",
 "payload":"Portland, OR is 63.4 F (17.4 C) and Overcast; windchill is NA; winds are Calm",
 "meta":{
 "name":"TenyksWunderground",
 "version":"1.1"
 }
}
```

### Service Registration

Registering your service with the bot will let people ask Tenyks which services
are online and available for use. Registering is not requires; anything
listening on the pubsub channel can respond without registration.

Each service should have a unique UUID set in it's REGISTER message. An example
of a valid register message is below:

```json
{
 "command":"REGISTER",
 "meta":{
 "name":"TenyksWunderground",
 "version":"1.1",
 "UUID": "uuid4 here",
 "description": "Fetched weather for someone who asks"
 }
}
```

### Service going offline

If the service is shutting down, you should send a BYE message so Tenyks doesn't
have to timeout the service after PINGs go unresponsive:

```json
{
 "command":"BYE",
 "meta":{
 "name":"TenyksWunderground",
 "version":"1.1",
 "UUID": "uuid4 here",
 "description": "Fetched weather for someone who asks"
 }
}
```

### Commands for registration that go to services

Services can register with Tenyks. This will allow you to list the services
currently online from the bot. This is not persistent. If you shut down the bot,
then all the service UUIDs that were registered go away.

The commands sent to services are:

```json
{
 "command": "HELLO",
 "payload": "!tenyks"
}
``` 
`HELLO` will tell services that Tenyks has come online and they can register if
they want to.

```json
{
 "command": "PING",
 "payload": "!tenyks"
}
``` 
`PING` will expect services to respond with `PONG`.

List and Help commands are coming soon.

### Lets make a service!

This service is in python and uses the
[tenyks-service](https://github.com/kyleterry/tenyks-service) package. You can
install that with pip: `pip install tenyksservice`.

```python
from tenyksservice import TenyksService, run_service, FilterChain


class Hello(TenyksService):
 irc_message_filters = {
 'hello': FilterChain([r"^(?i)(hi|hello|sup|hey), I'm (?P<name>(.*))$"],
 direct_only=False),
 # This is will respond to /msg tenyks this is private
 'private': FilterChain([r"^this is private$"],
 private_only=True)
 }

 def handle_hello(self, data, match):
 name = match.groupdict()['name']
 self.logger.debug('Saying hello to {name}'.format(name=name))
 self.send('How are you {name}?!'.format(name=name), data)

 def handle_private(self, data, match):
 self.send('Hello, private message sender', data)


def main():
 run_service(Hello)


if __name__ == '__main__':
 main()
```

Okay, we need to generate some settings for our new service.

```bash
tenyks-service-mkconfig hello >> hello_settings.py
```

Now lets run it: `python main.py hello_settings.py`

If you now join the channel that tenyks is in and say "tenyks: hello, I'm Alice"
then tenyks should respond with "How are you Alice?!".

### More Examples

There is a repository with some services on my Github called
[tenyks-contrib](https://github.com/kyleterry/tenyks-contrib). These are all
using the older tenyksclient class and will probably work out of the box with
Tenyks. I'm going to work on moving them to the newer
[tenyks-service](https://github.com/kyleterry/tenyks-service) class.

A good example of something more dynamic is the [Weather
service](https://github.com/kyleterry/tenyks-contrib/blob/master/src/tenykswunderground/main.py).

## Credit where credit is due

Service oriented anything isn't new. This idea came from an old
[coworker](https://github.com/wraithan) of mine. I just wanted to do something
slightly different. There are also plenty of other plugin style bots (such as
hubot and eggdrop). Every open source project needs love, so check those out as
well.

Tenyks

A bot for Telegram, Mastodon, Slack, and other messaging platforms archives webpages.

# Wayback

[![LICENSE](https://img.shields.io/github/license/wabarc/wayback.svg?color=green)](https://github.com/wabarc/wayback/blob/main/LICENSE)
[![Go Report Card](https://goreportcard.com/badge/github.com/wabarc/wayback)](https://goreportcard.com/report/github.com/wabarc/wayback)
[![Test Coverage](https://codecov.io/gh/wabarc/wayback/branch/main/graph/badge.svg)](https://codecov.io/gh/wabarc/wayback)
[![Go Reference](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/wabarc/wayback)
[![Releases](https://img.shields.io/github/v/release/wabarc/wayback.svg?include_prereleases&color=blue)](https://github.com/wabarc/wayback/releases)

[![Telegram Bot](https://img.shields.io/badge/Telegram-bot-3dbeff.svg)](https://t.me/wabarc_bot)
[![Discord Bot](https://img.shields.io/badge/Discord-bot-3dbeff.svg)](https://discord.com/api/oauth2/authorize?client_id=863324809206169640&permissions=2147796992&scope=bot%20applications.commands)
[![Matrix Bot](https://img.shields.io/badge/Matrix-bot-0a976f.svg)](https://matrix.to/#/@wabarc_bot:matrix.org)
[![Matrix Room](https://img.shields.io/badge/Matrix-room-0a976f.svg)](https://matrix.to/#/#wabarc:matrix.org)
[![Tor Hidden Service](https://img.shields.io/badge/Tor%20Hidden%20Service-472756.svg)](http://wabarcoww2bxmdbixj7sjwggv3fonh2rpflfiildegcydk5udkdckdyd.onion/)
[![World Wide Web](https://img.shields.io/badge/Web-15aabf.svg)](https://wabarc.eu.org/)
[![Nostr](https://img.shields.io/badge/Nostr-8e44ad.svg)](https://iris.to/#/profile/npub1gm4xeu8wlt6aa56zenutkwa0ppjng5axsscv424d0xvv5jalxxzs4hjukz)

Wayback is a web archiving and playback tool that allows users to capture and preserve web content. It provides an IM-style interface for receiving and presenting archived web content, and a search and playback service for retrieving previously archived pages. Wayback is designed to be used by web archivists, researchers, and anyone who wants to preserve web content and access it in the future.

## Features

- Free and open-source
- Expose prometheus metrics
- Cross-platform compatibility
- Batch wayback URLs for faster archiving
- Built-in CLI (`wayback`) for convenient use
- Serve as a Tor Hidden Service or local web entry for added privacy and accessibility
- Easier wayback to Internet Archive, archive.today, IPFS and Telegraph integration
- Interactive with IRC, Matrix, Telegram bot, Discord bot, Mastodon, Twitter, and XMPP as a daemon service for convenient use
- Supports publishing wayback results to Telegram channel, Mastodon, and GitHub Issues for sharing
- Supports storing archived files to disk for offline use
- Download streaming media (requires [FFmpeg](https://ffmpeg.org/)) for convenient media archiving.

## Getting Started

For a comprehensive guide, please refer to the complete [documentation](https://docs.wabarc.eu.org/).

### Installation

The simplest, cross-platform way is to download from [GitHub Releases](https://github.com/wabarc/wayback/releases) and place the executable file in your PATH.

From source:

```sh
go install github.com/wabarc/wayback/cmd/wayback@latest
```

From GitHub Releases:

```sh
curl -fsSL https://get.wabarc.eu.org | sh
```

or via [Bina](https://bina.egoist.dev/):

```sh
curl -fsSL https://bina.egoist.dev/wabarc/wayback | sh
```

Using [Snapcraft](https://snapcraft.io/wayback) (on GNU/Linux)

```sh
sudo snap install wayback
```

Via [APT](https://repo.wabarc.eu.org/deb:wayback):

```bash
curl -fsSL https://repo.wabarc.eu.org/apt/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/packages.wabarc.gpg
echo "deb [arch=amd64,arm64,armhf signed-by=/usr/share/keyrings/packages.wabarc.gpg] https://repo.wabarc.eu.org/apt/ /" | sudo tee /etc/apt/sources.list.d/wayback.list
sudo apt update
sudo apt install wayback
```

Via [RPM](https://repo.wabarc.eu.org/rpm:wayback):

```bash
sudo rpm --import https://repo.wabarc.eu.org/yum/gpg.key
sudo tee /etc/yum.repos.d/wayback.repo > /dev/null <<EOT
[wayback]
name=Wayback Archiver
baseurl=https://repo.wabarc.eu.org/yum/
enabled=1
gpgcheck=1
gpgkey=https://repo.wabarc.eu.org/yum/gpg.key
EOT

sudo dnf install -y wayback
```

Via [Homebrew](https://github.com/wabarc/homebrew-wayback):

```shell
brew tap wabarc/wayback
brew install wayback
```

### Usage

#### Command line

```sh
$ wayback -h

A command-line tool and daemon service for archiving webpages.

Usage:
 wayback [flags]

Examples:
 wayback https://www.wikipedia.org
 wayback https://www.fsf.org https://www.eff.org
 wayback --ia https://www.fsf.org
 wayback --ia --is -d telegram -t your-telegram-bot-token
 WAYBACK_SLOT=pinata WAYBACK_APIKEY=YOUR-PINATA-APIKEY \
 WAYBACK_SECRET=YOUR-PINATA-SECRET wayback --ip https://www.fsf.org

Flags:
 --chatid string Telegram channel id
 -c, --config string Configuration file path, defaults: ./wayback.conf, ~/wayback.conf, /etc/wayback.conf
 -d, --daemon strings Run as daemon service, supported services are telegram, web, mastodon, twitter, discord, slack, irc, xmpp
 --debug Enable debug mode (default mode is false)
 -h, --help help for wayback
 --ia Wayback webpages to Internet Archive
 --info Show application information
 --ip Wayback webpages to IPFS
 --ipfs-host string IPFS daemon host, do not require, unless enable ipfs (default "127.0.0.1")
 -m, --ipfs-mode string IPFS mode (default "pinner")
 -p, --ipfs-port uint IPFS daemon port (default 5001)
 --is Wayback webpages to Archive Today
 --ph Wayback webpages to Telegraph
 --print Show application configurations
 -t, --token string Telegram Bot API Token
 --tor Snapshot webpage via Tor anonymity network
 --tor-key string The private key for Tor Hidden Service
 -v, --version version for wayback
```

#### Examples

Wayback one or more url to *Internet Archive* **and** *archive.today*:

```sh
wayback https://www.wikipedia.org

wayback https://www.fsf.org https://www.eff.org
```

Wayback url to *Internet Archive* **or** *archive.today* **or** *IPFS*:

```sh
// Internet Archive
$ wayback --ia https://www.fsf.org

// archive.today
$ wayback --is https://www.fsf.org

// IPFS
$ wayback --ip https://www.fsf.org
```

For using IPFS, also can specify a pinning service:

```sh
$ export WAYBACK_SLOT=pinata
$ export WAYBACK_APIKEY=YOUR-PINATA-APIKEY
$ export WAYBACK_SECRET=YOUR-PINATA-SECRET
$ wayback --ip https://www.fsf.org

// or

$ WAYBACK_SLOT=pinata WAYBACK_APIKEY=YOUR-PINATA-APIKEY \
$ WAYBACK_SECRET=YOUR-PINATA-SECRET wayback --ip https://www.fsf.org
```

More details about [pinning service](https://github.com/wabarc/ipfs-pinner).

With telegram bot:

```sh
wayback --ia --is --ip -d telegram -t your-telegram-bot-token
```

Publish message to your Telegram channel at the same time:

```sh
wayback --ia --is --ip -d telegram -t your-telegram-bot-token --chatid your-telegram-channel-name
```

Also can run with debug mode:

```sh
wayback -d telegram -t YOUR-BOT-TOKEN --debug
```

Both serve on Telegram and Tor hidden service:

```sh
wayback -d telegram -t YOUT-BOT-TOKEN -d web
```

URLs from file:

```sh
wayback url.txt
```

```sh
cat url.txt | wayback
```

#### Configuration Parameters

Look at the [full list of configuration options](docs/environment.md).

## Deployment

- [wabarc/on-heroku](https://github.com/wabarc/on-heroku)
- [wabarc/on-github](https://github.com/wabarc/on-github)
- [wabarc/on-render](https://github.com/wabarc/on-render)

### Docker/Podman

```sh
docker pull wabarc/wayback
docker run -d wabarc/wayback wayback -d telegram -t YOUR-BOT-TOKEN # without telegram channel
docker run -d wabarc/wayback wayback -d telegram -t YOUR-BOT-TOKEN -c YOUR-CHANNEL-USERNAME # with telegram channel
```

### 1-Click Deploy

**Note:** These are free hosting options. If you need a quick and simple setup, this method may be ideal.

[![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy?template=https://github.com/wabarc/wayback)
<a href="https://render.com/deploy?repo=https://github.com/wabarc/on-render">
 <img
 src="https://render.com/images/deploy-to-render-button.svg"
 alt="Deploy to Render"
 width="155px"
 />
</a>

## Screenshots

<details><summary>Click to see screenshots of the services.</summary>

### Discord
![Discord](./docs/assets/discord-server.png)

### Web Service
![Web](./docs/assets/web.png)

### Mastodon
![Mastodon](./docs/assets/mastodon.png)

### Matrix
![Matrix Room](./docs/assets/matrix-room.png)

### IRC
![IRC](./docs/assets/irc.png)

### Slack
![Slack Channel](./docs/assets/slack-channel.png)

### Telegram
![Telegram Bot](./docs/assets/telegram.png)
![Telegram Channel](./docs/assets/telegram-channel.png)

### XMPP
![XMPP](./docs/assets/xmpp.png)

</details>

## Contributing

We encourage all contributions to this repository! Open an issue! Or open a Pull Request!

If you're interested in contributing to `wayback` itself, read our [contributing guide](./CONTRIBUTING.md) to get started.

Note: All interaction here should conform to the [Code of Conduct](./CODE_OF_CONDUCT.md).

## License

This software is released under the terms of the GNU General Public License v3.0. See the [LICENSE](https://github.com/wabarc/wayback/blob/main/LICENSE) file for details.

[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B30014%2Fgithub.com%2Fwabarc%2Fwayback.svg?type=large)](https://app.fossa.com/projects/custom%2B30014%2Fgithub.com%2Fwabarc%2Fwayback?ref=badge_large)

The Best Go Libraries For Bot Building (26)

bot