Getting Started

First, make sure you have:

  • Groupy installed
  • your API key

See the Installation page for help if needed.

The Client

Creating a client

Assuming your API token is stored in token:

>>> from groupy.client import Client
>>> client = Client.from_token(token)

Clients are capable of listing groups, chats, and bots. It can also provide your user information.

Listing groups

Groups are listed in pages. You can specify which page and how many groups per page using the page and per_page parameters. per_page defaults to 10.

>>> client.groups.list()
<groupy.pagers.GroupList at 0x7fcd9f7174e0>
>>> client.groups.list(page=2, per_page=30)
<groupy.pagers.GroupList at 0x7fa02c23db70>

The GroupList returned can be iterated to obtain the groups in that page.

>>> for group in client.groups.list():
...     print(

Since paging can be a pain, the GroupList also possesses an autopage() method that can be used to obtain all groups by automatically handling paging:

>>> groups = client.groups.list()
>>> for group in groups.autopage():
...     print(

However, the easiest way to list all groups, is:

>>> for group in client.groups.list_all():
...     print(


The ordering of groups is determined by most recent activity, so the group with the youngest message will be listed first. For this reason, autopaging is highly recommended when the goal is to list all groups.

Omitting fields

Sometimes, particularly when a group contains hundreds of members, the response is “too large” and contains an incomplete response. In that case, an InvalidJsonError is raised.

To avoid this, use the omit parameter to specify fields to omit.

>>> groups = client.groups.list(omit="memberships")


Multiple fields must be formatted in a CSV (e.g. “memberships,description”). At the time of this writing, however, the API only supports omission of “memberships.”

To refresh a group with fresh data from the server, thus replenishing any missing fields, use refresh_from_server():

>>> group.refresh_from_server()

Listing chats

Listing chats is exactly list listing groups, except that you cannot choose to omit fields.

>>> for chat in client.chats.list_all():
...     print(chat.other_user['name'])

Listing bots

Bots are listed all in one go. That is, the list of bots you own is not paginated.

>>> for bot in client.bots.list():
...     print(

Your own user information

At any time, you can easily access information about your GroupMe user account as a simple dictionary:

>>> fresh_user_data = client.user.get_me()

Since user information does not typically change during the lifetime of a single client instance, the user information is cached the first time it is fetched. You can access the cached user information as a read-only property:

>>> cached_user_data =


In general, if a field is present in an API response, you can access it as an attribute of the resource. For example:

'My cool group'

Some fields are converted to more useful objects for you:

>>> message.created_at
datetime.datetime(2015, 2, 8, 2, 8, 40)


Creating new groups

>>> new_group = client.groups.create(name='My group')

Listing messages from a group

>>> message_page = group.messages.list()
>>> for message in group.messages.list_all():
...     print(message.text)
>>> message_page = group.messages.list_after(message_id=message)


See “Listing messages” for details.

Accessing members of a group

>>> members = group.members

Viewing the leaderboard

>>> daily_best = group.leaderboard.list_day()
>>> weekly_best = group.leaderboard.list_week()
>>> my_best = group.leaderboard.list_for_me()

Destroying a group

>>> if group.destroy():
...     print('Bye bye!')
... else:
...     print('Something went wrong...')


A chat represents a conversation between you and another user.

Listing messages

>>> messages = chat.messages.list()


See the section on messages below for details.


Blocking/Unblocking a member

>>> block = member.block()
>>> member.unblock()

Removing members from groups


Remember, members are specific to the group from which they are obtained.

>>> member.remove()


Creating a message (in a group)

>>> message ='hi')

Liking/Unliking a message

>>> message.unlike()

Listing messages

>>> messages = chat_or_group.messages.list()
>>> oldest_message_in_page = messages[-1]
>>> page_two = chat_or_group.messages.list_before(
>>> all_messages = list(chat_or_group.messages.list().autopage())


Currently, Groupy supports the following types of attachments:

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

The following sections cover the various types of attachments and how to create them. Assume we have already imported the attachments module:

>>> from groupy import attachments


Location attachments are the simplest of all attachment types. Each includes a name, a latitude lat, and a longitude lng. Some location attachments also contain a foursqure_venue_id.

>>> location = attachments.Location(name='Camelot', lat=42, lng=11.2)


Image attachments are unique in that they do not actually contain the image data. Instead, they specify the URL from which you can obtain the actual image. To create a new image from a local file object,

>>> with open('some-image', 'rb') as f:
>>>     image = client.images.from_file(f)

To fetch the actual image bytes of an image attachment, use the client:

>>> image_data =


Mentions are an undocumented type of attachment. However, they are simple to understand. Mentions capture the details necessary to highlight “@” mentions of members in groups. They contain a list of loci and an equal-sized list of user_ids.

Assuming Bob’s user ID is 1234, the mention of Bob in “Hi @Bob!” would be:

>>> mention = attachments.Mentions(loci=[(3, 4)],
...                                user_ids=['1234'])

Each element in loci has two integers, the first of which indicates the starting index of the mentioning text, while second indicates its length. The strings in user_ids correspond by index to the elements in loci. You can use the loci to extract the mentioning portion of the text, as well as obtain the mentioned member via user_ids.

An example with mutiple mentions probably illustrates this better. If Bill (user ID 2345) and Zoe Childs (user ID 6789) are mentioned in “@Bill hey I saw you with @Zoe Childs at the park!’”

>>> mentions = attachments.Mentions(loci=[[0, 5], [25, 11]],
...                                 user_ids=['2345', '6789'])


Emojis are also an undocumented type of attachment, yet frequently appear in messages. Emoji attachments have a placeholder and a charmap. The placeholder is a high-point or unicode character designed to mark the location of the emoji in the text of the message. The charmap serves as some sort of translation or lookup tool for obtaining the actual emoji.



This type of attachment is depreciated. They were part of GroupMe’s bill splitting feature that seems to no longer be implemented in their clients. Groupy, however, still supports them due to their presence in older messages.