Basic Usage

This page gives an overview of all but the most advanced features of Groupy.

First, you’ll want to make sure that

• Groupy is installed
• Groupy can find your API key

See the Installation page for instructions. Now that that’s out of the way, let’s get started!

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 groupy import Group
>>> group = Group.list().first
>>> group.post('Hello to you')
>>> group.messages().newest.text
'Hello to you'

Note

Posting a message does not affect message_count. However, retrieving any page of messages does update it.

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'

Note

The SHARE_TOKEN is specific to each group’s share link.

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')]

Note

Not every message will have text and not every message will have attachments but every message must have one or the other.

Note

Although the majority of messages will have just one attachment, there is no limit on the number of attachments. In fact, despite that most clients are incapable of displaying more than one of each type of attachment, the API doesn’t limit the types of attachments in any way. For example, a single message might have two images, three locations, and one emoji, but it’s not likely that any client would show them all or handle the message without error.

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

Note

Currently, the message instance itself does not update its own attributes. You must re-fetch the message.

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()

Note

Although many attributes of a member are specific to a particular group, members listed in this fashion are taken from a single group with one exception: the nickname of each member listed from list() is the most frequent of the names that the member uses among the groups of which you are both members.

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!

Note

Keep in mind that bots can only post messages to groups, so if anything else is going to get done, it’ll be done by you, not your bot. That means adding and removing users, liking messages, direct messaging a member, and creating or modifying group will be done under your name.

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.