Low-Level APIs¶
This page documents the low-level APIs for using hangups.
Authentication¶
-
hangups.
get_auth_stdin
(refresh_token_filename, manual_login=False)[source]¶ Simple wrapper for
get_auth()
that prompts the user using stdin.Parameters: Raises: GoogleAuthError
– If authentication with Google fails.
-
hangups.
get_auth
(credentials_prompt, refresh_token_cache, manual_login=False)[source]¶ 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.
- manual_login (bool) – If true, prompt user to log in through a browser and enter authorization code manually. Defaults to false.
Returns: Google session cookies.
Return type: Raises: 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.
-
static
get_password
()[source]¶ Prompt for password.
Returns: Google account password. Return type: str
-
static
get_verification_code
()[source]¶ Prompt for verification code.
Returns: Google account verification code. Return type: str
Prompt for authorization code.
Returns: Google account authorization code. Return type: str
-
static
Client¶
-
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.
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.
-
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.
-
get_request_header
()[source]¶ 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.
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.
-
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
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_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
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
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_conversation_notification_level
(set_conversation_notification_level_request)[source]¶ Set the notification level of a conversation.
-
coroutine
set_group_link_sharing_enabled
(set_group_link_sharing_enabled_request)[source]¶ Set whether group link sharing is enabled for a conversation.
-
coroutine
sync_all_new_events
(sync_all_new_events_request)[source]¶ List all events occurring at or after a timestamp.
- cookies (dict) – Google session cookies. Get these using
Exceptions¶
Event¶
-
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_observer
(callback)[source]¶ 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_observer
(callback)[source]¶ 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.
-