GroupMe Push Client

A client for the GroupMe push service (Faye). It opens a websocket to GroupMe and calls your functions when messages, DMs and likes arrive.

Installation

pip install groupme-push, or clone the repo and run pip install .

Quick start

from groupme_push import PushClient

def on_message(message):
    print(message["text"])

client = PushClient(access_token="useraccesstoken", on_message=on_message)
client.start()
client.join()  # block until the client stops

Get an access token from dev.groupme.com.

Listening to one group

GroupMe pushes every group's messages down your personal channel, so subscribe_to_group() does not narrow the stream — it adds a group's own channel (typing notifications and the like) on top. To hear about only certain groups, pass group_ids:

client = PushClient(
    access_token="useraccesstoken",
    on_message=on_message,
    group_ids=["12345678"],  # everything else is dropped
)
client.start()

DMs and other events that have no group id are never filtered out; leave on_dm unset if you do not want them.

To find your group ids:

for group_id, name in PushClient(access_token="useraccesstoken").list_groups():
    print(group_id, name)

Options

Methods

• start(wait=False, timeout=10) — authenticate, handshake and open the socket. With wait=True it blocks until the socket is open and raises ConnectionTimeout if it never does.
• stop(timeout=5) — close the socket and stop reconnecting.
• join(timeout=None) — block the calling thread until the client stops.
• wait_until_connected(timeout=10) / is_connected — connection state.
• subscribe_to_group(group_id, timeout=10) — subscribe to a group's own channel. Safe to call right after start(): it waits for the socket, and the subscription is replayed automatically after a reconnect.
• unsubscribe_from_group(group_id) — the reverse.
• list_groups(per_page=100) — [(group_id, name), ...] for the user's groups, over REST. Handy for finding the ids to pass to group_ids.

PushClient is also a context manager:

with PushClient(access_token="useraccesstoken", on_message=on_message) as client:
    client.join()

Registering handlers with decorators

client = PushClient(access_token="useraccesstoken")

@client.receive_message
def on_message(message):
    print(message["text"])

There is one of these per callback: receive_message, receive_dm, receive_like, receive_favorite, receive_other, receive_connect, receive_error.

Errors

start() raises instead of logging and carrying on with a dead client:

• AuthenticationError — GroupMe rejected the access token.
• HandshakeError — Faye did not return a client id.
• ConnectionTimeout — start(wait=True) timed out.

All of them subclass GroupMePushError.

Examples

See examples/: basic.py, single_group.py, decorators.py.

Development

pip install -e ".[dev]"
pytest

The tests run against a scripted fake websocket, so no token or network access is needed.

Releases are additionally smoke tested against the live GroupMe service: the client creates a throwaway group, posts to it, and asserts on delivery, ordering, filtering, disregard_self and reconnect recovery.

Issues

If you encounter any bugs or have feature requests, please open an issue on GitHub.