Skip to main content
Donate to the Python Software Foundation or Purchase a PyCharm License to Benefit the PSF! Donate Now

A bot platform for automatic responses based on various triggers

Project description

gramhopper

A bot platform for automatic responses based on various triggers.

Install

Using pip

Install the latest version:

$ pip install gramhopper

Using docker

Pull the latest image:

$ docker pull orbin/gramhopper:latest

Configure

Create a bot

  1. Create a bot using 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:

  • Go to @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:

{
  "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:

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:

Run

To run gramhopper, just run:

From installed package

$ gramhopper

From docker image

$ docker run -it -v /your/configuration/dir:/root/.gramhopper orbin/gramhopper:latest

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
gramhopper-1.0.7-py3-none-any.whl (21.1 kB) Copy SHA256 hash SHA256 Wheel py3
gramhopper-1.0.7.tar.gz (13.5 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page