Developer Docs

This section of the documentation is for other developers, and contains the complete information about each package, module, class, and method.

The api Package

This module is a direct wrapper around GroupMe API calls.

The api.endpoint Module

This module contains classes that represent the many endpoints in the GroupMe API.

class groupy.api.endpoint.Bots

Endpoint for the bots API.

Bots can be listed, created, updated, and destroyed. Bots can also post messages to groups.

classmethod create(name, group_id, avatar_url=None, callback_url=None)

Create a new bot.

Parameters:

• name (str) – the name of the bot
• group_id (str) – the ID of the group to which the bot will belong
• avatar_url (str) – the GroupMe image URL for the bot’s avatar
• callback_url (str) – the callback URL for the bot

Returns:

the new bot

Return type:

dict

classmethod destroy(bot_id)

Destroy a bot.

Parameters:bot_id (str) – the ID of the bot to destroy

classmethod index()

List bots.

Returns:a list of bots Return type:list

classmethod post(bot_id, text, *attachments, picture_url=None)

Post a message to a group as a bot.

Parameters:

• bot_id (str) – the ID of the bot
• text (str) – the message text
• picture_url (str) – the GroupMe image URL for a picture
• attachments (list) – a list of attachments to include

Returns:

the created message

Return type:

dict

class groupy.api.endpoint.DirectMessages

Endpoint for the direct message API.

classmethod create(recipient_id, text, *attachments)

Create a direct message to a recipient user.

Parameters:

• recipient_id (str) – the ID of the recipient
• text (str) – the message text
• attachments (list) – a list of attachments to include

Returns:

the created direct message

Return type:

dict

classmethod index(other_user_id, before_id=None, since_id=None, after_id=None)

List the direct messages with another user.

Parameters:

• other_user_id (str) – the ID of the other party
• before_id (str) – a reference message ID; specify this to list messages prior to it

Returns:

a list of direct messages

Return type:

list

class groupy.api.endpoint.Endpoint

An API endpoint capable of building a url and extracting data from the response.

This class serves as the base class for all of the API endpoints.

classmethod build_url(path=None, *args)

Build and return a url extended by path and filled in with args.

Parameters:

• path (str) – a suffix for the final URL. If args are present, this should be a python format string pertaining to the given args.
• args (list) – a list of arguments for the format string path.

Returns:

a complete URL

Return type:

str

static clamp(value, lower, upper)

Utility method for clamping a value between a lower and an upper value.

Parameters:

• value – the value to clamp
• lower – the “smallest” possible value
• upper – the “largest” possible value

Returns:

value such that lower <= value <= upper

classmethod response(r)

Extract the data from the API response r.

This method essentially strips the actual response of the envelope while raising an ApiError if it contains one or more errors.

Parameters:r (requests.Response) – the HTTP response from an API call Returns:API response data Return type:json

class groupy.api.endpoint.Groups

Endpoint for the groups API.

Groups can be listed, loaded, created, updated, and destroyed.

classmethod create(name, description=None, image_url=None, share=True)

Create a new group.

Parameters:

• name (str) – the name of the new group
• description (str) – the description of the new group
• image_url (str) – the group avatar image as a GroupMe image URL
• share (bool) – whether to generate a join link for the group

Returns:

the new group

Return type:

dict

classmethod destroy(group_id)

Destroy (or leave) a group.

Note

If you are not the owner of a group, you cannot destroy it.

Parameters:group_id (str) – the ID of the group to destroy/leave Return type:dict

classmethod index(page=1, per_page=500, former=False)

Return a list of groups.

Parameters:

• page (int) – the page of groups to return
• per_page (int) – the number of groups in the page
• former (bool) – whether to list former groups instead

Returns:

a list of groups

Return type:

list

classmethod show(group_id)

Return a specific group by its group_id.

Parameters:group_id (str) – the ID of the group to show. Returns:the group with the given group_id Return type:dict

classmethod update(group_id, name=None, description=None, share=None, image_url=None)

Update the information for a group.

Parameters:

• group_id (str) – the ID of the group to update
• name (str) – the new name of the group
• description (str) – the new description of the group
• share (bool) – whether to generate a join link for the group
• image_url (str) – the GroupMe image URL for the new group avatar.

Returns:

the modified group

Return type:

dict

class groupy.api.endpoint.Images

Endpoint for the image service API.

GroupMe images are created through an upload service that returns a URL at which it can be accessed.

classmethod create(image)

Submit a new image.

Parameters:image (file) – object with a file-like interface and containing an image Returns:the URL at which the image can be accessed Return type:dict

classmethod response(r)

Extract the data from the image service API response r.

This method basically returns the inner “payload.”

Parameters:r (requests.Response) – the HTTP response from an API call Returns:API response data Return type:json

class groupy.api.endpoint.Likes

Endpoint for the likes API.

Likes can be created or destroyed.

Note

The conversation_id is poorly documented. For messages in a group, it corresponds to the group_id (or id since they seem to always be identical). For direct messages, it corresponds to the user_id of both conversation participants sorted lexicographically and concatenated with a plus sign (“+”).

classmethod create(conversation_id, message_id)

Like a message.

Parameters:

• conversation_id (str) – the ID of the group or recipient
• message_id (str) – the ID of the message

classmethod destroy(conversation_id, message_id)

Unlike a message.

Parameters:

• conversation_id (str) – the ID of the group or recipient
• message_id (str) – the ID of the message

class groupy.api.endpoint.Members

Endpoint for the members API.

Members can be added and removed from a group, and the results of adding members can be obtained.

classmethod add(group_id, *members)

Add one or more members to a group.

Parameters:

• group_id (str) – the ID of the group to which the members should be added
• members (list) – the members to add.

Returns:

the results ID for this request

Return type:

dict

classmethod remove(group_id, member_id)

Remove a member from a group.

Parameters:

• group_id (str) – the ID of the group from which the member should be removed
• member_id (str) – the ID of the member to remove

classmethod results(group_id, result_id)

Check the result of adding one or more members.

Parameters:

• group_id (str) – the ID of the group to which the add call was made
• result_id (str) – the GUID returned by the add call

Returns:

the successfully added members

Return type:

list

class groupy.api.endpoint.Messages

Endpoint for the messages API.

Messages can be listed and created.

classmethod create(group_id, text, *attachments)

Create a new message in a group.

All messages must have either text or one attachment. Note that while the API provides for an unlimited number of attachments, most clients can only handle one of each attachment type (location, image, split, or emoji).

Parameters:

• group_id (str) – the ID of the group in which to create the message
• text (str) – the text of the message
• attachments (list) – a list of attachments to include

Returns:

the created message

Return type:

dict

classmethod index(group_id, before_id=None, since_id=None, after_id=None, limit=100)

List the messages from a group.

Listing messages gives the most recent 100 by default. Additional messages can be obtained by specifying a reference message, thereby facilitating paging through messages.

Use before_id and after_id to “page” through messages. since_id is odd in that it returns the most recent messages since the reference message, which means there may be messages missing between the reference message and the oldest message in the returned list of messages.

Note

Only one of before_id, after_id, or since_id can be specified in a single call.

Parameters:

• group_id (str) – the ID of the group from which to list messages
• before_id (str) – a reference message ID; specify this to list messages just prior to it
• since_id (str) – a reference message ID; specify this to list the most recent messages after it (not the messages right after the reference message)
• after_id (str) – a reference message ID; specifying this will return the messages just after the reference message
• limit (int) – a limit on the number of messages returned (between 1 and 100 inclusive)

Returns:

a dict containing count and messages

Return type:

dict

Raises:

ValueError – if more than one of before_id, after_id or since_id are specified

class groupy.api.endpoint.Sms

Endpoint for the SMS API.

SMS mode can be enabled or disabled.

classmethod create(duration=4, registration_id=None)

Enable SMS mode.

Parameters:

• duration (int) – duration of SMS mode in hours (max of 48)
• registration_id (str) – the push registration_id or token to suppress (if omitted, SMS and push notifications will both be enabled)

classmethod delete()

Disable SMS mode.

class groupy.api.endpoint.Users

Endpoint for the users API.

classmethod me()

Get the user’s information.

Returns:the user’s information Return type:dict

The api.errors Module

The error module contains all of the exceptions thrown by the GroupMe API.

exception groupy.api.errors.ApiError

Error raised when errors are returned in a GroupMe response.

exception groupy.api.errors.GroupMeError

A general GroupMe error.

All exceptions raised by Groupy are descendents of this exception.

exception groupy.api.errors.InvalidOperatorError

Error thrown when an unsupported filter is used.

The api.status Module

The status module contains API response status code constants and a method that returns the textual description of such a constant.

groupy.api.status.OK = 200

Success

groupy.api.status.CREATED = 201

Resource was created successfully

groupy.api.status.NO_CONTENT = 204

Resource was deleted successfully

groupy.api.status.NOT_MODIFIED = 304

There was no new data to return

groupy.api.status.BAD_REQUEST = 400

Invalid format or invalid data is specified in the request

groupy.api.status.UNAUTHORIZED = 401

Authentication credentials were missing or incorrect

groupy.api.status.FORBIDDEN = 403

The request was understood, but it has been refused

groupy.api.status.NOT_FOUND = 404

The URI requested is invalid or the requested resource does not exist

groupy.api.status.ENHANCE_YOUR_CLAIM = 420

You are being rate limited

groupy.api.status.INTERNAL_SERVER_ERROR = 500

Something unexpected occurred

groupy.api.status.BAD_GATEWAY = 502

GroupMe is down or being upgraded

groupy.api.status.SERVICE_UNAVAILABLE = 503

The GroupMe servers are up but overloaded with requests

groupy.api.status.description(code)

Return the text description for a code.

Parameters:code (int) – the HTTP status code Returns:the text description for the status code Return type:str

The object Package

This module abstracts the objects returned by GroupMe API calls.

The object.responses Module

This module contains classes that encapsulate the information returned in API responses.

class groupy.object.responses.Recipient(endpoint, mkey, idkey, **kwargs)

Base class for Group and Member.

Recipients can post and receive messages.

Parameters:

• endpoint (Endpoint) – the API endpoint for messages
• mkey (str) – the dict key under which the endpoint returns messages
• idkey (str) – the dict key whose value represents the key for posting and retrieving messages

messages(before=None, since=None, after=None, limit=None)

Return a page of messages from the recipient.

Note

Only one of before, after, or since can be specified in a single call.

Parameters:

• before (str) – a reference message ID
• since (str) – a reference message ID
• after (str) – a reference message ID
• limit (int) – maximum number of messages to include in the page

Returns:

a page of messages

Return type:

MessagePager

Raises:

ValueError – if more than one of before, after or since are specified

post(text, *attachments)

Post a message to the recipient.

Although the API limits messages to 1000 characters, this method will split the text component into as many as necessary and include the attachments in the final message. Note that a list of messages sent is always returned, even if it contains only one element.

Parameters:

• text (str) – the message text
• attachments (list) – the attachments to include

Returns:

a list of raw API responses (sorry!)

Return type:

list

class groupy.object.responses.Group(**kwargs)

A GroupMe group.

add(*members, refresh=False)

Add a member to a group.

Each member can be either an instance of Member or a dict containing nickname and one of email, phone_number, or user_id.

Parameters:

• members (list) – members to add to the group
• refresh (bool) – True if the group information should be automatically refreshed from the API, False by default

Returns:

the results ID of the add call

Return type:

str

classmethod create(name, description=None, image_url=None, share=True)

Create a new group.

Parameters:

• name (str) – the group name
• description (str) – the group description
• image_url (str) – the GroupMe image service URL for a group avatar
• share (bool) – whether to generate a join link

Returns:

the newly created group

Return type:

Group

destroy()

Disband (destroy) a group that you created.

If unsuccessful, this raises an ApiError

Returns:OK

classmethod list(former=False)

List all of your current or former groups.

Parameters:former (bool) – True if former groups should be listed, False (default) lists current groups Returns:a list of groups Return type:FilterList

members()

Return a list of the members in the group.

Returns:the members of the group Return type:FilterList

refresh()

Refresh the group information from the API.

remove(member, refresh=False)

Remove a member from the group.

Note

The group must contain the member to be removed. This will not be the case if the group information has not been requested since the member was added. When in doubt, use the refresh() method to update the internal list of members before attempting to remove them.

Parameters:

• member (Member) – the member to remove
• refresh (bool) – True if the group information should be automatically refreshed from the API, False by default

Returns:

True if successful

Return type:

bool

Raises:

groupy.api.errors.ApiError – if removal is not successful

update(name=None, description=None, image_url=None, share=None)

Change group information.

Parameters:

• name (str) – the new name of the group
• description (str) – the new description of the group
• image_url (str) – the URL for the new group image
• share (bool) – whether to generate a share URL

class groupy.object.responses.Member(**kwargs)

A GroupMe member.

identification()

Return the identification of the member.

A member is identified by their nickname and user_id properties. If the member does not yet have a GUID, a new one is created and assigned to them (and is returned alongside the nickname and user_id properties).

Returns:the nickname, user_id, and guid of the member Return type:dict

classmethod identify(member)

Return or create an identification for a member.

Member identification is required for adding them to groups. If member is a dict, it must contain the following keys:

• nickname
• user_id or email or phone_number

If an identification cannot be created then raise an ValueError.

Parameters:member – either a Member or a dict with the required keys Returns:the identification of member Return type:dict Raises:ValueError – if an identification cannot be made

classmethod list()

List all known members regardless of group membership.

Returns:a list of all known members Return type:FilterList

class groupy.object.responses.Message(recipient, **kwargs)

A GroupMe message.

Parameters:recipient (Recipient) – the reciever of the message

is_from_me()

Return True if the message was sent by you.

Return type:bool

is_liked_by_me()

Return True if the message was liked by you.

Return type:bool

like()

Like the message.

Returns:True if successful Return type:bool Raises:groupy.api.errors.ApiError – if unsuccessful

likes()

Return a FilterList of the members that like the message.

Returns:a list of the members who “liked” this message Return type:FilterList

mentions_me()

Return True if the message “@” mentions you.

Return type:bool

recipient

Return the source of the message.

If the message is a direct message, this returns a member. Otherwise, it returns a group.

Returns:the source of the message Return type:Recipient

unlike()

Unlike the message.

Returns:True if successful Return type:bool Raises:groupy.api.errors.ApiError – if unsuccessful

class groupy.object.responses.Bot(**kwargs)

A GroupMe bot.

Each bot belongs to a single group. Messages posted by the bot are always posted to the group to which the bot belongs.

classmethod create(name, group, avatar_url=None, callback_url=None)

Create a new bot.

Parameters:

• name (str) – the name of the bot
• group (Group) – the group to which the bot will belong
• avatar_url (str) – the URL for a GroupMe image to be used as the bot’s avatar
• callback_url (str) – the URL to which each group message will be POSTed

Returns:

the new bot

Return type:

Bot

destroy()

Destroy the bot.

Returns:True if successful Return type:bool Raises:groupy.api.errors.ApiError – if unsuccessful

classmethod list()

Return a list of your bots.

Returns:a list of your bots Return type:FilterList

post(text, *attachments, picture_url=None)

Post a message to the group of the bot.

Parameters:

• text (str) – the message text
• picture_url (str) – the GroupMe image URL for an image
• attachments (list) – the attachments to include

Returns:

True if successful

Return type:

bool

Raises:

groupy.api.errors.ApiError – if unsuccessful

class groupy.object.responses.User(**kwargs)

A GroupMe user.

This is you, as determined by your API key.

classmethod disable_sms()

Disable SMS mode.

Disabling SMS mode causes push notifications to resume and SMS text messages to be discontinued.

Returns:True if successful Return type:bool Raises:groupy.api.errors.ApiError – if unsuccessful

classmethod enable_sms(duration=4, registration_token=None)

Enable SMS mode.

Each client has a unique registration token that allows it to recieve push notifications. Enabling SMS mode causes GroupMe to suppress those push notification and send SMS text messages instead for a number of hours no greater than 48.

Note

If the registration_token is omitted, no push notifications will be suppressed and the user will recieve both text messages and push notifications.

Parameters:

• duration (int) – the number of hours for which to send text messages
• registration_token (str) – the push notification token for which messages should be suppressed

Returns:

True if successful

Return type:

bool

Raises:

groupy.api.errors.ApiError – if unsuccessful

classmethod get()

Return your user information.

Returns:your user information Return type:dict

nickname

Your user name.

The object.attachments Module

This module contains classes for the different types of attachments.

class groupy.object.attachments.Attachment(type_)

Base class for attachments.

Parameters:type (str) – the type of the attachment

as_dict()

Return the attachment as a dictionary.

Returns:the attachment as a dictionary Return type:dict

class groupy.object.attachments.AttachmentFactory

A factory for creating attachments from dictionaries.

classmethod create(**kwargs)

Create and return an attachment.

Parameters:type (str) – the type of attachment to create; if unrecognized, a generic attachment is returned Returns:a subclass of Attachment

class groupy.object.attachments.Emoji(placeholder, charmap)

An attachment containing emoticons.

Emoji attachments do not contain any emoticon images. Instead, a placeholder specifies the location of the emoticon in the text, and a charmap facilitates translation into the emoticons.

Parameters:

• placeholder (str) – a high-point/invisible character indicating the position of the emoticon
• charmap (list) – a list of lists containing pack IDs and offsets

class groupy.object.attachments.GenericAttachment(type, **kwargs)

A generic attachment.

This attachment accepts any keyword arguments, but must be given a particular type.

Parameters:type (str) – the type of attachment

class groupy.object.attachments.Image(url, source_url=None)

An image attachemnt.

Image attachments do not contain an image. Instead, they specify a URL from which the image can be downloaded and must have a domain of “i.groupme.com”. Such URLs are known as “i” URLs, and are from the GroupMe image service.

Note

Use the direct initializer if and only if the image already has a known GroupMe image service URL. Otherwise, use the file() method.

Parameters:

• url (str) – the URL at which the image can be fetched from the GroupMe image service
• source_url (str) – the original URL of the image (optional)

download()

Download the image data of the image attachment.

Returns:the actual image the image attachment references Return type:PIL.Image.Image

classmethod file(image)

Upload an image file and return it as an attachment.

Parameters:image (file) – the file containing the image data Returns:an image attachment Return type:Image

class groupy.object.attachments.Location(name, lat, lng, foursquare_venue_id=None)

An attachment that specifies a geo-location.

In addition to latitude and longitude, every location attachment also specifies a name. Some (especially older) location attachments also contain a foursquare_venue_id attribute.

Parameters:

• name (str) – the location name
• lat (float) – the latitude
• lng (float) – the longitude
• foursquare_venue_id (str) – the FourSquare venue ID (optional)

class groupy.object.attachments.Mentions(user_ids, loci=None)

An attachment that specifies “@” mentions.

Mentions are a new addition to the types of attachments. Each contains two parallel lists: user_ids and loci. The elements in loci specify the start index and length of the mention, while the elements in user_ids specify by user_id which user was mentioned in the corresponding element of loci.

Note

The length of user_ids must be equal to the length of loci!

Parameters:

• user_ids (list) – a list of user IDs
• loci (list) – a list of (start, length) elements

class groupy.object.attachments.Split(token)

An attachment containing information for splitting a bill.

This type of attachment is depreciated. However, such attachments are still present in older messages.

Parameters:token (str) – the token that splits the bill

The object.listers Module

This module contains classes that provide filterable lists and message pagers.

class groupy.object.listers.FilterList

A filterable list.

Acts just like a regular list, except it can be filtered using a special keyword syntax. Also, the first and last items are special properties.

filter(**kwargs)

Filter the list and return a new instance.

Arguments are keyword arguments only, and can be appended with operator method names to indicate relationships other than equals. For example, to filter the list down to only items whose name property contains “ie”:

new_list = filter_list.filter(name__contains='ie')

As another example, this filters the list down to only those with a created property that is less than 1234567890:

new_list = filter_list.filter(created__lt=1234567890)

Acceptable operators are:

• __lt: less than
• __gt: greater than
• __contains: contains
• __eq: equal to
• __ne: not equal to
• __le: less than or equal to
• __ge: greater than or equal to

Use of any operator listed here results in a InvalidOperatorError.

Returns:a new list with potentially less items than the original Return type:FilterList

first

The first element in the list.

last

The last element in the list.

class groupy.object.listers.MessagePager(group, messages, backward=False)

A filterable, extendable page of messages.

Parameters:

• group (Group) – the group from which to page through messages
• messages (list) – the initial page of messages
• backward (bool) – whether the oldest message is at index 0

inewer()

Add in-place the next (newer) page of messages.

Returns:True if successful, False otherwise Return type:bool

iolder()

Add in-place the previous (older) page of messages.

Returns:True if successful, False otherwise Return type:bool

newer()

Return the next (newer) page of messages.

Returns:a newer page of messages Return type:MessagePager

newest

Return the newest message in the list.

Returns:the newest message in the list Return type:Message

older()

Return the previous (older) page of messages.

Returns:an older page of messages Return type:MessagePager

oldest

Return the oldest message in the list.

Returns:the oldest message in the list Return type:Message

prepend(messages)

Prepend a list of messages to the list.

Parameters:messages (list) – the messages to prepend

The config Module

The config module contains all the configuration options.

groupy.config.API_URL = 'https://api.groupme.com/v3'

The URL for the GroupMe API

groupy.config.IMAGE_API_URL = 'https://image.groupme.com'

The URL for the GroupMe Image Service API

groupy.config.KEY_LOCATION = '~/.groupy.key'

Full path to the file in which your access token can be found