Metadata-Version: 2.1
Name: gramhopper
Version: 1.0.5
Summary: A bot platform for automatic responses based on various triggers
Home-page: https://github.com/OrBin/gramhopper
Author: Or Bin, Meir Halachmi
Author-email: orbin50@gmail.com, meir.halachmi@gmail.com
License: MIT
Keywords: gramhopper telegram bot
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Other Audience
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Communications :: Chat
Description-Content-Type: text/markdown
Requires-Dist: python-telegram-bot (==11.1.0)
Requires-Dist: boolean.py (==3.6)
Requires-Dist: ruamel-yaml (==0.15.46)

# gramhopper
A bot platform for automatic responses based on various triggers.

## Install
Install the latest version:

```bash
$ pip install gramhopper
```

## Configure

### Create a bot
1. [Create a bot using BotFather](https://core.telegram.org/bots#6-botfather).
2. Save the received token in `~/.gramphopper/token.txt`.
3. Enable receiving messages from groups for the bot by sending `/setprivacy` to BotFather,
 then select the new bot and click `Disable`. 

### Enable nicknames for user-based rules
To use user nicknames, you have to get the user IDs first.

#### Getting user ID in Telegram
Getting a Telegram user ID can be done using [@userinfobot](https://telegram.me/userinfobot):
* Go to [@userinfobot](https://telegram.me/userinfobot) and press "START". 
    The bot will then print your user ID.
* To get the user ID of another user, just forward a message from this user and the bot will print their user ID. 

#### Mapping nicknames to user IDs
To use user nicknames, `~/.gramphopper/users.json` should contain an object in which the keys 
are nicknames and the values are user IDs, for example:
```json
{
  "nickname1": 123456789,
  "nickname2": 987654321
}
``` 

### Rules configuration
The configuration file is located at `~/.gramphopper/rules.yml`.

Basically, the configuration file has three parts:
* **Global triggers**: triggers that can be used in rules without redefining.
* **Global responses**: responses that can be used in rules without redefining.
* **Rules**: Pairs of triggers and responses, which define together what triggers the bot and how it responds.

#### `rules.yml` example
The following configuration file:
```yaml
triggers:
  - name: cat
    type: text.has_exact_word
    word:
      - Meow
      - meow

  - name: duck
    type: text.has_exact_word
    word: Quack

responses:
  - name: found_dog
    type: preset.reply
    preset_response:
      - Hey, here's a dog!

rules:
  # Identifies a cat (a global "cat" trigger) and sends "Hello cat!" (an inline response).
  - trigger: cat
    response:
      type: preset.message
      preset_response: Hello cat!

  # Identifies a dog (an inline trigger) and replies "Hey, here's a dog!"
  # (a global "found_dog" response).
  - trigger:
      type: text.has_substring
      substring:
        - Woof
        - woof
        - Ruff
        - ruff
    response: found_dog

  # Identifies an animal sound (an inline trigger) and replies 
  # 'I hear "(the animal sound)"' (an inline response), with a 30% probability.
  - trigger:
      type: text.regexp
      pattern: ^(Quack|Meow|Woof|Moo)$
    response:
      type: match.message
      template: I hear "{0}"
    probability: 0.3

  # Identifies 5 occurrences in 60 seconds of a duck sound (an inline event_streak
  # trigger that uses a global "duck" trigger") and replies "Shut up duck!".
  - trigger:
      type: event_streak
      counting_event_trigger: duck
      streak_timeout_sec: 60
      event_count: 5
    response:
      type: preset.message
      preset_response: Shut up duck!
```
will yield the following conversation:

![](https://raw.githubusercontent.com/OrBin/gramhopper/master/demo.gif "Conversation example")


## Run
To run gramhopper, just run:
```bash
$ gramhopper
```


