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_listUserList object.
  • sync_timestamp (datetime.datetime) – The time when conv_states was synced.
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.
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.
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=[])

A single chat conversation.

Use ConversationList methods to get instances of this class.

add_event(event_)

Add an event to the conversation.

This method is used by ConversationList to maintain this instance.

Parameters:eventEvent message.
Returns:ConversationEvent representing the event.
events

Loaded events sorted oldest to newest.

(list of ConversationEvent).

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.
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 newest-first.

Raises:
  • KeyError – If event_id does not correspond to a known event.
  • NetworkError – If the events could not be requested.
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.
id_

The conversation’s ID (str).

is_archived

True if this conversation has been archived.

is_off_the_record

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

is_quiet

True if notification level for this conversation is quiet.

last_modified

When conversation was last modified (datetime.datetime).

latest_read_timestamp

Timestamp of latest read event (datetime.datetime).

coroutine leave()

Leave this conversation.

Raises:NetworkError – If conversation cannot be left.
name

The conversation’s custom name (str)

May be None if conversation has no custom name.

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.

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 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.

coroutine set_notification_level(level)

Set the notification level of this conversation.

Parameters:levelNOTIFICATION_LEVEL_QUIET to disable notifications, or NOTIFICATION_LEVEL_RING to enable them.
Raises:NetworkError – If the request fails.
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.
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).

update_conversation(conversation)

Update the internal state of the conversation.

This method is used by ConversationList to maintain this instance.

Parameters:conversationConversation message.
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.
users

List of conversation participants (User).

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:eventEvent message.
conversation_id

ID of the conversation containing the event (str).

id_

ID of this event (str).

timestamp

When the event occurred (datetime.datetime).

user_id

Who created the event (UserID).

class hangups.ChatMessageEvent(event)

An event that adds a new message to a conversation.

Corresponds to the ChatMessage message.

attachments

List of attachments in the message (list).

segments

List of ChatMessageSegment in message (list).

text

Text of the message without formatting (str).

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.

participant_ids

UserID of users involved (list).

type_

The type of membership change.

May be either MEMBERSHIP_CHANGE_TYPE_JOIN or MEMBERSHIP_CHANGE_TYPE_LEAVE.

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 deserialize(segment)

Construct ChatMessageSegment from Segment message.

Parameters:segmentSegment message to parse.
Returns:ChatMessageSegment object.
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.
serialize()

Serialize this segment to a Segment message.

Returns:Segment message.

Notifications

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

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_entityEntity 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_all()

Get all known users.

Returns:List of User instances.
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.

User

class hangups.user.NameType

An enumeration.

DEFAULT = 0
NUMERIC = 1
REAL = 2
class hangups.user.UserID(chat_id, gaia_id)
class hangups.user.User(user_id, full_name, first_name, photo_url, emails, is_self)

A chat user.

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

static from_conv_part_data(conv_part_data, self_user_id)

Construct user from ConversationParticipantData message.

Parameters:
  • conv_part_idConversationParticipantData 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.

static from_entity(entity, self_user_id)

Construct user from Entity message.

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

User object.

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.