Low-Level APIs¶
This page documents the low-level APIs for using hangups.
Authentication¶
-
hangups.
get_auth_stdin
(refresh_token_filename)¶ 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.
Parameters: - 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.
Returns: Google session cookies.
Return type: Raises: 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.
Client¶
-
class
hangups.
Client
(cookies, max_retries=5, retry_backoff_base=2)¶ 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()
. - 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.
-
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_group_conversation_url
(get_group_conversation_url_request)¶ Get URL to allow others to join a group conversation.
-
get_request_header
()¶ 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.
-
coroutine
set_group_link_sharing_enabled
(set_group_link_sharing_enabled_request)¶ 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, *, return_uploaded_image=False)¶ Upload an image that can be later attached to a chat message.
Parameters: - 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.
Raises: hangups.NetworkError
– If the upload request failed.Returns: UploadedImage
instance, or ID of the uploaded image.
- cookies (dict) – Google session cookies. Get these using
-
class
hangups.client.
UploadedImage
(image_id, url)¶
Exceptions¶
-
exception
hangups.
GoogleAuthError
¶ A Google authentication request failed.
-
exception
hangups.
HangupsError
¶ An ambiguous error occurred.
-
exception
hangups.
NetworkError
¶ A network error occurred.
Event¶
-
class
hangups.event.
Event
(name)¶ An event that can notify subscribers with arguments when fired.
Parameters: name (str) – Name of the new event. -
add_observer
(callback)¶ 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_observer
(callback)¶ 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.
-