Low-Level APIs

This page documents the low-level APIs for using hangups.



Simple wrapper for get_auth() that prompts the user using stdin.

Parameters:refresh_token_filename (str) – Path to file where refresh token will be cached.
Raises:GoogleAuthError – If authentication with Google fails.
hangups.get_auth(credentials_prompt, refresh_token_cache)

Authenticate with Google.

  • refresh_token_cache (RefreshTokenCache) – Cache to use so subsequent logins may not require credentials.
  • credentials_prompt (CredentialsPrompt) – Prompt to use if credentials are required to log in.

Google session cookies.

Return type:



GoogleAuthError – If authentication with Google fails.

class hangups.CredentialsPrompt

Callbacks for prompting user for their Google account credentials.

This implementation prompts the user in a terminal using standard in/out.

static get_email()

Prompt for email.

Returns:Google account email address.
Return type:str
static get_password()

Prompt for password.

Returns:Google account password.
Return type:str
static get_verification_code()

Prompt for verification code.

Returns:Google account verification code.
Return type:str
class hangups.RefreshTokenCache(filename)

File-based cache for refresh token.

Parameters:filename (str) – Path to file where refresh token will be cached.

Get cached refresh token.

Returns:Cached refresh token, or None on failure.

Cache a refresh token, ignoring any failure.

Parameters:refresh_token (str) – Refresh token to cache.


class hangups.Client(cookies)

Instant messaging client for Hangouts.

Maintains a connections to the servers, emits events, and accepts commands.

Parameters:cookies (dict) – Google session cookies. Get these using get_auth().
coroutine add_user(add_user_request)

Invite users to join an existing group conversation.

coroutine connect()

Establish a connection to the chat server.

Returns when an error has occurred, or disconnect() has been called.

coroutine create_conversation(create_conversation_request)

Create a new conversation.

coroutine delete_conversation(delete_conversation_request)

Leave a one-to-one conversation.

One-to-one conversations are “sticky”; they can’t actually be deleted. This API clears the event history of the specified conversation up to delete_upper_bound_timestamp, hiding it if no events remain.

coroutine disconnect()

Gracefully disconnect from the server.

When disconnection is complete, connect() will return.

coroutine easter_egg(easter_egg_request)

Send an easter egg event to a conversation.

static get_client_generated_id()

Return client_generated_id for use when constructing requests.

Returns:Client generated ID.
coroutine get_conversation(get_conversation_request)

Return conversation info and recent events.

coroutine get_entity_by_id(get_entity_by_id_request)

Return one or more user entities.

Searching by phone number only finds entities when their phone number is in your contacts (and not always even then), and can’t be used to find Google Voice contacts.


Get URL to allow others to join a group conversation.


Return request_header for use when constructing requests.

Returns:Populated request header.
coroutine get_self_info(get_self_info_request)

Return info about the current user.

coroutine get_suggested_entities(get_suggested_entities_request)

Return suggested contacts.

coroutine modify_otr_status(modify_otr_status_request)

Enable or disable message history in a conversation.

coroutine query_presence(query_presence_request)

Return presence status for a list of users.

coroutine remove_user(remove_user_request)

Remove a participant from a group conversation.

coroutine rename_conversation(rename_conversation_request)

Rename a conversation.

Both group and one-to-one conversations may be renamed, but the official Hangouts clients have mixed support for one-to-one conversations with custom names.

coroutine search_entities(search_entities_request)

Return user entities based on a query.

coroutine send_chat_message(send_chat_message_request)

Send a chat message to a conversation.

coroutine send_offnetwork_invitation(send_offnetwork_invitation_request)

Send an email to invite a non-Google contact to Hangouts.

coroutine set_active()

Set this client as active.

While a client is active, no other clients will raise notifications. Call this method whenever there is an indication the user is interacting with this client. This method may be called very frequently, and it will only make a request when necessary.

coroutine set_active_client(set_active_client_request)

Set the active client.

coroutine set_conversation_notification_level(set_conversation_notification_level_request)

Set the notification level of a conversation.

coroutine set_focus(set_focus_request)

Set focus to a conversation.

Set whether group link sharing is enabled for a conversation.

coroutine set_presence(set_presence_request)

Set the presence status.

coroutine set_typing(set_typing_request)

Set the typing status of a conversation.

coroutine sync_all_new_events(sync_all_new_events_request)

List all events occurring at or after a timestamp.

coroutine sync_recent_conversations(sync_recent_conversations_request)

Return info on recent conversations and their events.

coroutine update_watermark(update_watermark_request)

Update the watermark (read timestamp) of a conversation.

coroutine upload_image(image_file, filename=None)

Upload an image that can be later attached to a chat message.

  • image_file – A file-like object containing an image.
  • filename (str) – (optional) Custom name for the uploaded file.

hangups.NetworkError – If the upload request failed.


ID of the uploaded image.


exception hangups.GoogleAuthError

A Google authentication request failed.

exception hangups.HangupsError

An ambiguous error occurred.

exception hangups.NetworkError

A network error occurred.


class hangups.event.Event(name)

An event that can notify subscribers with arguments when fired.

Parameters:name (str) – Name of the new event.

Add an observer to this event.

Parameters:callback – A function or coroutine callback to call when the event is fired.
Raises:ValueError – If the callback has already been added.
coroutine fire(*args, **kwargs)

Fire this event, calling all observers with the same arguments.


Remove an observer from this event.

Parameters:callback – A function or coroutine callback to remove from this event.
Raises:ValueError – If the callback is not an observer of this event.