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

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

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

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

The Best Go Libraries For Bot Building - Libraries for building and working with bots. (15)