Zero to Peribot - ahamlinman/peribot GitHub Wiki

This guide will show you how to create a very simple GroupMe bot using Peribot and Peribot::GroupMe. As part of this, you will learn how to set up and configure a bot. You will also get a very basic introduction to services.

This guide assumes some familiarity with the Ruby programming language, Ruby gems, and Bundler. At the very least, you will need to install Ruby on your system and run gem install bundler.

I welcome suggestions for this tutorial! Please see my GitHub profile for my most up-to-date contact information.

1. Create a new directory to hold the files for your bot. (e.g. mkdir mybot)
2. Create a Gemfile in your bot directory referencing Peribot and Peribot::GroupMe:

   source 'https://rubygems.org'
   
   gem 'peribot', '~> 0.10.0', git: 'https://github.com/ahamlinman/peribot.git'
   gem 'peribot-groupme', '~> 0.10.0', git: 'https://github.com/ahamlinman/peribot-groupme.git'

3. Run bundle install to download the gems required for your bot.

1. Visit https://dev.groupme.com and log in.
2. In the right sidebar, click "Create Application".
3. Fill in all fields. You may use localhost as your callback URL.
4. View your access token under "Your Access Token" on the application information page. (It should be a 32-character hexadecimal string.)

Alternatively, you can follow GroupMe's standard recommendation and click "Access Token" in the top navigation bar to obtain a personal access token. The benefit of this is that you do not need to fill out the full application form. The drawback is that (as far as I know) there is no easy way to revoke or regenerate this token should it become necessary (whereas the token obtained above can be revoked by deleting the application).

Either way, never share your access token! It is functionally equivalent to your GroupMe username and password, and anyone who has it has complete control of your GroupMe account. (This is why I feel more secure knowing that I can revoke it if necessary. It's also why Peribot is open source — so you can see that nothing bad is going on behind your back.)

1. (Optional) Create a new group using the GroupMe app or website. This will prevent you from spamming your existing groups with test messages.
2. On the GroupMe Developers site, click "Bots" in the top navigation bar.
3. Near the top of the page, click "Create Bot".
4. Choose a group as well as a name for the bot within the group. Optionally, provide an avatar URL. You may leave the callback URL blank.
5. Once submitted, notice the "Bot ID" and "Group ID" for your bot. You will not need them for this guide, but you may want them in the future if you do not want Peribot::GroupMe to configure your bots automatically.

Create a new Ruby file (e.g. mybot.rb) containing the following:

require 'bundler/setup'
require 'peribot'
require 'peribot/groupme'

bot = Peribot.new
bot.configure do
  groupme { token '<your access token, obtained above>' }
end

This simple bot uses DSL-style configuration. As you add more features, you may wish to use a YAML configuration file instead. See the Peribot documentation for details.

A service in Peribot receives all messages and can optionally respond to them based on a variety of conditions. The following basic service will cause your bot to send the message "Hello, world!" when you send the message "#hello". Add the following to your Ruby file:

class HelloService < Peribot::Service
  def greet(**)
    'Hello, world!'
  end
  on_command :hello, :greet
end

The greet method above is a handler method. The line on_command :hello, :greet registers this method to be called when your bot receives the "hello" command (i.e. a message starting with "#hello"). Your bot will send the message returned by greet in response.

Handler methods are always called with keyword arguments, which vary based on the type of handler method (greet is a command handler). The double-splat (**) in the parameter list allows us to ignore these keyword arguments. See Building Services to learn more about the types of handler methods provided by Peribot::Service.

Peribot's use method makes it easy to include components in your bot. Add the following to your Ruby file:

bot.use Peribot::GroupMe
bot.use HelloService

The first line sets up your bot to send and receive GroupMe messages. The second line tells your bot to process messages using the service we created above.

While your bot is now ready to process received messages and send replies, it does not currently get anything from GroupMe. Add the following to your Ruby file:

bot.start_groupme_push!

This method was defined on your bot by calling bot.use Peribot::GroupMe above. When called, it will connect to GroupMe's push notification service and send all received messages to your bot for processing. This should be the last line in your script, as this method call will block forever.

Run the Ruby script that you created (e.g. ruby mybot.rb). Note that you should not see any output. Using GroupMe on your phone or computer, open the group that contains the GroupMe bot you created earlier. Send the message "#hello" (without the quotes) to the group.

Soon after sending your message, you should see a reply from the GroupMe bot that you created earlier. If this is the case, you have successfully completed this tutorial! If not, you may wish to examine the output of your script (if any) and double-check it for errors.

• Read Building Services to learn more about services and how to create them.
• Take a look at the documentation for the framework.
• Return to the Home page for a full listing of the wiki's contents.