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: [9.5](https://core.telegram.org/bots/api#march-1-2026) from March 1, 2026

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 have no 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
- `WithPhotoCaptionHandler` - add handler for Message.Caption 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
- `WithNotAsyncHandlers()` - allows to run handlers in the main goroutine
- `WithInitialOffset(offset int64)` - allows to set initial offset for getUpdates method

## Message.Text and CallbackQuery.Data handlers

For your convenience, you can use `Message.Text`, `CallbackQuery.Data` and `Message.Caption` 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
- `HandlerTypeCallbackQueryGameShortName` - for Update.CallbackQuery.GameShortName field
- `HandlerTypePhotoCaption` - for Update.Message.Caption field

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

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

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

> For `MatchTypeCommand` and `MatchTypeCommandStartOnly` usage see an [example](examples/command_handler/main.go)

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)

## InputSticker

For `CreateNewStickerSet` method you can send sticker by file path or file contents.

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

> field `sticker`: The added sticker. Pass a file_id as a String to send a file that already exists on the Telegram servers, pass an HTTP URL as a String for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>” to upload a new file using multipart/form-data under <file_attach_name> name. Animated and video stickers can't be uploaded via HTTP URL.

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

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

inputSticker1 := models.InputSticker{
	Sticker: "https://github.com/go-telegram/bot/blob/main/examples/create_new_sticker_set/images/telegram.png?raw=true",
	Format: "static",
	EmojiList: []string{"1️⃣"},
}

inputSticker2 := models.InputSticker{
	Sticker: "attach://telegram.png",
	Format: "static",
	EmojiList: []string{"2️⃣"},
	StickerAttachment: bytes.NewReader(fileContent),
}

params := &bot.CreateNewStickerSetParams{
	UserID: update.Message.Chat.ID,
	Name: fmt.Sprintf("Example%d_by_%s", time.Now().Unix(), botUsername),
	Title: "Example sticker set",
	Stickers: []models.InputSticker{
		inputSticker1,
		inputSticker2,
	},
}

b.CreateNewStickerSet(ctx, params)
```

[Demo in examples](examples/create_new_sticker_set/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 *WebAppUser, 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
}
```

## Other

- `bot.ID() int64` - returns bot ID. Bot ID is a unique identifier for the bot, obtained from the token as first part before `:`. Example: `110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw` - bot ID is `110201543`. If the bot token is invalid, the bot ID will be 0.
- `bot.Token() string` - returns bot token
- `bot.SetToken()` - set new bot token

## MiniApp misc

Check the repo [go-telegram/miniapp](https://github.com/go-telegram/miniapp) for Telegram MiniApp example.

Repo [go-telegram/miniapp-types](https://github.com/go-telegram/miniapp-types) contains TypeScript types definitions for Telegram MiniApp object.

## 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="Echotron" width="800">

<div align="center">

[![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)

**The idiomatic, concurrent Telegram Bot library for Go.** 
Zero boilerplate. Built-in rate limiting. One instance per chat, by design.

</div>

## Why Echotron?

Most Telegram bot libraries hand you a stream of updates and leave everything else to you. Echotron goes further: it ships a battle-tested concurrency model out of the box, so you can focus on bot logic instead of synchronisation primitives, rate limiters, and state machinery.

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

## Five-line bot

```go
package main

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

func main() {
 api := echotron.NewAPI("MY_TOKEN")
 
 for u := range echotron.PollingUpdates("MY_TOKEN") {
 if u.Message.Text == "/start" {
 api.SendMessage("Hello, world!", u.ChatID(), nil)
 }
 }
}
```

No setup, no registration, no middleware stack. `PollingUpdates` returns a plain Go channel: range over it and you are done.

## The dispatcher pattern

For production bots, Echotron's `Dispatcher` automatically maintains one isolated bot instance per chat. Each instance gets its own goroutine; state is naturally scoped per conversation.

```go
package main

import (
 "log"
 "time"

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

// bot holds the per-chat state. Each conversation gets its own instance.
// Embedding echotron.API promotes all Telegram methods onto the struct,
// so b.SendMessage works directly without any explicit delegation.
type bot struct {
 chatID int64
 echotron.API
}

// newBot is the factory function called by the Dispatcher the first time
// a given chatID sends a message. It must return an echotron.Bot.
func newBot(chatID int64) echotron.Bot {
 return &bot{chatID, echotron.NewAPI("MY_TOKEN")}
}

// Update is the only method required by the echotron.Bot interface.
// The Dispatcher calls it in a new goroutine for every incoming update,
// so each chat is handled concurrently without blocking the others.
func (b *bot) Update(update *echotron.Update) {
 if update.Message.Text == "/start" {
 b.SendMessage("Hello!", b.chatID, nil)
 }
}

func main() {
 dsp := echotron.NewDispatcher("MY_TOKEN", newBot)
 for {
 // Poll blocks until a network error occurs, then returns it.
 // Sleeping before retrying avoids hammering the API on transient failures.
 log.Println(dsp.Poll())
 time.Sleep(5 * time.Second)
 }
}
```

| Concern | Handled by |
|---|---|
| Routing updates to the right chat | `Dispatcher` |
| Creating state for first-time users | `newBot` factory |
| Calling `Update` concurrently | `Dispatcher` (goroutine per update) |
| Rate limiting API calls | built-in `lclient` |
| Deduplication and offset tracking | `Dispatcher.Poll()` |

## A library, not a framework

Echotron does not ask you to structure your application in any particular way. There is no command router to register, no middleware stack to assemble, no lifecycle hooks to implement, no configuration object to fill out before anything works.

The `Dispatcher` is entirely optional. If you do not need per-chat state management, you can drive updates yourself with a plain channel:

```go
for u := range echotron.PollingUpdates("MY_TOKEN") {
 // your logic here, completely vanilla Go
}
```

If you want webhooks without the Dispatcher, that is a channel too:

```go
for u := range echotron.WebhookUpdates("https://example.com:443/MY_TOKEN", "MY_TOKEN") {
 // handle u
}
```

If you need only a subset of the Telegram API for a quick script or a one-off tool, instantiate `NewAPI` directly and call whatever methods you need. Nothing forces you to go further.

The `Bot` interface itself requires a single method:

```go
type Bot interface {
 Update(*Update)
}
```

That one line is the entire contract. Every other piece of Echotron is additive: pick what fits your use case and ignore the rest.

## Feature highlights

### One instance per chat

The `Dispatcher` stores one `Bot` per `chatID` in a lock-free `sync.Map`. `Update()` is dispatched in a fresh goroutine for every incoming message:

- No chat ever blocks another: a deadlock in chat A has zero effect on chat B.
- State lives in struct fields: no need for maps, mutexes, or context keys to correlate users.
- Crashes are isolated: a panic in one goroutine does not bring down the whole bot.

### Built-in dual-level rate limiting

Echotron ships a transparent, dual-layer rate limiter that mirrors Telegram's own limits. It is always active with sensible defaults and requires no configuration to be correct from day one.

| Limiter | Default | How to change |
|---|---|---|
| Global (all chats) | 30 req/s, burst 30 | `api.SetGlobalRequestLimit(interval, burst)` |
| Per-chat | 20 req/min, burst 20 | `api.SetChatRequestLimit(interval, burst)` |

One shared `http.Client` per bot token means connection pools are reused across all chat instances, keeping resource usage proportional to the number of bots, not the number of users.

### Functional state machines

Multi-step conversations can be modelled as a self-referential function type that returns the next state. No string enums, no external table, no switch-on-state:

```go
// stateFn is a function that handles one update and returns the next state.
// Because it references itself in its own return type, states form a chain:
// each handler decides at runtime which function should run next.
type stateFn func(*echotron.Update) stateFn

type bot struct {
 chatID int64
 state stateFn // current state; replaced after every update
 name string
 echotron.API
}

func newBot(chatID int64) echotron.Bot {
 b := &bot{chatID: chatID, API: echotron.NewAPI("MY_TOKEN")}
 b.state = b.handleMessage // set the initial state
 return b
}

func (b *bot) Update(update *echotron.Update) {
 // Execute the current state and store whatever it returns as the next one.
 // A single assignment is all the state-machine machinery needed.
 b.state = b.state(update)
}

func (b *bot) handleMessage(u *echotron.Update) stateFn {
 if u.Message.Text == "/setname" {
 b.SendMessage("What should I call you?", b.chatID, nil)
 // The next update will be the user's reply, so transition to handleName.
 return b.handleName
 }
 // No relevant command: stay in the default state.
 return b.handleMessage
}

func (b *bot) handleName(u *echotron.Update) stateFn {
 b.name = u.Message.Text
 b.SendMessage("Got it, "+b.name+"!", b.chatID, nil)
 // Name has been recorded; go back to the default state.
 return b.handleMessage
}
```

### Session self-destruction

Inactive sessions can remove themselves from the dispatcher, keeping memory usage proportional to currently active conversations rather than all users who ever interacted with the bot:

```go
func newBot(chatID int64) echotron.Bot {
 b := &bot{chatID, echotron.NewAPI("MY_TOKEN")}
 // Launch the timer in a separate goroutine so newBot returns immediately.
 // The bot instance is fully functional while selfDestruct waits in the background.
 go b.selfDestruct(time.After(time.Hour))
 return b
}

func (b *bot) selfDestruct(ch <-chan time.Time) {
 <-ch // block until the timer fires
 b.SendMessage("Goodbye!", b.chatID, nil)
 // Remove this instance from the dispatcher's session map.
 // After this call the struct will be garbage-collected once no other
 // references remain, freeing all per-chat state automatically.
 dsp.DelSession(b.chatID)
}
```

### Webhook support, with or without a custom server

Minimal webhook:

```go
dsp := echotron.NewDispatcher("MY_TOKEN", newBot)
dsp.ListenWebhook("https://example.com:443/MY_TOKEN")
```

Integrated into an existing HTTP server without displacing your own routes:

```go
mux := http.NewServeMux()
mux.HandleFunc("/api/v1/login", loginHandler)

server := &http.Server{Addr: ":8080", Handler: mux}
dsp.SetHTTPServer(server)
dsp.ListenWebhook("https://example.com:8080/MY_TOKEN")
```

Gzip-compressed payloads from Telegram are handled transparently.

### Direct API parity

Echotron maps 1-to-1 to the [official Telegram Bot API](https://core.telegram.org/bots/api). Method names are identical, just capitalised as required by Go:

```
sendMessage → SendMessage
sendPhoto → SendPhoto
answerCallbackQuery → AnswerCallbackQuery
```

No invented abstractions sit between you and the Telegram docs.

### Type-safe options and enum constants

Optional parameters are typed structs, not variadic `interface{}` bags. Enum values are compile-time constants so the compiler catches typos:

```go
b.SendMessage("*bold*", b.chatID, &echotron.MessageOptions{
 ParseMode: echotron.MarkdownV2,
})

b.SendChatAction(b.chatID, echotron.Typing)
```

Pass `nil` for optional parameters when you do not need them.

### Structured API errors

Errors from Telegram are typed `*APIError` values, not raw strings, so you can inspect the error code and description separately:

```go
_, err := api.SendMessage("hello", chatID, nil)
var apiErr *echotron.APIError
if errors.As(err, &apiErr) {
 fmt.Println(apiErr.ErrorCode(), apiErr.Description())
}
```

### Local Bot API server support

Running a [Telegram Local Bot API](https://github.com/tdlib/telegram-bot-api) server for increased file size limits and upload throughput? One function call is all it takes:

```go
api := echotron.CustomAPI("http://localhost:8081/bot", "MY_TOKEN")
```

All methods route through your local server with no further changes.

## Design gems

The following are a few of the internal decisions that make Echotron pleasant to work with and correct under concurrent load.

### A generic, type-safe sync.Map wrapper

Session storage is backed by a generic type declared as:

```go
type smap[K, V any] sync.Map
```

This thin wrapper over `sync.Map` provides full type safety without any runtime overhead. There are no `interface{}` assertions scattered through the codebase and no risk of a type mismatch crashing the dispatcher at runtime.

### Three levels of embedding, zero indirection

`API` embeds `*lclient` as an anonymous field. `lclient` carries the rate-limiter methods `SetGlobalRequestLimit` and `SetChatRequestLimit`. Because the user's bot struct embeds `echotron.API`, those same methods are promoted all the way to the bot struct level. Calling `b.SetGlobalRequestLimit(...)` from inside your bot just works, with no explicit delegation code anywhere.

### Atomic client initialisation without a mutex

When a new bot token is first used, Echotron creates an `http.Client` and stores it in a package-level cache keyed by base URL. The initialisation uses `sync.Map.LoadOrStore` atomically: if two goroutines race to create the client at the same time, exactly one wins and both receive the same pointer. No mutex, no double-checked locking pattern, no `sync.Once` per token.

### `Update.ChatID()` absorbs all update types

The `ChatID()` method on `Update` inspects every possible update variant, from plain messages and callback queries to business connections, story interactions, chat boosts, and more, and always returns the correct `int64`. The dispatcher calls this one method to route any update to the right bot instance, regardless of its type.

### `InputFile` is a sealed type

`InputFile` has only unexported fields. The only way to create one is through:

```go
echotron.NewInputFileID("AgACAgI...") // existing Telegram file
echotron.NewInputFilePath("photo.jpg") // local file on disk
echotron.NewInputFileBytes("img.png", data) // in-memory bytes
```

It is structurally impossible to create an `InputFile` in an invalid state from outside the package.

### A single dispatch choke point

Every API call, whether a plain GET, a form-encoded POST, or a multipart file upload, passes through the internal `lclient.dispatch()` function. Rate limiting, HTTP execution, JSON decoding, and error checking all happen exactly once, in one place. There is no duplicated error handling across the hundreds of API methods.

### The `stateFn` self-referential type

`type stateFn func(*Update) stateFn` is a function type that returns itself. This single line enables recursive, allocation-free state machines where the current state is simply the function that will handle the next update. No string-keyed state table, no `iota` enum, no external dependency.

## Echotron vs. other Go Telegram libraries

| Feature | **Echotron** | go-telegram-bot-api | telebot | gotgbot |
|---|:---:|:---:|:---:|:---:|
| Per-chat isolated state | ✅ built-in | ❌ manual | ❌ manual | ❌ manual |
| Concurrency model | ✅ built-in | ❌ manual | ⚠️ partial | ❌ manual |
| Built-in rate limiting | ✅ dual-level | ❌ | ❌ | ❌ |
| Shared HTTP client pool | ✅ per-token | ❌ | ❌ | ❌ |
| 1:1 Telegram API parity | ✅ | ✅ | ⚠️ | ✅ |
| Type-safe enums | ✅ | ⚠️ | ⚠️ | ⚠️ |
| Typed API errors | ✅ | ⚠️ | ⚠️ | ⚠️ |
| Functional state machines | ✅ first-class | ❌ | ❌ | ❌ |
| Session self-destruction | ✅ | ❌ | ❌ | ❌ |
| Custom HTTP server | ✅ | ⚠️ | ⚠️ | ⚠️ |
| Local API server support | ✅ | ✅ | ✅ | ✅ |
| No mandatory abstractions | ✅ | ✅ | ❌ | ✅ |
| External dependencies | 1 | 0 | several | 0 |
| License | LGPL-3.0 | MIT | MIT | MIT |

On the topic of dependencies: Echotron's single dependency is [`golang.org/x/time`](https://pkg.go.dev/golang.org/x/time), which lives in the `golang.org/x` namespace. That namespace is maintained by the Go team itself, under the same review standards and stability guarantees as the standard library. In practice, adding Echotron to your project means depending on the Go team's own code and nothing else.

**On the license:** LGPL-3.0 allows you to use Echotron in closed-source and commercial products without releasing your own code, provided you do not modify Echotron itself.

## More examples

### Sending files

```go
// From a local path
b.SendPhoto(b.chatID, echotron.NewInputFilePath("photo.jpg"), nil)

// By Telegram file_id, no re-upload
b.SendPhoto(b.chatID, echotron.NewInputFileID("AgACAgI..."), nil)

// From raw bytes already in memory
b.SendPhoto(b.chatID, echotron.NewInputFileBytes("photo.jpg", data), nil)
```

### Media groups

```go
b.SendMediaGroup(b.chatID, []echotron.GroupableInputMedia{
 echotron.InputMediaPhoto{Media: echotron.NewInputFilePath("a.jpg")},
 echotron.InputMediaPhoto{Media: echotron.NewInputFilePath("b.jpg")},
 echotron.InputMediaVideo{Media: echotron.NewInputFilePath("clip.mp4")},
}, nil)
```

### Inline keyboards

```go
b.SendMessage("Choose an option:", b.chatID, &echotron.MessageOptions{
 ReplyMarkup: echotron.InlineKeyboardMarkup{
 InlineKeyboard: [][]echotron.InlineKeyboardButton{
 {{Text: "Option A", CallbackData: "a"}},
 {{Text: "Option B", CallbackData: "b"}},
 },
 },
})
```

### Handling callback queries

```go
func (b *bot) Update(u *echotron.Update) {
 // Telegram guarantees that at most one field in an Update is non-nil,
 // so a switch on nil checks is the idiomatic way to route update types.
 switch {
 case u.CallbackQuery != nil:
 // AnswerCallbackQuery must be called to dismiss the loading indicator
 // shown by Telegram on the user's side after they tap a button.
 b.AnswerCallbackQuery(u.CallbackQuery.ID, nil)
 b.SendMessage("You chose: "+u.CallbackQuery.Data, b.chatID, nil)
 case u.Message != nil:
 b.SendMessage("Send me a button press!", b.chatID, nil)
 }
}
```

### Custom rate limits

```go
api := echotron.NewAPI("MY_TOKEN")

api.SetGlobalRequestLimit(time.Second/50, 50) // 50 req/s globally
api.SetChatRequestLimit(time.Second, 1) // 1 msg/s per chat
```

## Installation

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

Go 1.21 or later is required.

## Starter templates

Every example in the [`example/`](./example/) directory is a self-contained Go
module usable as a project skeleton with
[`gonew`](https://pkg.go.dev/golang.org/x/tools/cmd/gonew).

```bash
go install golang.org/x/tools/cmd/gonew@latest
```

| Template | What it gives you |
|---|---|
| `polling-simple` | Minimal stateless bot, plain update channel, no `Dispatcher` |
| `polling` | Per-chat stateful bot with `Dispatcher` and long-polling |
| `polling-keyboard` | Inline keyboards and callback query handling |
| `polling-inline` | Inline mode (`@botname <query>` from any chat) |
| `polling-ratelimit` | Rate limiter configuration |
| `polling-fsm` | Multi-step conversations via functional state machines |
| `polling-fsm-lifecycle` | FSM + session self-destruction on idle timeout |
| `polling-fsm-persistence` | FSM + disk persistence with [katalis](https://github.com/NicoNex/katalis) |
| `webhook` | `Dispatcher` with webhook delivery |
| `webhook-simple` | Minimal stateless bot on webhooks |

Clone any template and rename the module in one command:

```bash
gonew github.com/NicoNex/echotron/v3/example/polling github.com/you/mybot
cd mybot
TELEGRAM_TOKEN=<your-token> go run .
```

See [`example/README.md`](example/README.md) for the full list and a suggested reading order.

## Links

- [pkg.go.dev documentation](https://pkg.go.dev/github.com/NicoNex/echotron/v3)
- [Telegram Bot API reference](https://core.telegram.org/bots/api)
- [Echotron News on Telegram](https://t.me/echotronnews)
- [Report an issue](https://github.com/NicoNex/echotron/issues)

## License

Echotron is free software released under the **GNU Lesser General Public License v3.0**.
See [LICENSE](LICENSE) for details.

echotron

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

go-twitch-irc

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

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

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

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

slack-bot

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

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

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

[![GoDoc](https://godoc.org/gopkg.in/telebot.v4?status.svg)](https://godoc.org/gopkg.in/telebot.v4)
[![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.v4
```

* [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.v4"
)

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.v4#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.v4/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.v4#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

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

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

telego

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)
 --ga Wayback webpages to Ghostarchive (default true)
 -h, --help help for wayback
 --ia Wayback webpages to Internet Archive (default true)
 --info Show application information
 --ip Wayback webpages to IPFS (default true)
 --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 (default true)
 --migrate Run SQL migrations
 --ph Wayback webpages to Telegraph (default true)
 --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)
- [wabarc/on-vercel](https://github.com/wabarc/on-vercel)
- [wabarc/on-digitalocean](https://github.com/wabarc/on-digitalocean)

### 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="147px"
 height="32px"
 />
</a>
<a href="https://cloud.digitalocean.com/apps/new?repo=https://github.com/wabarc/on-digitalocean/tree/main">
 <img
 src="https://www.deploytodo.com/do-btn-blue.svg"
 alt="Deploy to DigitalOcean"
 width="200px"
 height="32px"
 />
</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)

## Credits

Thanks to DigitalOcean for supporting open-source software.


 <a href="https://m.do.co/c/cb27a8691d73">
 <img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/SVG/DO_Logo_horizontal_blue.svg" width="201px" alt="DigitalOcean">
 </a>

wayback

# 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

# 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 library and framework for the Discord API

# arikawa

[![ Pipeline Status ][pipeline_img ]][pipeline ]
[![ Report Card ][goreportcard_img]][goreportcard]
[![ Godoc Reference ][pkg.go.dev_img ]][pkg.go.dev ]
[![ Examples ][examples_img ]][examples ]
[![ Discord Gophers ][dgophers_img ]][dgophers ]
[![ Hime Arikawa ][himeArikawa_img ]][himeArikawa ]

A Golang library for the Discord API.

[dgophers]: https://discord.gg/7jSf85J
[dgophers_img]: https://img.shields.io/badge/Discord%20Gophers-%23arikawa-%237289da?style=flat-square

[examples]: https://github.com/diamondburned/arikawa/tree/v3/0-examples
[examples_img]: https://img.shields.io/badge/Example-.%2F0--examples%2F-blueviolet?style=flat-square

[pipeline]: https://github.com/diamondburned/arikawa/actions/workflows/test.yml
[pipeline_img]: https://img.shields.io/github/actions/workflow/status/diamondburned/arikawa/test.yml?style=flat-square&label=Tests

[pkg.go.dev]: https://pkg.go.dev/github.com/diamondburned/arikawa/v3
[pkg.go.dev_img]: https://img.shields.io/badge/%E2%80%8B-reference-007d9c?logo=go&logoColor=white&style=flat-square

[himeArikawa]: https://hime-goto.fandom.com/wiki/Hime_Arikawa
[himeArikawa_img]: https://img.shields.io/badge/Hime-Arikawa-ea75a2?style=flat-square

[goreportcard]: https://goreportcard.com/report/github.com/diamondburned/arikawa
[goreportcard_img]: https://goreportcard.com/badge/github.com/diamondburned/arikawa?style=flat-square&label=Go%20Report


## Library Highlights

- More modularity with components divided up into independent packages, such as
 the API client and the Websocket Gateway being fully independent.
- Clear separation of models: API and Gateway models are never mixed together so
 to not be confusing.
- Extend and intercept Gateway events, allowing for use cases such as reading
 deleted messages.
- Pluggable Gateway cache allows for custom caching implementations such as
 Redis, automatically falling back to the API if needed.
- Typed Snowflakes make it much harder to accidentally use the wrong ID (e.g.
 it is impossible to use a channel ID as a message ID).
- Working user account support, with much of them in [ningen][ningen]. Please
 do not use this for self-botting, as that is against Discord's ToS.

[ningen]: https://github.com/diamondburned/ningen


## Examples

### [Commands (Hybrid)](https://github.com/diamondburned/arikawa/tree/v3/0-examples/commands-hybrid)

commands-hybrid is an alternative variant of
[commands](https://github.com/diamondburned/arikawa/tree/v3/0-examples/commands),
where the program permits being hosted either as a Gateway-based daemon or as a
web server using the Interactions Webhook API.

Both examples demonstrate adding interaction commands into the bot as well as an
example of routing those commands to be executed.

### [Simple](https://github.com/diamondburned/arikawa/tree/v3/0-examples/simple)

Simple bot example without any state. All it does is logging messages sent into
the console. Run with `BOT_TOKEN="TOKEN" go run .`. This example only
demonstrates the most simple needs; in most cases, bots should use the state or
the bot router.

**Note** that Discord discourages use of bots that do not use the interactions
API, meaning that this example should not be used for bots.

### [Undeleter](https://github.com/diamondburned/arikawa/tree/v3/0-examples/undeleter)

A slightly more complicated example. This bot uses a local state to cache
everything, including messages. It detects when someone deletes a message,
logging the content into the console.

This example demonstrates the PreHandler feature of the state library.
PreHandler calls all handlers that are registered (separately from the session),
calling them before the state is updated.

**Note** that Discord discourages use of bots that do not use the interactions
API, meaning that this example should not be used for bots.

### Bare Minimum Bot Example

The least amount of code recommended to have a bot that responds to a /ping.

```go
package main

import (
	"context"
	"log"
	"os"

	"github.com/diamondburned/arikawa/v3/api"
	"github.com/diamondburned/arikawa/v3/api/cmdroute"
	"github.com/diamondburned/arikawa/v3/gateway"
	"github.com/diamondburned/arikawa/v3/state"
	"github.com/diamondburned/arikawa/v3/utils/json/option"
)

var commands = []api.CreateCommandData{{Name: "ping", Description: "Ping!"}}

func main() {
	r := cmdroute.NewRouter()
	r.AddFunc("ping", func(ctx context.Context, data cmdroute.CommandData) *api.InteractionResponseData {
		return &api.InteractionResponseData{Content: option.NewNullableString("Pong!")}
	})

	s := state.New("Bot " + os.Getenv("BOT_TOKEN"))
	s.AddInteractionHandler(r)
	s.AddIntents(gateway.IntentGuilds)

	if err := cmdroute.OverwriteCommands(s, commands); err != nil {
		log.Fatalln("cannot update commands:", err)
	}

	if err := s.Connect(context.TODO()); err != nil {
		log.Println("cannot connect:", err)
	}
}
```


## Testing

The package includes integration tests that require `$BOT_TOKEN`. To run these
tests, do:

```sh
export BOT_TOKEN="<BOT_TOKEN>"
go test -tags integration -race ./...
```

arikawa

<img width="2562" height="2855" alt="image" src="https://github.com/user-attachments/assets/fe90b972-3cdb-43ee-8584-aac05a414d61" />

# TG - Telegram Bot Framework for Go

[![Go Reference](https://pkg.go.dev/badge/github.com/enetx/tg.svg)](https://pkg.go.dev/github.com/enetx/tg)
[![Go Report Card](https://goreportcard.com/badge/github.com/enetx/tg)](https://goreportcard.com/report/github.com/enetx/tg)
[![Coverage Status](https://coveralls.io/repos/github/enetx/tg/badge.svg?branch=main&service=github)](https://coveralls.io/github/enetx/tg?branch=main)
[![Go](https://github.com/enetx/tg/actions/workflows/go.yml/badge.svg)](https://github.com/enetx/tg/actions/workflows/go.yml)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/enetx/tg)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
[![Telegram Bot API Version][TelegramVersionBadge]][TelegramLastVersion]

Modern and elegant wrapper around [gotgbot](https://github.com/PaulSonOfLars/gotgbot) with convenient API and functional programming style support.

## Video Demo

[![TG Framework Demo](https://img.youtube.com/vi/Mb8y4hDj7so/0.jpg)](https://www.youtube.com/watch?v=Mb8y4hDj7so)

## Features

- 🚀 **Simple and intuitive API** with method chaining support
- 🎯 **Type-safe** event handlers for all Telegram update types
- 🔧 **Flexible bot configuration** through Builder pattern
- 📝 **Rich functionality** for messages, media, keyboards and payments
- 🎮 **Built-in FSM support** (finite state machines) for complex dialogues
- 💰 **Telegram Payments and Stars** support with refunds
- 🎲 **Full support** for all Telegram content types and features
- 🔧 **Middleware system** for request filtering and processing
- 📂 **Advanced file handling** with metadata and thumbnails
- 🌐 **Webhook support** with security features

## Quick Start

### Installation

```bash
go mod init your-bot
go get github.com/enetx/tg
```

### Simple Echo Bot

```go
package main

import (
 "github.com/enetx/g"
 "github.com/enetx/tg/bot"
 "github.com/enetx/tg/ctx"
)

func main() {
 token := "token"
 b := bot.New(token).Build().Unwrap()

 // Handle text messages
 b.On.Message.Text(func(ctx *ctx.Context) error {
 return ctx.Reply("Echo: " + g.String(ctx.EffectiveMessage.Text)).Send().Err()
 })

 // Handle /start command
 b.Command("start", func(ctx *ctx.Context) error {
 return ctx.Reply("Welcome to the bot!").Send().Err()
 })

 b.Polling().Start()
}
```

## Message Handlers

Handle different types of Telegram messages:

```go
// Text messages
b.On.Message.Text(func(ctx *ctx.Context) error {
 return ctx.Reply("Text received").Send().Err()
})

// Media messages
b.On.Message.Photo(func(ctx *ctx.Context) error {
 return ctx.Reply("Photo received").Send().Err()
})

b.On.Message.Voice(func(ctx *ctx.Context) error {
 return ctx.Reply("Voice received").Send().Err()
})

b.On.Message.Video(func(ctx *ctx.Context) error {
 return ctx.Reply("Video received").Send().Err()
})

b.On.Message.Document(func(ctx *ctx.Context) error {
 return ctx.Reply("Document received").Send().Err()
})

// Contact and location
b.On.Message.Contact(func(ctx *ctx.Context) error {
 contact := ctx.EffectiveMessage.Contact
 return ctx.Reply("Thanks for sharing your contact!").Send().Err()
})

b.On.Message.Location(func(ctx *ctx.Context) error {
 location := ctx.EffectiveMessage.Location
 return ctx.Reply("Location received").Send().Err()
})
```

## Commands

Register commands with advanced options:

```go
// Basic command
b.Command("start", func(ctx *ctx.Context) error {
 return ctx.SendMessage("Start command triggered!").Send().Err()
})

// Command with custom triggers and options
b.Command("help", func(ctx *ctx.Context) error {
 return ctx.Reply("Help message").Send().Err()
}).
 Triggers('!', '.'). // Allow !help and .help
 AllowEdited(). // Handle edited messages
 AllowChannel(). // Work in channels
 Register()

// Commands work automatically, but you can customize them further
```

## Inline Keyboards

Create interactive inline keyboards:

```go
// Basic inline keyboard
b.Command("menu", func(ctx *ctx.Context) error {
 markup := keyboard.Inline().
 Row().
 Text("Option 1", "opt1").
 Text("Option 2", "opt2").
 Row().
 URL("Visit Site", "https://example.com").
 WebApp("Open App", "https://webapp.com")

 return ctx.Reply("Choose an option:").Markup(markup).Send().Err()
})

// Handle button presses
b.On.Callback.Equal("opt1", func(ctx *ctx.Context) error {
 return ctx.AnswerCallbackQuery("You chose option 1!").Send().Err()
})

b.On.Callback.Prefix("opt", func(ctx *ctx.Context) error {
 data := ctx.Update.CallbackQuery.Data
 return ctx.AnswerCallbackQuery("You clicked: " + g.String(data)).Alert().Send().Err()
})
```

### Dynamic Keyboard Editing

```go
b.On.Callback.Equal("edit", func(ctx *ctx.Context) error {
 // Edit existing keyboard
 markup := keyboard.Inline(ctx.EffectiveMessage.ReplyMarkup).
 Edit(func(btn *keyboard.Button) {
 switch btn.Get.Callback() {
 case "opt1":
 btn.Text("Modified Option 1")
 case "remove":
 btn.Delete()
 }
 })

 return ctx.EditMessageReplyMarkup(markup).Send().Err()
})
```

## Reply Keyboards

Create custom reply keyboards:

```go
b.Command("keyboard", func(ctx *ctx.Context) error {
 markup := keyboard.Reply().
 Row().
 Text("Regular Button").
 Contact("📞 Share Phone").
 Row().
 Location("📍 Send Location").
 WebApp("🌐 Web App", "https://webapp.com").
 Row().
 Poll("📊 Create Poll")

 return ctx.Reply("Use the keyboard below:").Markup(markup).Send().Err()
})
```

## File Handling

Send various types of media files:

```go
// Photo
b.Command("photo", func(ctx *ctx.Context) error {
 return ctx.SendPhoto("photo.png").
 Caption("Beautiful photo").
 Send().Err()
})

// Document with advanced options
b.Command("doc", func(ctx *ctx.Context) error {
 return ctx.SendDocument("document.pdf").
 Caption("Important document").
 Reply(reply.New(ctx.EffectiveMessage.MessageId)).
 Send().Err()
})

// Video with metadata
b.Command("video", func(ctx *ctx.Context) error {
 return ctx.SendVideo("video.mp4").
 Caption("Cool video").
 Spoiler().
 Timeout(3 * time.Minute). // Custom timeout
 ApplyMetadata(). // Extract video info (ffprobe)
 GenerateThumbnail(). // Auto-generate thumbnail (ffmpeg)
 Send().Err()
})

// Audio with metadata
b.Command("audio", func(ctx *ctx.Context) error {
 return ctx.SendAudio("song.mp3").
 Title("Song Title").
 Performer("Artist Name").
 Duration(180 * time.Second).
 Send().Err()
})
```

## Finite State Machine (FSM)

Create complex multi-step conversations:

```go
import (
	"github.com/enetx/fsm"
	"github.com/enetx/g"
	"github.com/enetx/tg/bot"
	"github.com/enetx/tg/ctx"
)

// Define states
const (
	StateGetEmail = "get_email"
	StateGetName = "get_name"
	StateSummary = "summary"
)

// Store FSM instances per user
var fsmStore = g.NewMapSafe[int64, *fsm.SyncFSM]()

func main() {
	b := bot.New(token).Build().Unwrap()

	// Create FSM template
	template := fsm.New(StateGetEmail).
		Transition(StateGetEmail, "next", StateGetName).
		Transition(StateGetName, "next", StateSummary)

	// Define state handlers
	template.OnEnter(StateGetEmail, func(fctx *fsm.Context) error {
		tgctx := fctx.Meta.Get("tgctx").Some().(*ctx.Context)
		return tgctx.Reply("Enter your email:").Send().Err()
	})

	template.OnEnter(StateGetName, func(fctx *fsm.Context) error {
		email := fctx.Input.(string)
		fctx.Data.Set("email", email)

		tgctx := fctx.Meta.Get("tgctx").Some().(*ctx.Context)
		return tgctx.Reply("Enter your name:").Send().Err()
	})

	template.OnEnter(StateSummary, func(fctx *fsm.Context) error {
		name := fctx.Input.(string)
		email := fctx.Data.Get("email").UnwrapOr("<no email>")

		tgctx := fctx.Meta.Get("tgctx").Some().(*ctx.Context)
		defer fsmStore.Delete(tgctx.EffectiveUser.Id)

		return tgctx.Reply(g.Format("Got name: {} and email: {}", name, email)).Send().Err()
	})

	// Start FSM
	b.Command("register", func(ctx *ctx.Context) error {
		fsm := fsmStore.Entry(ctx.EffectiveUser.Id).OrInsertWith(template.Clone().Sync)

		fsm.SetState(StateGetEmail)
		fsm.Context().Meta.Set("tgctx", ctx)
		return fsm.CallEnter(StateGetEmail)
	})

	// Handle FSM input
	b.On.Message.Text(func(ctx *ctx.Context) error {
		opt := fsmStore.Get(ctx.EffectiveUser.Id)
		if opt.IsNone() {
			return nil // No active FSM
		}

		fsm := opt.Some()
		fsm.Context().Meta.Set("tgctx", ctx)
		return fsm.Trigger("next", ctx.EffectiveMessage.Text)
	})

	b.Polling().Start()
}
```

## Payments with Telegram Stars

Handle payments using Telegram's Stars system:

```go
// Create invoice
b.Command("buy", func(ctx *ctx.Context) error {
 if ctx.EffectiveChat.Type != "private" {
 return nil
 }

 return ctx.SendInvoice("Premium Access", "Get premium features", "premium_123", "XTR").
 Price("Premium Plan", 100). // 100 stars
 Protect(). // Content protection
 Send().Err()
})

// Handle pre-checkout (validation)
b.On.PreCheckout.Any(func(ctx *ctx.Context) error {
 // Validate payment here if needed
 return ctx.AnswerPreCheckoutQuery().Ok().Send().Err()
})

// Handle successful payment
b.On.Message.SuccessfulPayment(func(ctx *ctx.Context) error {
 user := ctx.EffectiveUser
 payment := ctx.EffectiveMessage.SuccessfulPayment
 chargeID := payment.TelegramPaymentChargeId

 // Grant premium access here
 g.Println("User {1.FirstName} ({1.Id}) paid {2.TotalAmount} {2.Currency} with payload {2.InvoicePayload}",
 user, payment)

 return ctx.SendMessage(g.Format("Payment complete! Thank you, {}!\nChargeID:\n{}", user.FirstName, chargeID)).
 Send().Err()
})

// Handle refunds
b.Command("refund", func(ctx *ctx.Context) error {
 chargeID := ctx.Args().Get(0).Some()

 if result := ctx.RefundStarPayment(chargeID).Send(); result.IsErr() {
 err := g.String(result.Err().Error())
 if err.Contains("CHARGE_ALREADY_REFUNDED") {
 return ctx.Reply("This payment was already refunded.").Send().Err()
 }
 return ctx.Reply("Refund failed.").Send().Err()
 }

 return ctx.Reply("Refund processed successfully.").Send().Err()
})
```

## Middleware

Add middleware for request processing:

```go
// Global middleware
b.Use(func(ctx *ctx.Context) error {
 // Log all updates
 fmt.Println("Update from user:", ctx.EffectiveUser.Id)
 return nil // Continue processing
})

// Admin-only middleware
adminMiddleware := func(ctx *ctx.Context) error {
	admin := ctx.IsAdmin()
	if admin.IsErr() {
		return admin.Err()
	}

	if !admin.Ok() {
		return ctx.AnswerCallbackQuery("Access restricted to admins only!").Alert().Send().Err()
	}

 return nil // Continue
}

// Apply middleware to specific handlers
b.On.Callback.Prefix("admin_", adminMiddleware)
```

## Webhook Mode

Set up webhook instead of polling:

```go
import (
 "net/http"
 "io"

 "github.com/enetx/tg/bot"
 "github.com/enetx/tg/types/updates"
)

func main() {
 b := bot.New(token).Build().Unwrap()

 // Register webhook
 result := b.Webhook().
 Domain("https://yourdomain.com").
 Path("/webhook").
 SecretToken("your-secret").
 AllowedUpdates(updates.Message, updates.CallbackQuery).
 Register()
 if result.IsErr() {
 panic(result.Err())
 }

 // Setup HTTP server
 http.HandleFunc("/webhook", func(w http.ResponseWriter, r *http.Request) {
 // Verify secret token
 if r.Header.Get("X-Telegram-Bot-Api-Secret-Token") != "your-secret" {
 http.Error(w, "Unauthorized", http.StatusUnauthorized)
 return
 }

 body, _ := io.ReadAll(r.Body)
 b.HandleWebhook(body)
 w.WriteHeader(http.StatusOK)
 })

 http.ListenAndServe(":8080", nil)
}
```

## Business Account API

Handle business account connections and messages:

```go
// Handle business connection updates
b.On.BusinessConnection.Enabled(func(ctx *ctx.Context) error {
 conn := ctx.Update.BusinessConnection

 // Configure business account
 return ctx.Business(g.String(conn.Id)).SetName("My Business").
 LastName("LLC").
 Send().Err()
})

// Handle business messages
b.On.Message.Business(func(ctx *ctx.Context) error {
 return ctx.Reply("Business message received!").Send().Err()
})

// Handle deleted business messages
b.On.BusinessMessagesDeleted.Any(func(ctx *ctx.Context) error {
 deleted := ctx.Update.DeletedBusinessMessages
 // Process message deletions
 return nil
})

// Manage business account settings
b.Command("business_setup", func(ctx *ctx.Context) error {
 connectionId := g.String("your_connection_id")

 // Set profile information
 err := ctx.Business(connectionId).
 SetBio("Professional business account").
 Send().Err()

 if err != nil {
 return err
 }

 // Check star balance
 balance := ctx.Business(connectionId).Balance().GetStarBalance().Send()
 if balance.IsOk() {
 return ctx.Reply(g.Format("Stars balance: {}", balance.Ok().Amount)).Send().Err()
 }

 return ctx.Reply("Business account configured").Send().Err()
})
```

## Text Entities and Formatting

Format text messages with various entities:

```go
import (
 "github.com/enetx/g"
 "github.com/enetx/tg/entities"
)

// Basic text formatting
b.Command("format", func(ctx *ctx.Context) error {
 text := g.String("Hello bold italic code")

 e := entities.New(text).
 Bold("bold"). // Make "bold" bold
 Italic("italic"). // Make "italic" italic
 Code("code") // Make "code" monospace

 return ctx.Reply(text).
 Entities(e).
 Send().Err()
})

// Links and spoilers
b.Command("links", func(ctx *ctx.Context) error {
 text := g.String("Click here to visit Google")

 e := entities.New(text).
 URL("here", "https://google.com"). // "here" as hyperlink
 Spoiler("Google") // "Google" as spoiler

 return ctx.Reply(text).
 Entities(e).
 Send().Err()
})

// Code blocks with syntax highlighting
b.Command("codeblock", func(ctx *ctx.Context) error {
 code := g.String(`func main() {
 fmt.Println("Hello")
}`)
 codeText := g.Format("Check this Go code:\n{}", code)

 e := entities.New(codeText).
 Pre(code, "go") // Go code with syntax highlighting

 return ctx.Reply(codeText).
 Entities(e).
 Send().Err()
})

// Multiple formatting types
b.Command("mixed", func(ctx *ctx.Context) error {
 text := g.String("Bold italic underline strikethrough spoiler")

 e := entities.New(text).
 Bold("Bold").
 Italic("italic").
 Underline("underline").
 Strikethrough("strikethrough").
 Spoiler("spoiler")

 return ctx.Reply(text).
 Entities(e).
 Send().Err()
})

// Blockquotes
b.Command("quotes", func(ctx *ctx.Context) error {
 text := g.String(`Regular text
This is a blockquote
This is expandable quote`)

 e := entities.New(text).
 Blockquote("This is a blockquote").
 ExpandableBlockquote("This is expandable quote")

 return ctx.Reply(text).
 Entities(e).
 Send().Err()
})
```

## Advanced Features

### Chat Actions

Show typing indicators and other actions:

```go
b.On.Message.Text(func(ctx *ctx.Context) error {
 // Show typing indicator
 ctx.SendChatAction().Typing().Send()

 // Process message...
 time.Sleep(2 * time.Second)

 return ctx.Reply("Processed your message").Send().Err()
})
```

### Dice and Games

```go
// Send dice
b.Command("dice", func(ctx *ctx.Context) error {
 return ctx.SendDice().Send().Err()
})

// Send slot machine
b.Command("slot", func(ctx *ctx.Context) error {
 return ctx.SendDice().Slot().Send().Err()
})
```

### Message Editing and Deletion

```go
b.Command("edit", func(ctx *ctx.Context) error {
 // Send initial message
 msg := ctx.Reply("Original message").Send()

 // Edit it
 return ctx.EditMessageText("Edited message").MessageID(msg.Ok().MessageId).Send().Err()
})

b.Command("delete", func(ctx *ctx.Context) error {
 return ctx.DeleteMessage().Send().Err()
})
```

## Bot Configuration

Configure bot with advanced options:

```go
b := bot.New(token).
 APIURL("https://api.telegram.org"). // Custom API URL
 UseTestEnvironment(). // Use test environment
 DisableTokenCheck(). // Skip token validation
 Build().
 Unwrap()
```

## Error Handling

All methods follow a consistent error handling pattern:

```go
if err := ctx.Reply("Hello").Send().Err(); err != nil {
 log.Printf("Failed to send message: %v", err)
}

// Or chain with result handling
result := ctx.SendPhoto("image.jpg").Send()
if result.IsErr() {
 log.Printf("Failed to send photo: %v", result.Err())
}
```

## API Documentation

Full API documentation is available at [GoDoc](https://pkg.go.dev/github.com/enetx/tg).

## License

MIT License. See `LICENSE` file for details.

## Support

- Create GitHub issues for bug reports
- Use discussions for questions and suggestions
- Explore examples in the `examples/` folder

[TelegramBotAPI]: https://core.telegram.org/bots/api

[TelegramVersionBadge]: https://img.shields.io/static/v1?label=Supported%20Telegram%20Bot%20API&color=29a1d4&logo=telegram&message=v9.4

[TelegramLastVersion]: https://core.telegram.org/bots/api#february-9-2026

Go SDK for Yandex Messenger Bot API with type-safe models, automatic retry, and rate-limit handling

# Yandex Messenger Go SDK (ymsdk)

[English](README.en.md)

[![CI](https://github.com/rekurt/ymsdk/actions/workflows/ci.yml/badge.svg)](https://github.com/rekurt/ymsdk/actions/workflows/ci.yml)
[![Go Reference](https://pkg.go.dev/badge/github.com/rekurt/ymsdk.svg)](https://pkg.go.dev/github.com/rekurt/ymsdk)
[![Go Report Card](https://goreportcard.com/badge/github.com/rekurt/ymsdk)](https://goreportcard.com/report/github.com/rekurt/ymsdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Go Version](https://img.shields.io/github/go-mod/go-version/rekurt/ymsdk)](go.mod)
[![codecov](https://codecov.io/gh/rekurt/ymsdk/branch/master/graph/badge.svg)](https://codecov.io/gh/rekurt/ymsdk)

Легковесный Go-клиент для Yandex Messenger Bot API с типобезопасными моделями, встроенным retry и сервисами для всех основных методов API. Документация: https://pkg.go.dev/github.com/rekurt/ymsdk

## Возможности

- **Типобезопасные модели** — `ChatID`, `UserLogin`, `MessageID` и другие типы предотвращают ошибки на этапе компиляции
- **Автоматический retry** — экспоненциальный backoff с настраиваемой стратегией повторных попыток
- **Rate limit** — автоматическое соблюдение `Retry-After` заголовков API
- **Сервис-ориентированная архитектура** — отдельные пакеты для сообщений, чатов, опросов, обновлений, файлов и пользователей
- **Polling и Webhooks** — два режима получения обновлений
- **Debug-логирование** — структурированные логи через `zap` с HTTP-инспекцией
- **Минимум зависимостей** — только `go.uber.org/zap`
- **Полное покрытие API** — все основные методы Yandex Messenger Bot API

## Установка

```bash
go get github.com/rekurt/ymsdk
```

## Быстрый старт

### Через агрегатор (рекомендуется)

```go
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/rekurt/ymsdk/client"
	"github.com/rekurt/ymsdk/client/ym"
	"github.com/rekurt/ymsdk/client/ym/ymerrors"
)

func main() {
	cs := client.New(ym.Config{
		Token: os.Getenv("YM_TOKEN"),
		ErrorHandling: ymerrors.ErrorHandlingConfig{
			RetryStrategy:     ymerrors.RetryStrategy{MaxAttempts: 3, RetryNetwork: true},
			RateLimitHandling: ymerrors.RateLimitHandling{UseRetryAfter: true},
		},
	})

	msg, err := cs.Messages.SendToChat(context.Background(), "chat-id", "hello", nil)
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Println("sent message:", msg.ID)
}
```

### Через отдельные сервисы

```go
cl := ym.NewClient(ym.Config{Token: os.Getenv("YM_TOKEN")})
msgSvc := messages.NewService(cl)
pollSvc := polls.NewService(cl)

msg, _ := msgSvc.SendToChat(ctx, "chat-id", "hello", nil)
```

## Архитектура

```
client/
├── sdk.go              # YMClient — агрегатор со всеми сервисами
└── ym/                 # Ядро SDK
    ├── client.go       # HTTP-клиент с retry/rate-limit логикой
    ├── types.go        # Общие типы (Chat, Message, Update, …)
    ├── ptr.go          # Хелпер ym.Ptr[T] для optional-полей
    ├── validate.go     # Общая валидация получателя
    ├── ymerrors/       # Типы ошибок и конфигурация
    ├── messages/       # Текст, файлы, картинки, галереи, удаление, getFile
    ├── chats/          # Создание чатов/каналов, управление участниками
    ├── users/          # Ссылки на чат/звонок пользователя
    ├── polls/          # Опросы: создание, результаты, голоса
    ├── updates/        # getUpdates, GetUpdates и PollLoop
    ├── self/           # Управление webhook_url бота
    └── files/          # Низкоуровневая отправка файлов (byte[])
middleware/             # Логирование через zap
├── logging.go          # LogError, LogUpdateWithRawData, WithRequestID
├── debug.go            # DebugLogger с уровнями (Silent → Debug)
└── http_logger.go      # HTTP-обёртка для логирования request/response
```

## Сервисы

| Сервис | Описание |
|--------|----------|
| `cs.Messages` | Текстовые сообщения, файлы, картинки, галереи, удаление, скачивание файлов |
| `cs.Chats` | Создание чатов/каналов, добавление/удаление участников, подписчиков, админов |
| `cs.Users` | Получение chat_link / call_link по логину |
| `cs.Polls` | Создание опросов, результаты, постраничный список голосов, GetAllVoters |
| `cs.Updates` | getUpdates (raw + typed), PollLoop для непрерывного опроса |
| `cs.Self` | self.update для настройки webhook_url |
| `cs.Files` | Низкоуровневая отправка файлов через byte[] |

Для удобства есть агрегатор `client.YMClient` с уже сконструированными сервисами:
- `client.New(cfg)` — создание с новым HTTP-клиентом
- `client.Wrap(cl)` — обёртка над существующим `ym.Client`

## Обработка ошибок

```go
var apiErr *ymerrors.APIError
if errors.As(err, &apiErr) {
    fmt.Printf("kind=%d http=%d desc=%s request_id=%s\n",
        apiErr.Kind, apiErr.HTTPStatus, apiErr.Description, apiErr.RequestID)

    if errors.Is(err, ymerrors.ErrRateLimited) && apiErr.RetryAfter > 0 {
        time.Sleep(apiErr.RetryAfter)
    }
}
```

- Все API-ошибки — `*ymerrors.APIError`; используйте `errors.As`.
- Rate limit: `errors.Is(err, ymerrors.ErrRateLimited)` + `RetryAfter`.
- Авторизация: `ErrInvalidToken` (403) / `ErrUnauthorized` (401).
- Сетевые: `KindNetwork` (5xx) или `net.Error`, если включён `RetryNetwork`.

## Конфигурация

```go
cfg := ym.Config{
    BaseURL: "",  // по умолчанию production endpoint
    Token:   os.Getenv("YM_TOKEN"),
    ErrorHandling: ymerrors.ErrorHandlingConfig{
        RetryStrategy: ymerrors.RetryStrategy{
            MaxAttempts:    3,               // до 3 попыток
            InitialBackoff: 500 * time.Millisecond,
            MaxBackoff:     10 * time.Second,
            RetryNetwork:   true,            // повторять при сетевых ошибках
            RetryHTTP:      []int{500, 502, 503, 504},
        },
        RateLimitHandling: ymerrors.RateLimitHandling{
            UseRetryAfter:  true,            // уважать Retry-After заголовок
            DefaultBackoff: time.Second,
        },
    },
    UpdatesMode: ymerrors.UpdatesModePolling, // "polling" или "webhook"
}
```

## Debug-логирование

Для отладки HTTP-запросов и ответов используйте middleware:

```go
import (
    "github.com/rekurt/ymsdk/client"
    "github.com/rekurt/ymsdk/client/ym"
    "github.com/rekurt/ymsdk/middleware"
)

logger, _ := zap.NewDevelopmentConfig().Build()
debugLogger := middleware.NewDebugLogger(logger, middleware.LogLevelDebug)
loggedHTTP := middleware.NewHTTPLogger(&http.Client{Timeout: 15 * time.Second}, debugLogger)

ymClient := ym.NewClientWithHTTP(cfg, loggedHTTP)
cs := client.Wrap(ymClient)
```

Подробнее — `middleware/README.md` и `examples/debug_logger`.

## Примеры

| Пример | Описание |
|--------|----------|
| `examples/basic_send` | Отправка текста в чат/логин, reply-to, mark-important, обработка ошибок |
| `examples/poller` | Непрерывный опрос обновлений через PollLoop, обработка типов (текст, файлы, стикеры, пересланные) |
| `examples/poll_bot` | Создание опроса, GetResults, GetAllVoters, чтение обновлений |
| `examples/webhook` | HTTP-приёмник webhook с валидацией секрета, graceful shutdown, echo-бот |
| `examples/debug_logger` | HTTP-логирование запросов/ответов, обработка обновлений без сообщений |
| `examples/integration` | Полный обход всех методов SDK (настройка через env) |

### Запуск примеров

```bash
# Отправка сообщения
cd examples/basic_send
YM_TOKEN=... go run . -chat "chat-id" -text "hello"

# Polling обновлений
cd examples/poller
YM_TOKEN=... go run .

# Опрос-бот
cd examples/poll_bot
YM_TOKEN=... YM_CHAT_ID=... go run .

# Webhook-сервер
cd examples/webhook
YM_TOKEN=... YM_WEBHOOK_SECRET=... YM_PORT=8080 go run .

# Debug-логирование
cd examples/debug_logger
YM_TOKEN=... go run .

# Полная интеграция
cd examples/integration
YM_TOKEN=... YM_CHAT_ID=... YM_LOGIN=... go run .
```

## Версионирование

Проект следует [Semantic Versioning](https://semver.org/). Для установки конкретной версии:

```bash
go get github.com/rekurt/ymsdk@v0.1.0
```

## Тесты

```bash
# Все тесты
go test ./...

# Линтинг (50+ линтеров)
golangci-lint run --config .golangci.yml
```


ymsdk

Event-driven trading framework for Go. Spot, perpetual futures, prediction markets. Multi-exchange (Bybit, Hyperliquid, Polymarket)

The Best Go Libraries For Bot Building (31)

bot

echotron

go-sarah

go-tg

go-twitch-irc

ephemeral-roles

go-chat-bot

go-tgbot

Golang CryptoTrading Bot

govkbot

hanu

Kelp

larry

margelet

slack-bot

olivia

slacker

telebot

slackscot

tbot

telego

wayback

telegram-bot-api

teleterm

Tenyks

micha

arikawa

telegram-bot-api

TG

ymsdk

Wisp