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)[source]¶ Build
UserList
andConversationList
.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)[source]¶ 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)[source]¶ 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)[source]¶ 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.
- client – The connected
Conversation¶
-
class
hangups.conversation.
Conversation
(client, user_list, conversation, events=[], event_cont_token=None)[source]¶ 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.
-
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).
-
update_conversation
(conversation)[source]¶ Update the internal state of the conversation.
This method is used by
ConversationList
to maintain this instance.Parameters: conversation – Conversation
message.
-
add_event
(event_)[source]¶ 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)[source]¶ 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)[source]¶ 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
andimage_id
together,image_file
takes precedence andimage_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.- segments – List of
-
coroutine
leave
()[source]¶ Leave this conversation.
Raises: NetworkError
– If conversation cannot be left.
-
coroutine
rename
(name)[source]¶ 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)[source]¶ Set the notification level of this conversation.
Parameters: level – NOTIFICATION_LEVEL_QUIET
to disable notifications, orNOTIFICATION_LEVEL_RING
to enable them.Raises: NetworkError
– If the request fails.
-
coroutine
set_typing
(typing=1)[source]¶ Set your typing status in this conversation.
Parameters: typing – (optional) TYPING_TYPE_STARTED
,TYPING_TYPE_PAUSED
, orTYPING_TYPE_STOPPED
to start, pause, or stop typing, respectively. Defaults toTYPING_TYPE_STARTED
.Raises: NetworkError
– If typing status cannot be set.
-
coroutine
update_read_timestamp
(read_timestamp=None)[source]¶ 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)[source]¶ Get events from this conversation.
Makes a request to load historical events if necessary.
Parameters: Returns: List of
ConversationEvent
instances, ordered oldest-first.Raises: KeyError
– Ifevent_id
does not correspond to a known event.NetworkError
– If the events could not be requested.
-
next_event
(event_id, prev=False)[source]¶ Get the event following another event in this conversation.
Parameters: Raises: KeyError
– If no suchConversationEvent
is known.Returns: ConversationEvent
orNone
if there is no following event.
-
get_event
(event_id)[source]¶ Get an event in this conversation by its ID.
Parameters: event_id (str) – ID of the event. Raises: KeyError
– If no suchConversationEvent
is known.Returns: ConversationEvent
with the given ID.
-
Conversation Event¶
-
class
hangups.
ConversationEvent
(event)[source]¶ 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
).
-
-
class
hangups.
ChatMessageEvent
(event)[source]¶ An event that adds a new message to a conversation.
Corresponds to the
ChatMessage
message.-
segments
¶ List of
ChatMessageSegment
in message (list
).
-
-
class
hangups.
OTREvent
(event)[source]¶ 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
orOFF_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
orOFF_THE_RECORD_STATUS_ON_THE_RECORD
.
-
-
class
hangups.
RenameEvent
(event)[source]¶ An event that renames a conversation.
Corresponds to the
ConversationRename
message.
-
class
hangups.
MembershipChangeEvent
(event)[source]¶ 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
orMEMBERSHIP_CHANGE_TYPE_LEAVE
.
-
-
class
hangups.
HangoutEvent
(event)[source]¶ 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
, orHANGOUT_EVENT_TYPE_ONGOING
.
-
-
class
hangups.
GroupLinkSharingModificationEvent
(event)[source]¶ 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
orGROUP_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)[source]¶ 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
, orSEGMENT_TYPE_LINK
. Defaults toSEGMENT_TYPE_TEXT
, orSEGMENT_TYPE_LINK
iflink_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)[source]¶ 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)[source]¶ Construct
ChatMessageSegment
fromSegment
message.Parameters: segment – Segment
message to parse.Returns: ChatMessageSegment
object.
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
, orTYPING_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)[source]¶ 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.
- client – The connected
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, emails, is_self)[source]¶ A chat user.
Use
UserList
orConversationList
methods to get instances of this class.-
upgrade_name
(user_)[source]¶ 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)[source]¶ Construct user from
Entity
message.Parameters: Returns: User
object.
-