# Boty

`Boty` is a utilitary to create bots (at this time, specificaly Slack bots).

A bot is this context is a ordinary ruby application, that knows how to receive
messages. Boty will give you a nice way to bind your own logic to specific
messages of your own interest.

## Slack Bot Integration<a id="integration" />

The first thing to do is to create a Slack Bot integration.
Go to `http://[your-company-name].slack.com/services` to add a new one.
In the process an `API Token` will be generated. That will be used in the [next
step](#installation).

## Installation<a id="installation" />

Now you can install `Boty`:

```sh
$ gem install boty
```

This will give you an executable `boty`, which ships with a command `help` so
you can know all the stuff that it can do. But the main one is to [create your
new shiny bot](#usage).

## Usage<a id="usage" />

In this section you will learn how to create a custom bot application for your
needs, how to configure it to allow the bot say stuff in your slack channels and
finally, will see how to run the bot properly.

### Creating a new bot

To create a new bot, execute:

```sh
$ boty new jeeba
```

Where `jeeba` will be the nickname you give your bot in the [Slack
integration](#integration).

The command will create a new directory after your bot name (`jeeba` in my
example). Your _bot application_ will live in this directory. Feel free to check
the directory, it will have some ruby files, some directories... it's just an
ordinary ruby application.

But first, let's see something about the [configurations](#configuration).

### Configuration<a id="configuration" />

When executing the `boty new` command, you will be prompted for the
*company name* and the *bot api key*.

The information that you enter will be used only locally, so you can experiment
and test (we will see more about the automated ones in this *README*) while
developing your bot. This will be stored in the `.env.local` file on the
recently created dir.

If you want to understand how this configuration is managed locally, you can
check de [`Dotenv` gem documentation](https://github.com/bkeepers/dotenv), but
you don't need to worry about it.

### Running locally<a id="running" />

After create the new _bot application_ and give the *bot api key*, you can just
enter the new dir and run

```sh
$ ./bot
```

Done! Your bot will be connected to your company Slack through the nickname that
you provided in the [integration](#integration) step.
To see if it's working properly, just go the the slack, in the general channel
(or any other where the bot was invited) and type:

```sh
@jeeba: ping
```

It will respond to you: `pong`. IT'S ALIVE.

### Deploy on heroku

But probably what you want is to have your bot running in a server, not in your
machine, right?

Your bot is created with an example `Procfile` to make it easy to run it on
[Heroku](http://heroku.com) (to give an example).

Create a new project on Heroku, following their instructions, until they ask you
to do the "deploy" (the `git push heroku master`).

#### configure the api key

Now you need to add the configurations that are localy stored on `.env.local`.
The two environment variables on that file are:

    SLACK_COMPANY
    SLACK_BOT_API_TOKEN

The *Heroku* command line tool offers a way to create environment vars in the
server, check
[their documentation](https://devcenter.heroku.com/articles/config-vars).
Today, when as I'm writing the readme, you can use the following commands to set
those two environment variables:

    $ heroku config:set SLACK_COMPANY=your-company-name
    $ heroku config:set SLACK_BOT_API_TOKEN=your-bot-integration-api-token

#### allow process to run

Heroku will not detect a web application in your bot, so you need to tell them
to run your application as a, well... as a "normal" application.
Go to your heroku dashboard (https://dashboard.heroku.com/apps), find the
application that you have created to your bot.
On the tab _Resources_, find a line with the information:

    your-bot-name bundle exec ./bot


Turn on this resource. And done, your bot is up and running!


## Adding custom scripts

 **todo: document**

For now, check the `script/ping.rb` and follow it's leads.

### Describing script usage

A bot list all the commands and message handlers that it knows in the moment. If
you want to give a nice description and/or a usage tip on command you can use
the `desc` method.

Given that your bot has the following script:

```ruby
desc "pug me", "Send some nice pug in the channel."
respond(/pug me/i) do
  # ...
end
```

The follow text will be part of the response for a `@bot: knows` command:

    pug me: Send some nice pug in the channel.

You can use just the description if you want. In this case the `regex` itself
will be used as the command name.

```ruby
desc "Send some nice pug in the channel."
respond(/pug me/i) do
  # ...
end
```

    valeriano 2:25PM
    @bot: knows

    bot 2:25PM
        knows: List all the commands known by this bot.
    /pug me/i: Send some nice pug in the channel.

We strongly recommend that you describe all of your scripts. But if you don't,
the bot will be capable of tell you what `regexes` are binded to it:

    valeriano 2:47PM
    @jabberu: knows

    jabberu 2:47PM
                          knows: List all the commands known by this bot.
                      /pug me/i
    /jabberu, are you there\?/i

### Testing your own scripts

 **todo: document**

For now, check the `spec/script/ping_spec.rb` and follow it's leads.

## Development

After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ricardovaleriano/boty. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.


## License

The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).