Skip to main content

A bot platform for automatic responses based on various triggers

Project description


image image image

A bot platform for automatic responses based on various triggers.


Using pip

Install the latest version:

$ pip install gramhopper

Using docker

Pull the latest image:

$ docker pull orbin/gramhopper:latest


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:

  - name: cat
    type: text.has_exact_word
      - Meow
      - meow

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

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

  # Identifies a cat (a global "cat" trigger) and sends "Hello cat!" (an inline response).
  - trigger: cat
      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
        - 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)$
      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
      type: preset.message
      preset_response: Shut up duck!

will yield the following conversation:


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.

Files for gramhopper, version 2.0.1
Filename, size File type Python version Upload date Hashes
Filename, size gramhopper-2.0.1-py3-none-any.whl (23.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size gramhopper-2.0.1.tar.gz (14.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page