jetsetdoritos / extbot

A GroupMe bot for providing like and kick stats, as well as random images or basic group information.

ExtBot

Description

A GroupMe bot written in Python that uses GroupMe's REST API to provide like and kick stats, as well as posting random images. Messages are stored using SQLite. Only image/video URLs are saved rather than the actual media to use minimal space. Ext is short for Extras :)

This has only been tested in Python 3.7

Features

• Return Like and Kick data for users
• Rank users in order of likes and return a leaderboard
• Return a random image previously posted, either from all time or specific year
• Return group metadata such as total messages, group creator, and date created
• Hourly refresh of message data
• Tested in a 7 year old group with over 100 partitipants and over 250k messages.

Setup

0. Install required python libraries in requirements.txt (schedule, requests)

1. In the data folder, create a copy or rename the example config file to config.json

2. Sign into dev.groupme.com with your GroupMe account

3. In the "Bots" tab create a bot in your group, set your callback url with the IP:port you will be hosting the bot on, also a name and optional photo

4. Copy the Bot ID and Group ID into the config file, also set the listening port

5. At the top of the dev.groupme.com page click "Access Token" and copy it to the config file

6. Run rebuild_database.py to create the local database of your groups messages (this may take some time! downloading 250k messages takes around 30 minutes!)

7. Edit the config file as you see fit, though the default settings are what worked best in my group.

8. Run run.py to start the bot :)

NOTE: you may need to rerun rebuild_database every once in a great while, messages older than the "refresh_days" will not be seen, but this should be very marginal.

Config File

bot_id : Your bot id from dev.groupme.com bots tab

listening_port : The port you are hosting the bot on

api_key : your api key from dev.groupme.com

group_id : the group id the bot is in from dev.groupme.com bots tab

disable_image : enable/disable the !image function

like_threshold : when !image is ran, this is the minimim number of likes for the image it picks

year_like_threshold : when !image [year] is ran, this is the minimim number of likes for the image it picks

limit_image : limit !image to one per day per user (this prevents so much spam)

refresh_days : the bot refreshes messages every hour, this is the amount of days back it checks,refreshing too many messages can use a lot of API calls and take much longer, though there is no documented API limit my calls started failing around ~2,500 within one hour, this days limit reduces the API calls to less than a dozen per hour usually

Bot Usage

Command	Function
!image	Post a random image previously posted in the chat, along with the original poster and message text
!image [year]	!image, randomly picks from a specified year, ignores the year if there are no posts for that year
!likes	Posts the total number of likes and rank for that user
!likes [tag user]	Posts the total number of likes and rank for the tagged user
!rank	Posts a leaderboard of the top 12 users in terms of likes
!kicks	Posts the total number of times kicked/times kicker for that user, might not be intresting for Locked groups as only the owner can kick
!kicks [tag user]	Posts the total number of times kicked/times kicker for the tagged user, might not be intresting for Locked groups as only the owner can kick
!info	Posts group info such as total number of messages, group creation date, group creator, and minimum likes for image from the config file

Screenshots

!info

!likes

!rank

!kicks

!image

Other Notes

• You can not DM bots, but GroupMe has a sort of bug in its app (possibly just on Android). If you view an image posted by a bot, you are able to tap the profile and there is an option to DM the bot or add to another group. This actually just DMs or adds a user with the same user ID as the bot's ID.

• This project was made possible by Chomps Bot and GroupMe Analytics, which were used to learn GroupMe's bot and application APIs accordingly.

Adding Functions

I'll document how to add your own functionality later

extbot's Issues

More frequent refresh

perhaps 15 minutes, API requests are much lower now per redresh

Consider listing this bot on MeBots to expose it to a wider audience

Hey Mason! Hope you're doing well.

I recently launched an "App Store" of sorts for GroupMe bots, which you can check out at https://mebots.io. Like you, I built a GroupMe bot as a fun project, but became frustrated with the limitations of GroupMe's bot infrastructure. As you know, GroupMe has no straightforward way to run a bot in multiple groups. The simple system of maintaining a constant bot ID seriously limits how useful GroupMe bots can be, and leaves GroupMe lagging behind other platforms like Discord in this area.

So, I developed the bot management and indexing system GroupMe has been missing (and massively upgraded it in recent weeks). MeBots acts as a middleman to the GroupMe API and injects extra fields into the message POST sent from GroupMe, i.e. the bot ID and user token that can be used in the group where the message was sent. All you need is to register your bot and tweak your code to use the received bot ID and token rather than constants. With this minor tweak, anyone could go to https://mebots.io/bot/extbot and click just a couple buttons to add the bot to their own groups.

I would love to see your work on MeBots, which would no doubt expose your great work to more people! One of my bots that I created as a joke several years ago blew up once I launched it on MeBots and now has over 225 groups and thousands of people using it—I wouldn't be surprised if the same happened to yours, since it's a fairly versatile and publicly appealing bot. I am happy to help with the integration process and anything else that would be useful. Just let me know.

Appreciate the consideration, and have a great week! :)

Consider using MeBots to allow users to add this bot to chats automatically

Hey there! I'm Erik, a developer of another Python GroupMe bot. Motivated by frustration I experienced with building that bot, I recently developed MeBots, which is a platform/API for building GroupMe bots more easily. It's designed to abstract away some of the headaches of maintaining GroupMe bots so that your job as a developer will be a little easier. For example, it has a whole built-in panel for adding and removing bots from different groups, and then it stores all the bot IDs and stuff in a database for you so you won't need to worry about keeping track of that data; you can just get what you need through a web API. Also, other people can add the bot to their own groups if you so choose. I think your bot could be of available to more people if it's on that marketplace and can be easily added by non-technical users. That way, anyone who wants XKCD in their chats could simply click a couple buttons and it'd be added to their chats too! No need to deploy to Heroku again as one instance would handle every chat.

I've written up some documentation for how to integrate with the API here: http://mebots.co/documentation. This would not be a complex change: each time a message was sent to a chat, there would just be one simple API request to check which bot_id to send with, and the website takes care of all the adding/removing logic for you!

I wrote some more specific documentation in the README of a pip package I made for easy integration with the API, which you can find here, and there's a complete bot implementation here! I'm happy to make a PR integrating with the platform as well or answer any questions you may have about tradeoffs.

database rebuilld is broken (new setups)

Rank change alerts

for if any users ranks change after a refresh