High-Level APIs

This page documents high-level APIs that expose some of hangups’ low-level functionality in a simpler way.

Conversation List

coroutine hangups.build_user_conversation_list(client)

Build UserList and ConversationList.

This method requests data necessary to build the list of conversations and users. Users that are not in the contact list but are participating in a conversation will also be retrieved.

Parameters:client (Client) – Connected client. Returns:Tuple of built objects. Return type:(UserList, ConversationList)

class hangups.ConversationList(client, conv_states, user_list, sync_timestamp)

Maintains a list of the user’s conversations.

Using build_user_conversation_list() to initialize this class is recommended.

Parameters:

• client – The connected Client.
• conv_states – List of ConversationState messages used to initialize the list of conversations.
• user_list – UserList object.
• sync_timestamp (datetime.datetime) – The time when conv_states was synced.

on_event = None

Event fired when an event occurs in any conversation.

Parameters:conv_event – ConversationEvent that occurred.

on_typing = None

Event fired when a users starts or stops typing in any conversation.

Parameters:typing_message – TypingStatusMessage that occurred.

on_watermark_notification = None

Event fired when a watermark (read timestamp) is updated for any conversation.

Parameters:watermark_notification – WatermarkNotification that occurred.

get_all(include_archived=False)

Get all the conversations.

Parameters:include_archived (bool) – (optional) Whether to include archived conversations. Defaults to False. Returns:List of all Conversation objects.

get(conv_id)

Get a conversation by its ID.

Parameters:conv_id (str) – ID of conversation to return. Raises:KeyError – If the conversation ID is not found. Returns:Conversation with matching ID.

coroutine leave_conversation(conv_id)

Leave a conversation.

Parameters:conv_id (str) – ID of conversation to leave.

Conversation

class hangups.conversation.Conversation(client, user_list, conversation, events=[], event_cont_token=None)

A single chat conversation.

Use ConversationList methods to get instances of this class.

on_event = None

Event fired when an event occurs in this conversation.

Parameters:conv_event – ConversationEvent that occurred.

on_typing = None

Event fired when a users starts or stops typing in this conversation.

Parameters:typing_message – TypingStatusMessage that occurred.

on_watermark_notification = None

Event fired when a watermark (read timestamp) is updated for this conversation.

Parameters:watermark_notification – WatermarkNotification that occurred.

id_

The conversation’s ID (str).

users

List of conversation participants (User).

name

The conversation’s custom name (str)

May be None if conversation has no custom name.

last_modified

When conversation was last modified (datetime.datetime).

latest_read_timestamp

Timestamp of latest read event (datetime.datetime).

events

Loaded events sorted oldest to newest.

(list of ConversationEvent).

watermarks

Participant watermarks.

(dict of UserID, datetime.datetime).

unread_events

Loaded events which are unread sorted oldest to newest.

Some Hangouts clients don’t update the read timestamp for certain event types, such as membership changes, so this may return more unread events than these clients will show. There’s also a delay between sending a message and the user’s own message being considered read.

(list of ConversationEvent).

is_archived

True if this conversation has been archived.

is_quiet

True if notification level for this conversation is quiet.

is_off_the_record

True if conversation is off the record (history is disabled).

is_group_link_sharing_enabled

True if group link sharing (joining by link) is enabled.

update_conversation(conversation)

Update the internal state of the conversation.

This method is used by ConversationList to maintain this instance.

Parameters:conversation – Conversation message.

add_event(event_)

Add an event to the conversation.

This method is used by ConversationList to maintain this instance.

Parameters:event – Event message. Returns:ConversationEvent representing the event.

get_user(user_id)

Get user by its ID.

Parameters:user_id (UserID) – ID of user to return. Raises:KeyError – If the user ID is not found. Returns:User with matching ID.

coroutine send_message(segments, image_file=None, image_id=None, image_user_id=None)

Send a message to this conversation.

A per-conversation lock is acquired to ensure that messages are sent in the correct order when this method is called multiple times asynchronously.

Parameters:

• segments – List of ChatMessageSegment objects to include in the message.
• image_file – (optional) File-like object containing an image to be attached to the message.
• image_id – (optional) ID of an Picasa photo to be attached to the message. If you specify both image_file and image_id together, image_file takes precedence and image_id will be ignored.
• image_user_id – (optional) Picasa user ID, required only if image_id refers to an image from a different Picasa user, such as Google’s sticker user.

Raises:

NetworkError – If the message cannot be sent.

Returns:

ConversationEvent representing the new message.

coroutine add_users(user_ids)

Add one or more users to this conversation.

Parameters:

user_ids – List of IDs of the new users to be added; accepts UserID, InviteeID or just str IDs.

Raises:

• ConversationTypeError – If conversation is not a group.
• NetworkError – If conversation cannot be invited to.

Returns:

ConversationEvent representing the change.

coroutine remove_user(user_id)

Remove a user from this conversation.

Parameters:

user_id – ID of the user to be removed; accepts UserID, ParticipantId or just str IDs.

Raises:

• ConversationTypeError – If conversation is not a group.
• NetworkError – If conversation cannot be removed from.

Returns:

ConversationEvent representing the change.

coroutine leave()

Leave this conversation.

Raises:NetworkError – If conversation cannot be left.

coroutine rename(name)

Rename this conversation.

Hangouts only officially supports renaming group conversations, so custom names for one-to-one conversations may or may not appear in all first party clients.

Parameters:name (str) – New name. Raises:NetworkError – If conversation cannot be renamed.

coroutine set_notification_level(level)

Set the notification level of this conversation.

Parameters:level – NOTIFICATION_LEVEL_QUIET to disable notifications, or NOTIFICATION_LEVEL_RING to enable them. Raises:NetworkError – If the request fails.

coroutine modify_otr_status(off_record)

Set the OTR mode of this conversation.

Parameters:off_record – True to disable history, or False to enable it. Raises:NetworkError – If the request fails. Returns:ConversationEvent representing the change.

coroutine set_group_link_sharing_enabled(enabled)

Set the link sharing mode of this conversation.

Parameters:

enabled – True to allow joining the conversation by link, or False to prevent it.

Raises:

• ConversationTypeError – If conversation is not a group.
• NetworkError – If the request fails.

Returns:

ConversationEvent representing the change.

coroutine set_typing(typing=1)

Set your typing status in this conversation.

Parameters:typing – (optional) TYPING_TYPE_STARTED, TYPING_TYPE_PAUSED, or TYPING_TYPE_STOPPED to start, pause, or stop typing, respectively. Defaults to TYPING_TYPE_STARTED. Raises:NetworkError – If typing status cannot be set.

coroutine update_read_timestamp(read_timestamp=None)

Update the timestamp of the latest event which has been read.

This method will avoid making an API request if it will have no effect.

Parameters:read_timestamp (datetime.datetime) – (optional) Timestamp to set. Defaults to the timestamp of the newest event. Raises:NetworkError – If the timestamp cannot be updated.

coroutine get_events(event_id=None, max_events=50)

Get events from this conversation.

Makes a request to load historical events if necessary.

Parameters:

• event_id (str) – (optional) If provided, return events preceding this event, otherwise return the newest events.
• max_events (int) – Maximum number of events to return. Defaults to 50.

Returns:

List of ConversationEvent instances, ordered oldest-first.

Raises:

• KeyError – If event_id does not correspond to a known event.
• NetworkError – If the events could not be requested.

next_event(event_id, prev=False)

Get the event following another event in this conversation.

Parameters:

• event_id (str) – ID of the event.
• prev (bool) – If True, return the previous event rather than the next event. Defaults to False.

Raises:

KeyError – If no such ConversationEvent is known.

Returns:

ConversationEvent or None if there is no following event.

get_event(event_id)

Get an event in this conversation by its ID.

Parameters:event_id (str) – ID of the event. Raises:KeyError – If no such ConversationEvent is known. Returns:ConversationEvent with the given ID.

Conversation Event

class hangups.ConversationEvent(event)

An event which becomes part of the permanent record of a conversation.

This is a wrapper for the Event message, which may contain one of many subtypes, represented here as other subclasses.

Parameters:event – Event message.

timestamp

When the event occurred (datetime.datetime).

user_id

Who created the event (UserID).

conversation_id

ID of the conversation containing the event (str).

id_

ID of this event (str).

class hangups.ChatMessageEvent(event)

An event that adds a new message to a conversation.

Corresponds to the ChatMessage message.

text

Text of the message without formatting (str).

segments

List of ChatMessageSegment in message (list).

attachments

List of attachments in the message (list).

class hangups.OTREvent(event)

An event that changes a conversation’s OTR (history) mode.

Corresponds to the OTRModification message.

new_otr_status

The conversation’s new OTR status.

May be either OFF_THE_RECORD_STATUS_OFF_THE_RECORD or OFF_THE_RECORD_STATUS_ON_THE_RECORD.

old_otr_status

The conversation’s old OTR status.

May be either OFF_THE_RECORD_STATUS_OFF_THE_RECORD or OFF_THE_RECORD_STATUS_ON_THE_RECORD.

class hangups.RenameEvent(event)

An event that renames a conversation.

Corresponds to the ConversationRename message.

new_name

The conversation’s new name (str).

May be an empty string if the conversation’s name was cleared.

old_name

The conversation’s old name (str).

May be an empty string if the conversation had no previous name.

class hangups.MembershipChangeEvent(event)

An event that adds or removes a conversation participant.

Corresponds to the MembershipChange message.

type_

The type of membership change.

May be either MEMBERSHIP_CHANGE_TYPE_JOIN or MEMBERSHIP_CHANGE_TYPE_LEAVE.

participant_ids

UserID of users involved (list).

class hangups.HangoutEvent(event)

An event that is related to a Hangout voice or video call.

Corresponds to the HangoutEvent message.

event_type

The Hangout event type.

May be one of HANGOUT_EVENT_TYPE_START, HANGOUT_EVENT_TYPE_END, HANGOUT_EVENT_TYPE_JOIN, HANGOUT_EVENT_TYPE_LEAVE, HANGOUT_EVENT_TYPE_COMING_SOON, or HANGOUT_EVENT_TYPE_ONGOING.

class hangups.GroupLinkSharingModificationEvent(event)

An event that modifies a conversation’s group link sharing status.

Corresponds to the GroupLinkSharingModification message.

new_status

The new group link sharing status.

May be either GROUP_LINK_SHARING_STATUS_ON or GROUP_LINK_SHARING_STATUS_OFF.

Chat Message Segment

class hangups.ChatMessageSegment(text, segment_type=None, is_bold=False, is_italic=False, is_strikethrough=False, is_underline=False, link_target=None)

A segment of a chat message in ChatMessageEvent.

Parameters:

• text (str) – Text of the segment.
• segment_type – (optional) One of SEGMENT_TYPE_TEXT, SEGMENT_TYPE_LINE_BREAK, or SEGMENT_TYPE_LINK. Defaults to SEGMENT_TYPE_TEXT, or SEGMENT_TYPE_LINK if link_target is specified.
• is_bold (bool) – (optional) Whether the text is bold. Defaults to False.
• is_italic (bool) – (optional) Whether the text is italic. Defaults to False.
• is_strikethrough (bool) – (optional) Whether the text is struck through. Defaults to False.
• is_underline (bool) – (optional) Whether the text is underlined. Defaults to False.
• link_target (str) – (option) URL to link to. Defaults to None.

static from_str(text)

Construct ChatMessageSegment list parsed from a string.

Parameters:text (str) – Text to parse. May contain line breaks, URLs and formatting markup (simplified Markdown and HTML) to be converted into equivalent segments. Returns:List of ChatMessageSegment objects.

static deserialize(segment)

Construct ChatMessageSegment from Segment message.

Parameters:segment – Segment message to parse. Returns:ChatMessageSegment object.

serialize()

Serialize this segment to a Segment message.

Returns:Segment message.

Notifications

class hangups.parsers.TypingStatusMessage(conv_id, user_id, timestamp, status)

A notification about a user’s typing status in a conversation.

Parameters:

• conv_id (str) – ID of the conversation.
• user_id (hangups.user.UserID) – ID of the affected user.
• timestamp (datetime.datetime) – When the notification was generated.
• status – The new status; one of TYPING_TYPE_STARTED, TYPING_TYPE_PAUSED, or TYPING_TYPE_STOPPED.

class hangups.parsers.WatermarkNotification(conv_id, user_id, read_timestamp)

A notification about a user’s watermark (read timestamp).

Parameters:

• conv_id (str) – ID of the conversation.
• user_id (hangups.user.UserID) – ID of the affected user.
• read_timestamp (datetime.datetime) – The new watermark.

User List

class hangups.UserList(client, self_entity, entities, conv_parts)

Maintains a list of all the users.

Using build_user_conversation_list() to initialize this class is recommended.

Parameters:

• client – The connected Client.
• self_entity – Entity message for the current user.
• entities – List of known Entity messages.
• conv_parts – List of ConversationParticipantData messages. These are used as a fallback in case any users are missing.

get_user(user_id)

Get a user by its ID.

Parameters:user_id (UserID) – The ID of the user. Raises:KeyError – If no such user is known. Returns:User with the given ID.

get_all()

Get all known users.

Returns:List of User instances.

User

class hangups.user.NameType

Indicates which type of name a user has.

DEFAULT indicates that only a first name is available. NUMERIC indicates that only a numeric name is available. REAL indicates that a real full name is available.

DEFAULT = 0

NUMERIC = 1

REAL = 2

class hangups.user.UserID(chat_id, gaia_id)

A user ID, consisting of two parts which are always identical.

class hangups.user.User(user_id, full_name, first_name, photo_url, canonical_email, emails, is_self)

A chat user.

Use UserList or ConversationList methods to get instances of this class.

name_type = None

The user’s name type (NameType).

full_name = None

The user’s full name (str).

first_name = None

The user’s first name (str).

id_ = None

The user’s ID (UserID).

photo_url = None

The user’s profile photo URL (str).

canonical_email = None

The user’s canonical email address (str).

emails = None

The user’s email addresses (list).

is_self = None

Whether this user is the current user (bool).

upgrade_name(user_)

Upgrade name type of this user.

Google Voice participants often first appear with no name at all, and then get upgraded unpredictably to numbers (“+12125551212”) or names.

Parameters:user (User) – User to upgrade with.

static from_entity(entity, self_user_id)

Construct user from Entity message.

Parameters:

• entity – Entity message.
• self_user_id (UserID or None) – The ID of the current user. If None, assume entity is the current user.

Returns:

User object.

static from_conv_part_data(conv_part_data, self_user_id)

Construct user from ConversationParticipantData message.

Parameters:

• conv_part_id – ConversationParticipantData message.
• self_user_id (UserID or None) – The ID of the current user. If None, assume conv_part_id is the current user.

Returns:

User object.