Low-Level APIs

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


hangups.get_auth_stdin(refresh_token_filename, manual_login=False)[source]

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

  • refresh_token_filename (str) – Path to file where refresh token will be cached.
  • manual_login (bool) – If true, prompt user to log in through a browser and enter authorization code manually. Defaults to false.

GoogleAuthError – If authentication with Google fails.

hangups.get_auth(credentials_prompt, refresh_token_cache, manual_login=False)[source]

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.
  • manual_login (bool) – If true, prompt user to log in through a browser and enter authorization code manually. Defaults to false.

Google session cookies.

Return type:



GoogleAuthError – If authentication with Google fails.

class hangups.CredentialsPrompt[source]

Callbacks for prompting user for their Google account credentials.

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


Prompt for email.

Returns:Google account email address.
Return type:str

Prompt for password.

Returns:Google account password.
Return type:str

Prompt for verification code.

Returns:Google account verification code.
Return type:str

Prompt for authorization code.

Returns:Google account authorization code.
Return type:str
class hangups.RefreshTokenCache(filename)[source]

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, max_retries=5, retry_backoff_base=2)[source]

Instant messaging client for Hangouts.

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

  • cookies (dict) – Google session cookies. Get these using get_auth().
  • max_retries (int) – (optional) Maximum number of connection attempts hangups will make before giving up. Defaults to 5.
  • retry_backoff_base (int) – (optional) The base term for the exponential backoff. The following equation is used when calculating the number of seconds to wait prior to each retry: retry_backoff_base^(# of retries attempted thus far) Defaults to 2.
on_connect = None

Event fired when the client connects for the first time.

on_reconnect = None

Event fired when the client reconnects after being disconnected.

on_disconnect = None

Event fired when the client is disconnected.

on_state_update = None

Event fired when an update arrives from the server.

Parameters:state_update – A StateUpdate message.
coroutine connect()[source]

Establish a connection to the chat server.

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

coroutine disconnect()[source]

Gracefully disconnect from the server.

When disconnection is complete, connect() will return.


Return request_header for use when constructing requests.

Returns:Populated request header.
static get_client_generated_id()[source]

Return client_generated_id for use when constructing requests.

Returns:Client generated ID.
coroutine set_active()[source]

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 upload_image(image_file, filename=None, *, return_uploaded_image=False)[source]

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.
  • return_uploaded_image (bool) – (optional) If True, return UploadedImage instead of image ID. Defaults to False.

hangups.NetworkError – If the upload request failed.


UploadedImage instance, or ID of the uploaded image.

coroutine add_user(add_user_request)[source]

Invite users to join an existing group conversation.

coroutine create_conversation(create_conversation_request)[source]

Create a new conversation.

coroutine delete_conversation(delete_conversation_request)[source]

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 easter_egg(easter_egg_request)[source]

Send an easter egg event to a conversation.

coroutine get_conversation(get_conversation_request)[source]

Return conversation info and recent events.

coroutine get_entity_by_id(get_entity_by_id_request)[source]

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.

coroutine get_group_conversation_url(get_group_conversation_url_request)[source]

Get URL to allow others to join a group conversation.

coroutine get_self_info(get_self_info_request)[source]

Return info about the current user.

coroutine get_suggested_entities(get_suggested_entities_request)[source]

Return suggested contacts.

coroutine query_presence(query_presence_request)[source]

Return presence status for a list of users.

coroutine remove_user(remove_user_request)[source]

Remove a participant from a group conversation.

coroutine rename_conversation(rename_conversation_request)[source]

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)[source]

Return user entities based on a query.

coroutine send_chat_message(send_chat_message_request)[source]

Send a chat message to a conversation.

coroutine modify_otr_status(modify_otr_status_request)[source]

Enable or disable message history in a conversation.

coroutine send_offnetwork_invitation(send_offnetwork_invitation_request)[source]

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

coroutine set_active_client(set_active_client_request)[source]

Set the active client.

coroutine set_conversation_notification_level(set_conversation_notification_level_request)[source]

Set the notification level of a conversation.

coroutine set_focus(set_focus_request)[source]

Set focus to a conversation.

Set whether group link sharing is enabled for a conversation.

coroutine set_presence(set_presence_request)[source]

Set the presence status.

coroutine set_typing(set_typing_request)[source]

Set the typing status of a conversation.

coroutine sync_all_new_events(sync_all_new_events_request)[source]

List all events occurring at or after a timestamp.

coroutine sync_recent_conversations(sync_recent_conversations_request)[source]

Return info on recent conversations and their events.

coroutine update_watermark(update_watermark_request)[source]

Update the watermark (read timestamp) of a conversation.

class hangups.client.UploadedImage(image_id, url)

Details about an uploaded image.

  • image_id (str) – Image ID of uploaded image.
  • url (str) – URL of uploaded image.


exception hangups.GoogleAuthError[source]

A Google authentication request failed.

exception hangups.HangupsError[source]

An ambiguous error occurred.

exception hangups.NetworkError[source]

A network error occurred.

exception hangups.ConversationTypeError[source]

An action was performed on a conversation that doesn’t support it.


class hangups.event.Event(name)[source]

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.

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.
coroutine fire(*args, **kwargs)[source]

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