Welcome to Groupy!¶

About GroupMe¶

GroupMe is a messaging app that allows you to create groups and have others join them with you. In addition to group messaging, fellow group members can be messaged directly. GroupMe is available for most platforms, lets you share links, images, and locations, and messages can be favorited (or “liked”). You can read more about GroupMe, but the best part about it is that they provide an API!

The GroupMe API is documented, but there are some notable omissions. Many of the properties of groups and messages are not documented, and some features are only hinted at by the documentation. Regardless, all of the information about your groups, their members, their messages, you, and your bots can be obtained through the GroupMe API. You can read the API documentation for more (or less) detailed information.

About Groupy¶

Groupy lets you forget about the GroupMe API and focus on what you need to get done!

It is composed of two main parts:

Prerequisites¶

To get started, you’ll need to get an account at Groupme.com.

Got it? Great!

Now you’ll need to obtain your access token so you can make API requests:

1. Login to the developer portal.
2. Click the “Bots” button on the top menu bar.
3. Click the “Click here to reveal” button.
4. Copy your access token.

You must also create a key file.

1. Paste your access token into a new file.
2. Save it as .groupy.key in your user’s home directory.

Lastly, ensure you’re running Python >= 3! Now you’re ready to install Groupy!

Instructions¶

Below are instructions for various ways of performing installation.

$ pip3 install GroupyAPI

$ git clone https://github.com/rhgrant10/Groupy.git
$ cd Groupy
$ cp -r groupy /usr/lib/python3/dist-packages       # see note above

$ wget https://github.com/rhgrant10/Groupy/archive/master.zip
$ unzip master.zip
$ cd Groupy-master
$ cp -r groupy /usr/lib/python3/dist-packages   # see note above

Troubleshooting¶

Sometimes things go wrong. Here are some common things to check when encountering problems after installing.

It says no such package when I import groupy...

Check whether you copied the groupy package into the correct python package directory. It must be a directory on your sys.path.

I get an unauthorized error when I try to do anything...

Check whether your key file (.groupy.key by default) contains your API token, and that groupy/config.py contains a definition for KEY_LOCATION that correctly specifies the location and name of your key file.

Listing Things¶

The most basic operation is listing things. Groups, Members, and Bots can be listed directly.

>>> import groupy
>>> groups = groupy.Group.list()
>>> members = groupy.Member.list()
>>> bots = groupy.Bot.list()

The object lists are returned as a FilterList. These behave just like the built-in list does with some convenient additions.

You can read more about the types of lists used by Groupy in the Advanced Usage section, but for the remainder of this page, the following truth should suffice.

>>> groups.first == groups[0]
True
>>> groups.last == groups[-1]
True

Groups¶

From a Group, you can list its Members and Messages.

>>> from groupy import Group
>>> groups = Group.list()
>>> group = groups.first
>>> messages = group.messages()
>>> members = group.members()

A group returns all of its members in a single list. So determining the number of members in a group should be a familiar task.

>>> len(members)
5

Messages, however, are a different matter. Since there may be thousands of messages in a group, messages are returned in pages. The default (and maximum) number of messages per page is 100. To determine the total number of messages in a group, simply access the message_count attribute. Additional pages of messages can be obtained using older() and newer().

>>> len(messages)
100
>>> group.message_count
3014
>>> older = messages.older()
>>> newer = messages.newer()

There are also methods for collecting a newer or older page of messages into one list: iolder() and inewer(). An example of using the former to retrieve all messages in a group:

>>> from groupy import Group
>>> group = Group.list().first
>>> messages = group.messages()
>>> while messages.iolder():
...       pass
...
>>> len(messages) == group.message_count
True

Often you’ll want to post a new message to a group. New messages can be posted to a group using its post() method.

>>> from group import Group
>>> group = Group.list().first
>>> group.post('Hello to you')
>>> group.messages().newest.text
'Hello to you'

Groups have many attributes, some of which can be changed.

>>> group.name
'My Family'
>>> group.image_url
'http://i.groupme.com/123456789'
>>> group.description
'Group of my family members - so we can keep up with each other.'
>>> group.update(name="My Group of Family Members")
>>> group.name
'My Group of Family Members'
>>> group.update(name="[old] Family Group", description="The old family group")
>>> group.name
'[old] Family Group'
>>> group.description
'The old family group'

Some Groups also have a share_url that others can visit to join the group.

>>> group.share_url
'https://groupme.com/join_group/1234567890/SHARE_TOKEN'

Beware that not every group is created with a share link, in which case the value of share_url would be None. However, this can be changed in the same way as other group information.

>>> print(group.share_url)
None
>>> group.update(share=True)
>>> group.share_url
'https://groupme.com/join_group/1234567890/SHARE_TOKEN'

The remainder of a Groups attributes cannot be changed. Some of the more important attributes are shown below.

>>> group.group_id
'1234567890'
>>> group.creator_user_id
'0123456789'
>>> print(group.created_at)
2013-12-25 9:53:33
>>> print(group.updated_at)
2013-12-26 4:21:08

Messages¶

Unlike Groups, Members, and Bots, Messages cannot be listed directly. Instead, Messages are listed either from Group or Member instances.

To list the messages from a group, use a group’s messages() method.

>>> from groupy import Group
>>> group = Group.list().first
>>> messages = group.messages()

To list the messages from a member, use a member’s messages() method.

>>> from groupy import Member
>>> member = Member.list().first
>>> messages = member.messages()

Messages have several properties. Let’s look at a few of them. Messages have a timestamp indicating when the message was created as a datetime.datetime instance, as well as information about the member who posted it. Of course, messages can have text and attachments.

>>> message = messages.newest
>>> print(message.created_at)
2014-4-29 12:19:05
>>> message.user_id
'0123456789'
>>> message.name
'Kevin'
>>> message.avatar_url
'http://i.groupme.com/123456789'
>>> message.text
'Hello'
>>> message.attachments
[Image(url='http://i.groupme.com/123456789')]

There are multiple types of messages. System messages are messages that are not sent by a member, but generated by member actions. Many things generate system messages, including membership changes (entering/leaving, adding/removing), group updates (name, avatar, etc.), and member updates (nickname, avatar, etc.), and changing the topic.

Additionally there are group messages and direct messages. Group messages are messages in a group, whereas direct messages are messages between two members.

Each message has a few properties that can be used to differentiate among the types.

>>> message.group_id
'1234567890'
>>> message.recipient_id
None
>>> message.system
False

In the above example, we can see that message.system is False, which indicates that the message was sent by a member, not the system. We can also see that although the message has a message.group_id, it does not have a message.recipient_id, which means it is a group message. Had it been a system message, message.system would have been True. Had it been a direct message, message.group_id would have been None and message.recipient_id would contain a valid user ID.

Lastly, each message contains a list of user IDs to indicate which members have “liked” it.

>>> message.favorited_by
['2345678901', '3456789012']

Because often more information about the member is desired, a list of actual Member instances can be retrieved using the likes() method.

>>> message.likes()
[Rob, Jennifer, Vlad]

Messages can also be liked and unliked.

>>> message.like()
True
>>> message.unlike()
True

Members¶

Member instances represent other GroupMe users. Finding members can be accomplished in one of three ways.

Firstly, members may be listed from a group. This lists just the members of a particular group.

>>> from groupy import Group
>>> group = Group.list().first
>>> members = group.members()

Secondly, members may be listed from a message. This lists just the members who have “liked” a particular message.

>>> messages = group.messages()
>>> message = message.newest
>>> members = message.likes()

Lastly, all the members you’ve seen thus far can be listed directly.

>>> from groupy import Member
>>> members = Member.list()

Each member has a user ID, a nickname, and a URL indicating their avatar image that are specific to the group from which the member was listed.

>>> member = members.first
>>> member.user_id
'0123456789'
>>> member.nickname
'Bill'
>>> member.avatar_url
'http://i.groupme.com/123456789'

Members have one more property of interest: muted. This indicates whether the member has that group muted.

>>> member1, member2 = members[:2]
>>> member1.muted
False
>>> member2.muted
True

Messaging a member and retrieving the messages between you and the member is done in the same way as when messaging a group.

>>> member.post("Hello")
>>> member.messages().newest.text
'Hello'

Groups and Members¶

Members can be added and removed from groups. Adding one or multiple members to a group is quite intuitive. The following examples assume that no one from group1 is a member of group2 (although the API doesn’t care if you add a member who is already a member).

>>> from groupy import Group
>>> group1, group2 = Group.list()[:2]
>>> member = group1.members().first
>>> group2.add(member)

Multiple members can be added simultaneously as well. Suppose you wanted to add everyone from group1 to group2.

>>> group2.add(*group1.members())

Removing members, however, must be done one at a time:

>>> for m in group2.members():
...   group2.remove(m)
...

GroupMe and You¶

One of the most basic pieces of information you’ll want to obtain is your own! Groupy makes this very simple:

>>> from groupy import User
>>> your_info = User.get()

It contains your GroupMe profile/account information and settings:

>>> print(your_info.user_id)
12345678
>>> print(your_info.name)
Billy Bob <-- the MAN!
>>> print(your_info.image_url)
http://i.groupme.com/123456789
>>> print(your_info.sms)
False
>>> print(your_info.phone_number)
+1 5055555555
>>> print(your_info.email)
bb@example.com

It also contains some meta information:

>>> print(your_info.created_at)
2011-3-14 14:11:12
>>> print(your_info.updated_at)
2013-4-20 6:58:26

created_at and updated_at are returned as datetime objects.

Bots¶

Bots can be a useful tool because each has a callback URL to which every message in the group is POSTed. This allows your bot the chance to do... well, something (whatever that may be) in response to every message!

Bot creation is simple. You’ll need to give the bot a name and associate it with a specific group.

>>> from groupy import Bot, Group
>>> group = Group.list().first
>>> bot = Bot.create('R2D2', group)

bot is now the newly created bot and is ready to be used. If you want, you can also specify a callback URL (recommended), as well as an image URL to be used for the bot’s avatar.

Just about the only thing a bot can do is post a message to a group. Groupy makes it easy:

>>> from group import Bot
>>> bot = Bot.list().first
>>> bot.post("I'm a bot!")

Note that the bot always posts its messages to the group in which it belongs. You can create multiple bots. Listing all of your bots is straightforward.

>>> from groupy import Bot
>>> bots = Bot.list()

Now bots contains a list of all of your bots.

Filter Lists¶

FilterLists are exactly like the built-in list but with some convenient additions.

>>> from groupy.object.listers import FilterList
>>> fl = FilterList(range(1, 11))
>>> fl
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> fl.first
1
>>> fl.last
10

>>> fl = FilterList()
>>> fl
[]
>>> print(fl.first)
None
>>> fl[0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: list index out of range
>>> print(fl.last)
None
>>> fl[-1]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: list index out of range

>>> from groupy import Group
>>> groups = Group.list()
>>> for g in groups:
...     print(g.name)
...
My Family
DevTeam #6
Friday Night Trivia
>>> for g in groups.filter(name__contains='am'):
...     print(g.name)
My Family
DevTeam #6
>>>
>>> members = groups.first.members()
>>> for m in members:
...     print(m.nickname)
...
Dan the Man
Manuel
Fred
Dan
>>> for m in members.filter(nickname='Dan'):
...     print(m.nickname)
...
Dan
>>> for m in members.filter(nickname__contains='Dan'):
...     print(m.nickname)
...
Dan the Man
Dan
>>> for m in members.filter(nickname__ge='F'):
...     print(m.nickname)
...
Manuel
Fred

Attachments¶

Attachments are a common part of Messages and there are several different types. Currently, Groupy supports the following types of attachments:

• Location - for locations
• Image - for images
• Mentions - for “@” mentions
• Emoji - for emoticons
• Split - for splitting bills[*]

For all other types of attachments (such as those introduced in the future) there exists a GenericAttachment.

>>> from groupy import attachments
>>> loc = attachments.Location('My house', lat=34, lng=-84)
>>> loc
Location('My house', lat=34, lng=-84)
>>> loc.name
'My house'
>>> loc.lat, loc.lng
(34, -84)

>>> from groupy import attachments
>>> image_attachment = attachments.Image.file(open(filename, 'rb'))
>>> image_attachment
Image(url='http://i.groupme.com/123456789')
>>> image_attachment.url
'http://i.groupme.com/123456789'

>>> image_file = image_attachment.download()
>>> image_file.save(filename)

>>> from groupy import Group
>>> message = None
>>> mention = None
>>> for g in Group.list():
...   for m in g.messages():
...     for a in m.attachments:
...       if a.type == 'mentions' and len(a.user_ids) > 1:
...         message = m
...         mention = a
...         break
>>> message.text
'@Bill hey I saw you with @Zoe Childs at the park!'
>>> mention.user_ids
['1234567', '5671234']
>>> mention.loci
[[0, 5], [25, 11]]

>>> for uid, (start, length) in zip(mention.user_ids, mention.loci):
...   end = start + length
...   uid, message.text[start:end]
...   member = message.group.members().filter(user_id=uid).first
...   member.uid, member.nickname
('1234567', '@Bill')
('1234567', 'Bill')
('5671234', '@Zoe Childs')
('5671234', 'Zoe Childs')

>>> from groupy.attachments import Mentions
>>> Mentions(['1234567', '2345671'], [[0, 4], [5, 3]])
Mentions(['1234567', '2345671'])

>>> from groupy import Group
>>> from groupy.attachment import Location
>>> loc = Location.create('My house', lat=33, lng=-84)
>>> group = Group.list().first
>>> group.post("Hey meet me here", loc)

>>> from groupy.attachment import Image
>>> img = Image.file('front-door.png')
>>> group.post("I said meet me here!", loc, img)

>>> attachments = [img, loc]
>>> group.post("Are you listening?", *attachments)

The api Package¶

The object Package¶

The config Module¶

v0.5.3 (September 19, 2014)¶

• Fix packaging bug that caused inner packages to not be installed via pip3

v0.5.2 (September 14, 2014)¶

• Now installable via pip3:

  $ pip3 install GroupyAPI
  

v0.5.1 (August 25, 2014)¶

Groups

• Added a class method for creating a new group
• Added an instance method for destroying a group

Members

• Fixed member identification on dictionaries

User

• Fixed the enable/disable SMS methods (now class methods as they should be)

Documentation

• Added some module docstrings
• Added API docs for all attachment classes
• Added docs for split attachments
• Moved FilterList docs into the Advanced Usage section
• Rewrote API docs for enabling SMS mode
• Fixed bad sphinx references
• Fixed typos
• Added miscellaneous sections to the README
• Updated feature list

v0.5.0 (August 20, 2014)¶

• Added support for downloaded the image of an image attachment
• Reorganized modules and project structure
• Updated documentation

v0.4.0 (August 18, 2014)¶

• Added ability to list all known members
• Re-wrote attachments classes

v0.3.1 (August 14, 2014)¶

• Fixed bug when adding members to a group
• Many additions to the documentation

v0.3.0 (August 12, 2014)¶

• Added post and messages methods to members
• Added after_id parameter for direct messages
• Fixed liking and unliking direct messages
• Fixed listing former groups
• Fixed group lists being limited to a max of 500 items
• Documentation now available on Read the Docs!

v0.2.0 (August 11, 2014)¶

• Added MessagePager class for returning lists of messages

v0.1.3 (August 10, 2014)¶

• Added attachment class
• Added basic documentation
• Fixed the automatic splitting of long texts
• Fixed invalid response error issue

v0.1.0 (August 9, 2014)¶

• Initial release