hangups¶

hangups is the first third-party instant messaging client for Google Hangouts. It includes both a Python library and a reference client with a text-based user interface.

Unlike its predecessor Google Talk, Hangouts uses a proprietary, non-interoperable protocol. hangups is implemented by reverse-engineering this protocol, which allows it to support features like group messaging that aren’t available in clients that connect via XMPP.

hangups is still in an early stage of development. The reference client is usable for basic chatting, but the API is undocumented and subject to change. Bug reports and pull requests are welcome!

Quick Links¶

hangups on GitHub

Documentation Contents¶

Installation¶

hangups requires Python 3.4.2+ and is known to work on Linux, Mac OS X, and Windows (with Cygwin).

Python Package Index (PyPI)¶

hangups is listed in PyPI, and may be installed using pip:

pip3 install hangups

Docker¶

hangups is available as an automated build on Docker Hub as tdryer/hangups.

Create a data-only container for hangups to allow upgrading without losing your login session:

docker run --name hangups-session --entrypoint true tdryer/hangups

Whenever you want to start hangups, run a new container:

docker run -it --rm --name hangups --volumes-from hangups-session tdryer/hangups

To upgrade hangups, pull the latest version of the image:

docker pull tdryer/hangups

Arch Linux¶

An unofficial hangups package is available for Arch Linux in the Arch User Repository.

Install from Source¶

The hangups code is available from GitHub. Either download and extract a hangups release archive, or clone the hangups repository:

git clone https://github.com/tdryer/hangups.git

Switch to the hangups directory and install the package:

cd hangups
python3 setup.py install

User Guide¶

This page is intended for end-users who want to use the textual user interface included with hangups.

Running¶

Once installed, run this command to start hangups:

hangups

For help with command line arguments, run:

hangups -h

Logging in¶

The first time you start hangups, you need to log into your Google account.

Caution

Never give your Google account credentials to any application or device that you don’t trust. Logging into Google grants hangups unrestricted access to your account. hangups works this way because Google does not provide any other method to access the Hangouts API.

You will be prompted to enter your Google email address, password, and verification code (if applicable).

After a successful login, hangups will save a refresh token allowing it to login automatically. By default, the token is saved to a file in an OS-specific cache directory. The default token file path can be viewed using hangups -h. To specify a different path for the token file, use the --token-path option:

hangups --token-path /path/to/refresh_token.txt

hangups may be deauthorized from your Google account using the Google recently used devices page. hangups will be listed as “iOS”.

Usage¶

After connecting, hangups will display the conversations tab, which lists the names of all the available conversations. Use the up and down arrow keys to select a conversation, and press enter to open it in a new tab.

hangups uses a tabbed interface. The first tab is always the conversations tab. Once multiple tabs are open, use ctrl+u and ctrl+d and move up and down the list of tabs. Use ctrl+w to close a tab.

In a conversation tab, type a message and press enter to send it, or use the up and arrows to scroll the list of previous messages. hangups supports readline commands for editing text. See the readlike library documentation for a full list. Note that some of hangouts’ bindings conflict with these key combinations, see the Configuration section on how to adjust key bindings.

When new messages arrive, hangups will open a conversation tab in the background, and display the number of unread messages in the tab title. On Linux (with an appropriate desktop notification service running) and Mac OS X, hangups will also display a desktop notification. To mark messages as read, press any key (such as enter) while in a conversation tab.

When the network connection is interrupted, hangups will show a “Disconnected” message in each conversation. When the connection is restored a “Connected” message is shown, and hangups will attempt to sync any messages that were missed during the disconnection. If hangups is disconnected for too long, it will eventually exit.

To exit hangups, press ctrl+e.

Configuration¶

hangups may be configured through both command line arguments and a configuration file. See the output of hangups -h for details on using both of these methods.

Keybindings are specified using urwid’s format, for example: ctrl e or shift ctrl e. Some key combinations may be unavailable due to terminal limitations or conflicts.

Colours are specified using urwid’s colors, for example: dark red or Xresources color1. Standard Foreground and Background Colors can be found here for 16 bit palette.

Constants for 88-Color and 256-Color palettes for urwid’s hcolors.

Troubleshooting¶

hangups can log information that may be useful for troubleshooting a problem. Run hangups -h to view the default log file path.

To specify a custom log file path, run:

hangups --log /path/to/mylog

To log detailed debugging messages, run:

hangups -d

Developer Guide¶

This section is intended for developers who want to use the hangups library to write their own applications.

See the examples directory for examples of using hangups as a library.

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

static get_email()¶

Prompt for email.

Returns:	Google account email address.
Return type:	str

static get_password()¶

Prompt for password.

Returns:	Google account password.
Return type:	str

static get_verification_code()¶

Prompt for verification code.

Returns:	Google account verification code.
Return type:	str

class hangups.RefreshTokenCache(filename)¶

File-based cache for refresh token.

Parameters:	filename (str) – Path to file where refresh token will be cached.

get()¶

Get cached refresh token.

Returns:	Cached refresh token, or `None` on failure.

set(refresh_token)¶

Cache a refresh token, ignoring any failure.

Parameters:	refresh_token (str) – Refresh token to cache.

Client¶

class hangups.Client(cookies)¶

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()`.

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)¶

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.
Raises:	`hangups.NetworkError` – If the upload request failed.
Returns:	ID of the uploaded image.

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.

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.

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:	event – `Event` 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:	level – `NOTIFICATION_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:	conversation – `Conversation` 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:	event – `Event` 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:	segment – `Segment` 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_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_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_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.

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.

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.

Protocol Documentation¶

The Hangouts protocol is undocumented, as such any documentation here is unofficial and liable to be incomplete and/or incorrect.

Protocol Buffers¶

This file documents the reverse-engineered Protocol Buffers used by the Hangouts chat protocol. hangups and other projects may these Protocol Buffers to serialize and deserialize data for communicating with Google’s servers.

Some of the most important Protocol Buffer messages include:

Conversation
Entity
Event
StateUpdate

DoNotDisturbSetting¶

The state of do-not-disturb mode. Not to be confused with DndSetting, which is used to change the state of do-not-disturb mode.

Field	Number	Type	Label	Description
`do_not_disturb`	1	bool	optional	Whether do-not-disturb mode is enabled.
`expiration_timestamp`	2	uint64	optional	Timestamp when do-not-disturb mode expires.
`version`	3	uint64	optional	Timestamp when this setting was applied. Not present when this message comes from a notification.

NotificationSettings¶

Field	Number	Type	Label	Description
`dnd_settings`	1	DoNotDisturbSetting	optional

ConversationId¶

Identifies a conversation.

Field	Number	Type	Label	Description
`id`	1	string	optional	Unique identifier for a conversation.

ParticipantId¶

Identifies a user.

Field	Number	Type	Label	Description
`gaia_id`	1	string	optional	Unique identifier for a user’s Google account.
`chat_id`	2	string	optional	Seems to always be the same as gaia_id.

DeviceStatus¶

Indicates whether Hangouts is active (running in the foreground) on different types of devices.

Field	Number	Type	Label	Description
`mobile`	1	bool	optional	True if a mobile phone is active.
`desktop`	2	bool	optional	True if a desktop or laptop is active.
`tablet`	3	bool	optional	True if a tablet is active.

LastSeen¶

Field	Number	Type	Label	Description
`last_seen_timestamp_usec`	1	uint64	optional

Presence¶

Field	Number	Type	Label
`reachable`	1	bool	optional
`available`	2	bool	optional
`device_status`	6	DeviceStatus	optional
`mood_message`	9	MoodMessage	optional
`last_seen`	10	LastSeen	optional

PresenceResult¶

Field	Number	Type	Label	Description
`user_id`	1	ParticipantId	optional
`presence`	2	Presence	optional

ClientIdentifier¶

Field	Number	Type	Label	Description
`resource`	1	string	optional	(client_id in hangups).
`header_id`	2	string	optional	unknown (header_id in hangups).

ClientPresenceState¶

Field	Number	Type	Label	Description
`identifier`	1	ClientIdentifier	optional
`state`	2	ClientPresenceStateType	optional

UserEventState¶

Field	Number	Type	Label
`user_id`	1	ParticipantId	optional
`client_generated_id`	2	string	optional
`notification_level`	3	NotificationLevel	optional

Formatting¶

Field	Number	Type	Label
`bold`	1	bool	optional
`italic`	2	bool	optional
`strikethrough`	3	bool	optional
`underline`	4	bool	optional

LinkData¶

Field	Number	Type	Label	Description
`link_target`	1	string	optional

Segment¶

A segment of a message. Message are broken into segments that may be of different types and have different formatting.

Field	Number	Type	Label	Description
`type`	1	SegmentType	required	Note: This field is required because Hangouts for Chrome misbehaves if it isn’t serialized.
`text`	2	string	optional	The segment text. For line breaks, may either be empty or contain new line character.
`formatting`	3	Formatting	optional	Formatting for this segment.
`link_data`	4	LinkData	optional	Link data for this segment, if it is a link.

PlusPhoto¶

Google Plus photo that can be embedded in a chat message.

Field	Number	Type	Label	Description
`thumbnail`	1	PlusPhoto.Thumbnail	optional	Thumbnail.
`owner_obfuscated_id`	2	string	optional	Owner obfuscated ID.
`album_id`	3	string	optional	Album ID.
`photo_id`	4	string	optional	Photo ID.
`url`	6	string	optional	URL of full-sized image.
`original_content_url`	10	string	optional	URL of image thumbnail.
`media_type`	13	PlusPhoto.MediaType	optional	The media type.
`stream_id`	14	string	repeated	List of stream ID parameters.

PlusPhoto.Thumbnail¶

Metadata for displaying an image thumbnail.

Field	Number	Type	Label	Description
`url`	1	string	optional	URL to navigate to when thumbnail is selected (a Google Plus album page).
`image_url`	4	string	optional	URL of thumbnail image.
`width_px`	10	uint64	optional	Image width in pixels.
`height_px`	11	uint64	optional	Image height in pixels.

PlusPhoto.MediaType¶

Media type.

Name	Number	Description
`MEDIA_TYPE_UNKNOWN`	0
`MEDIA_TYPE_PHOTO`	1
`MEDIA_TYPE_ANIMATED_PHOTO`	4

Place¶

Place that can be embedded in a chat message via Google Maps.

Field	Number	Type	Label	Description
`url`	1	string	optional	Google Maps URL pointing to the map coordinates.
`name`	3	string	optional	Name of map location.
`representative_image`	185	Place.RepresentativeImage	optional	Representative image of the place (map with pin).

Place.RepresentativeImage¶

Representative image of a place.

Field	Number	Type	Label	Description
`url`	2	string	optional	URL of image.

EmbedItem¶

An item of some type embedded in a chat message.

Field	Number	Type	Label	Description
`type`	1	ItemType	repeated	List of embedded item types in this message.
`id`	2	string	optional	For photos this is not given, for maps, it’s the URL of the map.
`plus_photo`	27639957	PlusPhoto	optional	Embedded Google Plus photo.
`place`	35825640	Place	optional	Embedded Google Map of a place.

Attachment¶

An attachment for a chat message.

Field	Number	Type	Label	Description
`embed_item`	1	EmbedItem	optional

MessageContent¶

Chat message content.

Field	Number	Type	Label	Description
`segment`	1	Segment	repeated
`attachment`	2	Attachment	repeated

EventAnnotation¶

Annotation that can be applied to a chat message event. The only known use for this is “me” actions supported by the Chrome client (type 4).

Field	Number	Type	Label	Description
`type`	1	int32	optional	Annotation type.
`value`	2	string	optional	Optional annotation string value.

ChatMessage¶

A chat message in a conversation.

Field	Number	Type	Label	Description
`annotation`	2	EventAnnotation	repeated	Optional annotation to attach to message.
`message_content`	3	MessageContent	optional	The message’s content.

MembershipChange¶

Field	Number	Type	Label	Description
`type`	1	MembershipChangeType	optional
`participant_ids`	3	ParticipantId	repeated

ConversationRename¶

Field	Number	Type	Label	Description
`new_name`	1	string	optional
`old_name`	2	string	optional

HangoutEvent¶

Field	Number	Type	Label	Description
`event_type`	1	HangoutEventType	optional
`participant_id`	2	ParticipantId	repeated

OTRModification¶

Field	Number	Type	Label
`old_otr_status`	1	OffTheRecordStatus	optional
`new_otr_status`	2	OffTheRecordStatus	optional
`old_otr_toggle`	3	OffTheRecordToggle	optional
`new_otr_toggle`	4	OffTheRecordToggle	optional

HashModifier¶

Field	Number	Type	Label
`update_id`	1	string	optional
`hash_diff`	2	uint64	optional
`version`	4	uint64	optional

Event¶

Event that becomes part of a conversation’s history.

Field	Number	Type	Label	Description
`conversation_id`	1	ConversationId	optional	ID of the conversation this event belongs to.
`sender_id`	2	ParticipantId	optional	ID of the user that sent this event.
`timestamp`	3	uint64	optional	Timestamp when the event occurred.
`self_event_state`	4	UserEventState	optional
`source_type`	6	SourceType	optional
`chat_message`	7	ChatMessage	optional
`membership_change`	9	MembershipChange	optional
`conversation_rename`	10	ConversationRename	optional
`hangout_event`	11	HangoutEvent	optional
`event_id`	12	string	optional	Unique ID for the event.
`expiration_timestamp`	13	uint64	optional
`otr_modification`	14	OTRModification	optional
`advances_sort_timestamp`	15	bool	optional
`otr_status`	16	OffTheRecordStatus	optional
`persisted`	17	bool	optional
`medium_type`	20	DeliveryMedium	optional
`event_type`	23	EventType	optional	The event’s type.
`event_version`	24	uint64	optional	Event version timestamp.
`hash_modifier`	26	HashModifier	optional
`group_link_sharing_modification`	31	GroupLinkSharingModification	optional

UserReadState¶

Field	Number	Type	Label	Description
`participant_id`	1	ParticipantId	optional
`latest_read_timestamp`	2	uint64	optional

DeliveryMedium¶

Field	Number	Type	Label	Description
`medium_type`	1	DeliveryMediumType	optional
`phone_number`	2	PhoneNumber	optional	Phone number to use for sending Google Voice messages.

DeliveryMediumOption¶

Field	Number	Type	Label	Description
`delivery_medium`	1	DeliveryMedium	optional
`current_default`	2	bool	optional

UserConversationState¶

Field	Number	Type	Label
`client_generated_id`	2	string	optional
`self_read_state`	7	UserReadState	optional
`status`	8	ConversationStatus	optional
`notification_level`	9	NotificationLevel	optional
`view`	10	ConversationView	repeated
`inviter_id`	11	ParticipantId	optional
`invite_timestamp`	12	uint64	optional
`sort_timestamp`	13	uint64	optional
`active_timestamp`	14	uint64	optional
`invite_affinity`	15	InvitationAffinity	optional
`delivery_medium_option`	17	DeliveryMediumOption	repeated

ConversationParticipantData¶

Field	Number	Type	Label
`id`	1	ParticipantId	optional
`fallback_name`	2	string	optional
`invitation_status`	3	InvitationStatus	optional
`participant_type`	5	ParticipantType	optional
`new_invitation_status`	6	InvitationStatus	optional

Conversation¶

A conversation between two or more users.

Field	Number	Type	Label	Description
`conversation_id`	1	ConversationId	optional
`type`	2	ConversationType	optional
`name`	3	string	optional
`self_conversation_state`	4	UserConversationState	optional
`read_state`	8	UserReadState	repeated
`has_active_hangout`	9	bool	optional	True if the conversation has an active Hangout.
`otr_status`	10	OffTheRecordStatus	optional	The conversation’s “off the record” status.
`otr_toggle`	11	OffTheRecordToggle	optional	Whether the OTR toggle is available to the user for this conversation.
`conversation_history_supported`	12	bool	optional
`current_participant`	13	ParticipantId	repeated
`participant_data`	14	ConversationParticipantData	repeated
`network_type`	18	NetworkType	repeated
`force_history_state`	19	ForceHistory	optional
`group_link_sharing_status`	22	GroupLinkSharingStatus	optional

EasterEgg¶

Field	Number	Type	Label	Description
`message`	1	string	optional

BlockStateChange¶

Field	Number	Type	Label	Description
`participant_id`	1	ParticipantId	optional
`new_block_state`	2	BlockState	optional

Photo¶

Field	Number	Type	Label	Description
`photo_id`	1	string	optional	Picasa photo ID.
`delete_albumless_source_photo`	2	bool	optional
`user_id`	3	string	optional	Optional Picasa user ID needed for photos from other accounts (eg. stickers).
`is_custom_user_id`	4	bool	optional	Must be true if user_id is specified.

ExistingMedia¶

Field	Number	Type	Label	Description
`photo`	1	Photo	optional

EventRequestHeader¶

Field	Number	Type	Label
`conversation_id`	1	ConversationId	optional
`client_generated_id`	2	uint64	optional
`expected_otr`	3	OffTheRecordStatus	optional
`delivery_medium`	4	DeliveryMedium	optional
`event_type`	5	EventType	optional

ClientVersion¶

The client and device version.

Field	Number	Type	Label	Description
`client_id`	1	ClientId	optional	Identifies the client.
`build_type`	2	ClientBuildType	optional	The client build type.
`major_version`	3	string	optional	Client version.
`version_timestamp`	4	uint64	optional	Client version timestamp.
`device_os_version`	5	string	optional	OS version string (for native apps).
`device_hardware`	6	string	optional	Device hardware name (for native apps).

RequestHeader¶

Header for requests from the client to the server.

Field	Number	Type	Label
`client_version`	1	ClientVersion	optional
`client_identifier`	2	ClientIdentifier	optional
`language_code`	4	string	optional

ResponseHeader¶

Header for responses from the server to the client.

Field	Number	Type	Label
`status`	1	ResponseStatus	optional
`error_description`	2	string	optional
`debug_url`	3	string	optional
`request_trace_id`	4	string	optional
`current_server_time`	5	uint64	optional

Entity¶

A user that can participate in conversations.

Field	Number	Type	Label	Description
`id`	9	ParticipantId	optional	The user’s ID.
`presence`	8	Presence	optional	Optional user presence status.
`properties`	10	EntityProperties	optional	Optional user properties.
`entity_type`	13	ParticipantType	optional
`had_past_hangout_state`	16	Entity.PastHangoutState	optional

Entity.PastHangoutState¶

Name	Number	Description
`PAST_HANGOUT_STATE_UNKNOWN`	0
`PAST_HANGOUT_STATE_HAD_PAST_HANGOUT`	1
`PAST_HANGOUT_STATE_NO_PAST_HANGOUT`	2

EntityProperties¶

Field	Number	Type	Label	Description
`type`	1	ProfileType	optional
`display_name`	2	string	optional
`first_name`	3	string	optional
`photo_url`	4	string	optional	Photo URL with protocol scheme omitted (eg. “//lh.googleusercontent.com/...”).
`email`	5	string	repeated
`phone`	6	string	repeated
`in_users_domain`	10	bool	optional
`gender`	11	Gender	optional
`photo_url_status`	12	PhotoUrlStatus	optional
`canonical_email`	15	string	optional

ConversationState¶

State of a conversation and recent events.

Field	Number	Type	Label
`conversation_id`	1	ConversationId	optional
`conversation`	2	Conversation	optional
`event`	3	Event	repeated
`event_continuation_token`	5	EventContinuationToken	optional

EventContinuationToken¶

Token that allows retrieving more events from a position in a conversation. Specifying event_timestamp is sufficient.

Field	Number	Type	Label
`event_id`	1	string	optional
`storage_continuation_token`	2	bytes	optional
`event_timestamp`	3	uint64	optional

EntityLookupSpec¶

Specifies an entity to lookup by one of its properties.

Field	Number	Type	Label	Description
`gaia_id`	1	string	optional
`email`	3	string	optional
`phone`	4	string	optional	Phone number as string (eg. “+15551234567”).
`create_offnetwork_gaia`	6	bool	optional	Whether create a gaia_id for off-network contacts (eg. Google Voice contacts).

ConfigurationBit¶

Field	Number	Type	Label	Description
`configuration_bit_type`	1	ConfigurationBitType	optional
`value`	2	bool	optional

RichPresenceState¶

Field	Number	Type	Label	Description
`get_rich_presence_enabled_state`	3	RichPresenceEnabledState	repeated

RichPresenceEnabledState¶

Field	Number	Type	Label	Description
`type`	1	RichPresenceType	optional
`enabled`	2	bool	optional

DesktopOffSetting¶

Field	Number	Type	Label	Description
`desktop_off`	1	bool	optional	State of “desktop off” setting.

DesktopOffState¶

Field	Number	Type	Label	Description
`desktop_off`	1	bool	optional	Whether Hangouts desktop is signed off or on.
`version`	2	uint64	optional

DndSetting¶

Enable or disable do-not-disturb mode. Not to be confused with DoNotDisturbSetting, which is used to indicate the state of do-not-disturb mode.

Field	Number	Type	Label	Description
`do_not_disturb`	1	bool	optional	Whether to enable or disable do-not-disturb mode.
`timeout_secs`	2	uint64	optional	Do not disturb expiration in seconds.

PresenceStateSetting¶

Field	Number	Type	Label	Description
`timeout_secs`	1	uint64	optional
`type`	2	ClientPresenceStateType	optional

MoodMessage¶

Field	Number	Type	Label	Description
`mood_content`	1	MoodContent	optional

MoodContent¶

Field	Number	Type	Label	Description
`segment`	1	Segment	repeated

MoodSetting¶

The user’s mood message.

Field	Number	Type	Label	Description
`mood_message`	1	MoodMessage	optional

MoodState¶

Field	Number	Type	Label	Description
`mood_setting`	4	MoodSetting	optional

DeleteAction¶

Field	Number	Type	Label
`delete_action_timestamp`	1	uint64	optional
`delete_upper_bound_timestamp`	2	uint64	optional
`delete_type`	3	DeleteType	optional

InviteeID¶

Field	Number	Type	Label	Description
`gaia_id`	1	string	optional
`fallback_name`	4	string	optional

Country¶

Describes a user’s country.

Field	Number	Type	Label	Description
`region_code`	1	string	optional	Abbreviated region code (eg. “CA”).
`country_code`	2	uint64	optional	Country’s calling code (eg. “1”).

DesktopSoundSetting¶

Sound settings in the desktop Hangouts client.

Field	Number	Type	Label	Description
`desktop_sound_state`	1	SoundState	optional	Whether to play sound for incoming messages.
`desktop_ring_sound_state`	2	SoundState	optional	Whether to ring for incoming calls.

PhoneData¶

Field	Number	Type	Label	Description
`phone`	1	Phone	repeated
`caller_id_settings_mask`	3	CallerIdSettingsMask	optional

Phone¶

Field	Number	Type	Label
`phone_number`	1	PhoneNumber	optional
`google_voice`	2	bool	optional
`verification_status`	3	PhoneVerificationStatus	optional
`discoverable`	4	bool	optional
`discoverability_status`	5	PhoneDiscoverabilityStatus	optional
`primary`	6	bool	optional

I18nData¶

Field	Number	Type	Label
`national_number`	1	string	optional
`international_number`	2	string	optional
`country_code`	3	uint64	optional
`region_code`	4	string	optional
`is_valid`	5	bool	optional
`validation_result`	6	PhoneValidationResult	optional

PhoneNumber¶

Field	Number	Type	Label	Description
`e164`	1	string	optional	Phone number as string (eg. “+15551234567”).
`i18n_data`	2	I18nData	optional

SuggestedContactGroupHash¶

Field	Number	Type	Label	Description
`max_results`	1	uint64	optional	Number of results to return from this group.
`hash`	2	bytes	optional	An optional 4-byte hash. If this matches the server’s hash, no results will be sent.

SuggestedContact¶

Field	Number	Type	Label	Description
`entity`	1	Entity	optional	The contact’s entity.
`invitation_status`	2	InvitationStatus	optional	The contact’s invitation status.

SuggestedContactGroup¶

Field	Number	Type	Label	Description
`hash_matched`	1	bool	optional	True if the request’s hash matched and no contacts will be included.
`hash`	2	bytes	optional	A 4-byte hash which can be used in subsequent requests.
`contact`	3	SuggestedContact	repeated	List of contacts in this group.

GroupLinkSharingModification¶

Field	Number	Type	Label	Description
`new_status`	1	GroupLinkSharingStatus	optional

StateUpdate¶

Pushed from the server to the client to notify it of state changes. Includes exactly one type of notification, and optionally updates the attributes of a conversation.

Field	Number	Type	Label	Description
`state_update_header`	1	StateUpdateHeader	optional
`conversation`	13	Conversation	optional	If set, includes conversation attributes that have been updated by the notification.
`conversation_notification`	2	ConversationNotification	optional
`event_notification`	3	EventNotification	optional
`focus_notification`	4	SetFocusNotification	optional
`typing_notification`	5	SetTypingNotification	optional
`notification_level_notification`	6	SetConversationNotificationLevelNotification	optional
`reply_to_invite_notification`	7	ReplyToInviteNotification	optional
`watermark_notification`	8	WatermarkNotification	optional
`view_modification`	11	ConversationViewModification	optional
`easter_egg_notification`	12	EasterEggNotification	optional
`self_presence_notification`	14	SelfPresenceNotification	optional
`delete_notification`	15	DeleteActionNotification	optional
`presence_notification`	16	PresenceNotification	optional
`block_notification`	17	BlockNotification	optional
`notification_setting_notification`	19	SetNotificationSettingNotification	optional
`rich_presence_enabled_state_notification`	20	RichPresenceEnabledStateNotification	optional

StateUpdateHeader¶

Header for StateUpdate messages.

Field	Number	Type	Label
`active_client_state`	1	ActiveClientState	optional
`request_trace_id`	3	string	optional
`notification_settings`	4	NotificationSettings	optional
`current_server_time`	5	uint64	optional

BatchUpdate¶

List of StateUpdate messages to allow pushing multiple notifications from the server to the client simultaneously.

Field	Number	Type	Label	Description
`state_update`	1	StateUpdate	repeated

ConversationNotification¶

Field	Number	Type	Label	Description
`conversation`	1	Conversation	optional

EventNotification¶

Field	Number	Type	Label	Description
`event`	1	Event	optional

SetFocusNotification¶

Field	Number	Type	Label
`conversation_id`	1	ConversationId	optional
`sender_id`	2	ParticipantId	optional
`timestamp`	3	uint64	optional
`type`	4	FocusType	optional
`device`	5	FocusDevice	optional

SetTypingNotification¶

Field	Number	Type	Label
`conversation_id`	1	ConversationId	optional
`sender_id`	2	ParticipantId	optional
`timestamp`	3	uint64	optional
`type`	4	TypingType	optional

SetConversationNotificationLevelNotification¶

Field	Number	Type	Label
`conversation_id`	1	ConversationId	optional
`level`	2	NotificationLevel	optional
`timestamp`	4	uint64	optional

ReplyToInviteNotification¶

Field	Number	Type	Label	Description
`conversation_id`	1	ConversationId	optional
`type`	2	ReplyToInviteType	optional

WatermarkNotification¶

Field	Number	Type	Label
`sender_id`	1	ParticipantId	optional
`conversation_id`	2	ConversationId	optional
`latest_read_timestamp`	3	uint64	optional

ConversationViewModification¶

Field	Number	Type	Label
`conversation_id`	1	ConversationId	optional
`old_view`	2	ConversationView	optional
`new_view`	3	ConversationView	optional

EasterEggNotification¶

Field	Number	Type	Label
`sender_id`	1	ParticipantId	optional
`conversation_id`	2	ConversationId	optional
`easter_egg`	3	EasterEgg	optional

SelfPresenceNotification¶

Notifies the status of other clients and mood.

Field	Number	Type	Label
`client_presence_state`	1	ClientPresenceState	optional
`do_not_disturb_setting`	3	DoNotDisturbSetting	optional
`desktop_off_setting`	4	DesktopOffSetting	optional
`desktop_off_state`	5	DesktopOffState	optional
`mood_state`	6	MoodState	optional

DeleteActionNotification¶

Field	Number	Type	Label	Description
`conversation_id`	1	ConversationId	optional
`delete_action`	2	DeleteAction	optional

PresenceNotification¶

Field	Number	Type	Label	Description
`presence`	1	PresenceResult	repeated

BlockNotification¶

Field	Number	Type	Label	Description
`block_state_change`	1	BlockStateChange	repeated

SetNotificationSettingNotification¶

Field	Number	Type	Label	Description
`configuration_bit`	1	ConfigurationBit	repeated
`desktop_sound_setting`	2	DesktopSoundSetting	optional

RichPresenceEnabledStateNotification¶

Field	Number	Type	Label	Description
`rich_presence_enabled_state`	1	RichPresenceEnabledState	repeated

ConversationSpec¶

Field	Number	Type	Label	Description
`conversation_id`	1	ConversationId	optional

OffnetworkAddress¶

Field	Number	Type	Label	Description
`type`	1	OffnetworkAddressType	optional
`email`	3	string	optional

EntityResult¶

Field	Number	Type	Label	Description
`lookup_spec`	1	EntityLookupSpec	optional
`entity`	2	Entity	repeated

AddUserRequest¶

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`invitee_id`	3	InviteeID	repeated
`event_request_header`	5	EventRequestHeader	optional

AddUserResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`created_event`	5	Event	optional

CreateConversationRequest¶

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`type`	2	ConversationType	optional
`client_generated_id`	3	uint64	optional
`name`	4	string	optional
`invitee_id`	5	InviteeID	repeated

CreateConversationResponse¶

Field	Number	Type	Label
`response_header`	1	ResponseHeader	optional
`conversation`	2	Conversation	optional
`new_conversation_created`	7	bool	optional

DeleteConversationRequest¶

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`conversation_id`	2	ConversationId	optional
`delete_upper_bound_timestamp`	3	uint64	optional

DeleteConversationResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`delete_action`	2	DeleteAction	optional

EasterEggRequest¶

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`conversation_id`	2	ConversationId	optional
`easter_egg`	3	EasterEgg	optional

EasterEggResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`timestamp`	2	uint64	optional

GetConversationRequest¶

Field	Number	Type	Label	Description
`request_header`	1	RequestHeader	optional
`conversation_spec`	2	ConversationSpec	optional
`include_conversation_metadata`	3	bool	optional	Whether the ConversationState in the response should include metadata other than the conversation ID (default true).
`include_event`	4	bool	optional	Whether to include list of events in the response (default true).
`max_events_per_conversation`	6	uint64	optional
`event_continuation_token`	7	EventContinuationToken	optional

GetConversationResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`conversation_state`	2	ConversationState	optional

GetEntityByIdRequest¶

Field	Number	Type	Label	Description
`request_header`	1	RequestHeader	optional
`batch_lookup_spec`	3	EntityLookupSpec	repeated

GetEntityByIdResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`entity`	2	Entity	repeated	Resulting entities of PARTICIPANT_TYPE_GAIA only.
`entity_result`	3	EntityResult	repeated	All resulting entities.

GetGroupConversationUrlRequest¶

Field	Number	Type	Label	Description
`request_header`	1	RequestHeader	optional
`conversation_id`	2	ConversationId	optional	Conversation to retrieve URL for.

GetGroupConversationUrlResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`group_conversation_url`	2	string	optional	URL for others to join conversation.

GetSuggestedEntitiesRequest¶

Field	Number	Type	Label	Description
`request_header`	1	RequestHeader	optional
`max_count`	4	uint64	optional	Max number of non-grouped entities to return.
`favorites`	8	SuggestedContactGroupHash	optional	Optional hash for “favorites” contact group.
`contacts_you_hangout_with`	9	SuggestedContactGroupHash	optional	Optional hash for “contacts you hangout with” contact group.
`other_contacts_on_hangouts`	10	SuggestedContactGroupHash	optional	Optional hash for “other contacts on hangouts” contact group.
`other_contacts`	11	SuggestedContactGroupHash	optional	Optional hash for “other contacts” contact group.
`dismissed_contacts`	12	SuggestedContactGroupHash	optional	Optional hash for “dismissed contacts” contact group.
`pinned_favorites`	13	SuggestedContactGroupHash	optional	Optional hash for “pinned favorites” contact group.

GetSuggestedEntitiesResponse¶

Field	Number	Type	Label
`response_header`	1	ResponseHeader	optional
`entity`	2	Entity	repeated
`favorites`	4	SuggestedContactGroup	optional
`contacts_you_hangout_with`	5	SuggestedContactGroup	optional
`other_contacts_on_hangouts`	6	SuggestedContactGroup	optional
`other_contacts`	7	SuggestedContactGroup	optional
`dismissed_contacts`	8	SuggestedContactGroup	optional
`pinned_favorites`	9	SuggestedContactGroup	optional

GetSelfInfoRequest¶

Field	Number	Type	Label	Description
`request_header`	1	RequestHeader	optional

GetSelfInfoResponse¶

Field	Number	Type	Label
`response_header`	1	ResponseHeader	optional
`self_entity`	2	Entity	optional
`is_known_minor`	3	bool	optional
`dnd_state`	5	DoNotDisturbSetting	optional
`desktop_off_setting`	6	DesktopOffSetting	optional
`phone_data`	7	PhoneData	optional
`configuration_bit`	8	ConfigurationBit	repeated
`desktop_off_state`	9	DesktopOffState	optional
`google_plus_user`	10	bool	optional
`desktop_sound_setting`	11	DesktopSoundSetting	optional
`rich_presence_state`	12	RichPresenceState	optional
`default_country`	19	Country	optional

QueryPresenceRequest¶

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`participant_id`	2	ParticipantId	repeated
`field_mask`	3	FieldMask	repeated

QueryPresenceResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`presence_result`	2	PresenceResult	repeated

RemoveUserRequest¶

Field	Number	Type	Label	Description
`request_header`	1	RequestHeader	optional
`participant_id`	3	ParticipantId	optional	Optional participant to remove from conversation, yourself if not given.
`event_request_header`	5	EventRequestHeader	optional

RemoveUserResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`created_event`	4	Event	optional

RenameConversationRequest¶

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`new_name`	3	string	optional
`event_request_header`	5	EventRequestHeader	optional

RenameConversationResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`created_event`	4	Event	optional

SearchEntitiesRequest¶

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`query`	3	string	optional
`max_count`	4	uint64	optional

SearchEntitiesResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`entity`	2	Entity	repeated

SendChatMessageRequest¶

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`annotation`	5	EventAnnotation	repeated
`message_content`	6	MessageContent	optional
`existing_media`	7	ExistingMedia	optional
`event_request_header`	8	EventRequestHeader	optional

SendChatMessageResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`created_event`	6	Event	optional

ModifyOTRStatusRequest¶

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`otr_status`	3	OffTheRecordStatus	optional
`event_request_header`	5	EventRequestHeader	optional

ModifyOTRStatusResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`created_event`	4	Event	optional

SendOffnetworkInvitationRequest¶

Field	Number	Type	Label	Description
`request_header`	1	RequestHeader	optional
`invitee_address`	2	OffnetworkAddress	optional

SendOffnetworkInvitationResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional

SetActiveClientRequest¶

Field	Number	Type	Label	Description
`request_header`	1	RequestHeader	optional
`is_active`	2	bool	optional	Whether to set the client as active or inactive.
`full_jid`	3	string	optional	‘email/resource’.
`timeout_secs`	4	uint64	optional	Timeout in seconds for client to remain active.

SetActiveClientResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional

SetConversationLevelRequest¶

Field	Number	Type	Label	Description
`request_header`	1	RequestHeader	optional

SetConversationLevelResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional

SetConversationNotificationLevelRequest¶

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`conversation_id`	2	ConversationId	optional
`level`	3	NotificationLevel	optional

SetConversationNotificationLevelResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`timestamp`	2	uint64	optional

SetFocusRequest¶

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`conversation_id`	2	ConversationId	optional
`type`	3	FocusType	optional
`timeout_secs`	4	uint32	optional

SetFocusResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`timestamp`	2	uint64	optional

SetGroupLinkSharingEnabledRequest¶

Field	Number	Type	Label	Description
`request_header`	1	RequestHeader	optional
`event_request_header`	2	EventRequestHeader	optional
`group_link_sharing_status`	4	GroupLinkSharingStatus	optional	New group link sharing status.

SetGroupLinkSharingEnabledResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`created_event`	2	Event	optional	Created event of type EVENT_TYPE_GROUP_LINK_SHARING_MODIFICATION.
`updated_conversation`	3	Conversation	optional	Updated conversation.

SetPresenceRequest¶

Allows setting one or more of the included presence-related settings.

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`presence_state_setting`	2	PresenceStateSetting	optional
`dnd_setting`	3	DndSetting	optional
`desktop_off_setting`	5	DesktopOffSetting	optional
`mood_setting`	8	MoodSetting	optional

SetPresenceResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional

SetTypingRequest¶

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`conversation_id`	2	ConversationId	optional
`type`	3	TypingType	optional

SetTypingResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional
`timestamp`	2	uint64	optional

SyncAllNewEventsRequest¶

Field	Number	Type	Label	Description
`request_header`	1	RequestHeader	optional
`last_sync_timestamp`	2	uint64	optional	Timestamp after which to return all new events.
`max_response_size_bytes`	8	uint64	optional

SyncAllNewEventsResponse¶

Field	Number	Type	Label
`response_header`	1	ResponseHeader	optional
`sync_timestamp`	2	uint64	optional
`conversation_state`	3	ConversationState	repeated

SyncRecentConversationsRequest¶

Field	Number	Type	Label	Description
`request_header`	1	RequestHeader	optional
`last_event_timestamp`	2	uint64	optional	Timestamp used for pagination, returns most recent conversations if not given.
`max_conversations`	3	uint64	optional
`max_events_per_conversation`	4	uint64	optional
`sync_filter`	5	SyncFilter	repeated

SyncRecentConversationsResponse¶

Field	Number	Type	Label
`response_header`	1	ResponseHeader	optional
`sync_timestamp`	2	uint64	optional
`conversation_state`	3	ConversationState	repeated
`continuation_end_timestamp`	4	uint64	optional

UpdateWatermarkRequest¶

Field	Number	Type	Label
`request_header`	1	RequestHeader	optional
`conversation_id`	2	ConversationId	optional
`last_read_timestamp`	3	uint64	optional

UpdateWatermarkResponse¶

Field	Number	Type	Label	Description
`response_header`	1	ResponseHeader	optional

ActiveClientState¶

Describes which Hangouts client is active.

Name	Number	Description
`ACTIVE_CLIENT_STATE_NO_ACTIVE`	0	No client is active.
`ACTIVE_CLIENT_STATE_IS_ACTIVE`	1	This is the active client.
`ACTIVE_CLIENT_STATE_OTHER_ACTIVE`	2	Other client is active.

FocusType¶

Name	Number	Description
`FOCUS_TYPE_UNKNOWN`	0
`FOCUS_TYPE_FOCUSED`	1
`FOCUS_TYPE_UNFOCUSED`	2

FocusDevice¶

Name	Number	Description
`FOCUS_DEVICE_UNSPECIFIED`	0
`FOCUS_DEVICE_DESKTOP`	20
`FOCUS_DEVICE_MOBILE`	300

TypingType¶

Name	Number	Description
`TYPING_TYPE_UNKNOWN`	0
`TYPING_TYPE_STARTED`	1	Started typing.
`TYPING_TYPE_PAUSED`	2	Stopped typing with inputted text.
`TYPING_TYPE_STOPPED`	3	Stopped typing with no inputted text.

ClientPresenceStateType¶

Name	Number	Description
`CLIENT_PRESENCE_STATE_UNKNOWN`	0
`CLIENT_PRESENCE_STATE_NONE`	1
`CLIENT_PRESENCE_STATE_DESKTOP_IDLE`	30
`CLIENT_PRESENCE_STATE_DESKTOP_ACTIVE`	40

NotificationLevel¶

Name	Number	Description
`NOTIFICATION_LEVEL_UNKNOWN`	0
`NOTIFICATION_LEVEL_QUIET`	10	Notifications are disabled.
`NOTIFICATION_LEVEL_RING`	30	Notifications are enabled.

SegmentType¶

Name	Number	Description
`SEGMENT_TYPE_TEXT`	0	Segment is text.
`SEGMENT_TYPE_LINE_BREAK`	1	Segment is a line break.
`SEGMENT_TYPE_LINK`	2	Segment is hyperlinked text.

ItemType¶

A type of embedded item.

Name	Number	Description
`ITEM_TYPE_THING`	0
`ITEM_TYPE_PLUS_PHOTO`	249	Google Plus photo.
`ITEM_TYPE_PLACE`	335
`ITEM_TYPE_PLACE_V2`	340	Google Map place.

MembershipChangeType¶

Name	Number	Description
`MEMBERSHIP_CHANGE_TYPE_JOIN`	1
`MEMBERSHIP_CHANGE_TYPE_LEAVE`	2

HangoutEventType¶

Name	Number	Description
`HANGOUT_EVENT_TYPE_UNKNOWN`	0
`HANGOUT_EVENT_TYPE_START`	1
`HANGOUT_EVENT_TYPE_END`	2
`HANGOUT_EVENT_TYPE_JOIN`	3
`HANGOUT_EVENT_TYPE_LEAVE`	4
`HANGOUT_EVENT_TYPE_COMING_SOON`	5
`HANGOUT_EVENT_TYPE_ONGOING`	6

OffTheRecordToggle¶

Whether the OTR toggle is available to the user.

Name	Number	Description
`OFF_THE_RECORD_TOGGLE_UNKNOWN`	0
`OFF_THE_RECORD_TOGGLE_ENABLED`	1
`OFF_THE_RECORD_TOGGLE_DISABLED`	2

OffTheRecordStatus¶

Name	Number	Description
`OFF_THE_RECORD_STATUS_UNKNOWN`	0
`OFF_THE_RECORD_STATUS_OFF_THE_RECORD`	1	Conversation is off-the-record (history disabled).
`OFF_THE_RECORD_STATUS_ON_THE_RECORD`	2	Conversation is on-the-record (history enabled).

SourceType¶

Name	Number	Description
`SOURCE_TYPE_UNKNOWN`	0

EventType¶

Name	Number	Description
`EVENT_TYPE_UNKNOWN`	0
`EVENT_TYPE_REGULAR_CHAT_MESSAGE`	1
`EVENT_TYPE_SMS`	2
`EVENT_TYPE_VOICEMAIL`	3
`EVENT_TYPE_ADD_USER`	4
`EVENT_TYPE_REMOVE_USER`	5
`EVENT_TYPE_CONVERSATION_RENAME`	6
`EVENT_TYPE_HANGOUT`	7
`EVENT_TYPE_PHONE_CALL`	8
`EVENT_TYPE_OTR_MODIFICATION`	9
`EVENT_TYPE_PLAN_MUTATION`	10
`EVENT_TYPE_MMS`	11
`EVENT_TYPE_DEPRECATED_12`	12
`EVENT_TYPE_OBSERVED_EVENT`	13
`EVENT_TYPE_GROUP_LINK_SHARING_MODIFICATION`	14

ConversationType¶

Name	Number	Description
`CONVERSATION_TYPE_UNKNOWN`	0
`CONVERSATION_TYPE_ONE_TO_ONE`	1	Conversation is one-to-one (only 2 participants).
`CONVERSATION_TYPE_GROUP`	2	Conversation is group (any number of participants).

ConversationStatus¶

Name	Number	Description
`CONVERSATION_STATUS_UNKNOWN`	0
`CONVERSATION_STATUS_INVITED`	1	User is invited to conversation.
`CONVERSATION_STATUS_ACTIVE`	2	User is participating in conversation.
`CONVERSATION_STATUS_LEFT`	3	User has left conversation.

ConversationView¶

Name	Number	Description
`CONVERSATION_VIEW_UNKNOWN`	0
`CONVERSATION_VIEW_INBOX`	1	Conversation is in inbox.
`CONVERSATION_VIEW_ARCHIVED`	2	Conversation has been archived.

DeliveryMediumType¶

Name	Number	Description
`DELIVERY_MEDIUM_UNKNOWN`	0
`DELIVERY_MEDIUM_BABEL`	1
`DELIVERY_MEDIUM_GOOGLE_VOICE`	2
`DELIVERY_MEDIUM_LOCAL_SMS`	3

InvitationAffinity¶

Name	Number	Description
`INVITE_AFFINITY_UNKNOWN`	0
`INVITE_AFFINITY_HIGH`	1
`INVITE_AFFINITY_LOW`	2

ParticipantType¶

Name	Number	Description
`PARTICIPANT_TYPE_UNKNOWN`	0
`PARTICIPANT_TYPE_GAIA`	2
`PARTICIPANT_TYPE_GOOGLE_VOICE`	3

InvitationStatus¶

Name	Number	Description
`INVITATION_STATUS_UNKNOWN`	0
`INVITATION_STATUS_PENDING`	1
`INVITATION_STATUS_ACCEPTED`	2

ForceHistory¶

Name	Number	Description
`FORCE_HISTORY_UNKNOWN`	0
`FORCE_HISTORY_NO`	1

NetworkType¶

Name	Number	Description
`NETWORK_TYPE_UNKNOWN`	0
`NETWORK_TYPE_BABEL`	1
`NETWORK_TYPE_GOOGLE_VOICE`	2

BlockState¶

Name	Number	Description
`BLOCK_STATE_UNKNOWN`	0
`BLOCK_STATE_BLOCK`	1
`BLOCK_STATE_UNBLOCK`	2

ReplyToInviteType¶

Name	Number	Description
`REPLY_TO_INVITE_TYPE_UNKNOWN`	0
`REPLY_TO_INVITE_TYPE_ACCEPT`	1
`REPLY_TO_INVITE_TYPE_DECLINE`	2

ClientId¶

Identifies the client.

Name	Number	Description
`CLIENT_ID_UNKNOWN`	0
`CLIENT_ID_ANDROID`	1	Hangouts app for Android.
`CLIENT_ID_IOS`	2	Hangouts app for iOS.
`CLIENT_ID_CHROME`	3	Hangouts Chrome extension.
`CLIENT_ID_WEB_GPLUS`	5	Hangouts web interface in Google Plus.
`CLIENT_ID_WEB_GMAIL`	6	Hangouts web interface in Gmail.
`CLIENT_ID_ULTRAVIOLET`	13	Hangouts Chrome app (“ultraviolet”).
`CLIENT_ID_WEB_HANGOUTS`	44	Hangouts web app (https://hangouts.google.com).

ClientBuildType¶

Build type of the client.

Name	Number	Description
`BUILD_TYPE_UNKNOWN`	0
`BUILD_TYPE_PRODUCTION_WEB`	1	Web app (not used anymore?).
`BUILD_TYPE_PRODUCTION_APP`	3	Native app.

ResponseStatus¶

Status of the response from the server to the client.

Name	Number	Description
`RESPONSE_STATUS_UNKNOWN`	0
`RESPONSE_STATUS_OK`	1
`RESPONSE_STATUS_UNEXPECTED_ERROR`	3
`RESPONSE_STATUS_INVALID_REQUEST`	4

PhotoUrlStatus¶

Status of EntityProperties.photo_url.

Name	Number	Description
`PHOTO_URL_STATUS_UNKNOWN`	0
`PHOTO_URL_STATUS_PLACEHOLDER`	1	URL is a placeholder.
`PHOTO_URL_STATUS_USER_PHOTO`	2	URL is a photo set by the user.

Gender¶

Name	Number	Description
`GENDER_UNKNOWN`	0
`GENDER_MALE`	1
`GENDER_FEMALE`	2

ProfileType¶

Name	Number	Description
`PROFILE_TYPE_NONE`	0
`PROFILE_TYPE_ES_USER`	1

ConfigurationBitType¶

A type of binary configuration option.

Name	Number	Description
`CONFIGURATION_BIT_TYPE_UNKNOWN`	0
`CONFIGURATION_BIT_TYPE_UNKNOWN_1`	1
`CONFIGURATION_BIT_TYPE_UNKNOWN_2`	2
`CONFIGURATION_BIT_TYPE_UNKNOWN_3`	3
`CONFIGURATION_BIT_TYPE_UNKNOWN_4`	4
`CONFIGURATION_BIT_TYPE_UNKNOWN_5`	5
`CONFIGURATION_BIT_TYPE_UNKNOWN_6`	6
`CONFIGURATION_BIT_TYPE_UNKNOWN_7`	7
`CONFIGURATION_BIT_TYPE_UNKNOWN_8`	8
`CONFIGURATION_BIT_TYPE_UNKNOWN_9`	9
`CONFIGURATION_BIT_TYPE_UNKNOWN_10`	10
`CONFIGURATION_BIT_TYPE_UNKNOWN_11`	11
`CONFIGURATION_BIT_TYPE_UNKNOWN_12`	12
`CONFIGURATION_BIT_TYPE_UNKNOWN_13`	13
`CONFIGURATION_BIT_TYPE_UNKNOWN_14`	14
`CONFIGURATION_BIT_TYPE_UNKNOWN_15`	15
`CONFIGURATION_BIT_TYPE_UNKNOWN_16`	16
`CONFIGURATION_BIT_TYPE_UNKNOWN_17`	17
`CONFIGURATION_BIT_TYPE_UNKNOWN_18`	18
`CONFIGURATION_BIT_TYPE_UNKNOWN_19`	19
`CONFIGURATION_BIT_TYPE_UNKNOWN_20`	20
`CONFIGURATION_BIT_TYPE_UNKNOWN_21`	21
`CONFIGURATION_BIT_TYPE_UNKNOWN_22`	22
`CONFIGURATION_BIT_TYPE_UNKNOWN_23`	23
`CONFIGURATION_BIT_TYPE_UNKNOWN_24`	24
`CONFIGURATION_BIT_TYPE_UNKNOWN_25`	25
`CONFIGURATION_BIT_TYPE_UNKNOWN_26`	26
`CONFIGURATION_BIT_TYPE_UNKNOWN_27`	27
`CONFIGURATION_BIT_TYPE_UNKNOWN_28`	28
`CONFIGURATION_BIT_TYPE_UNKNOWN_29`	29
`CONFIGURATION_BIT_TYPE_UNKNOWN_30`	30
`CONFIGURATION_BIT_TYPE_UNKNOWN_31`	31
`CONFIGURATION_BIT_TYPE_UNKNOWN_32`	32
`CONFIGURATION_BIT_TYPE_UNKNOWN_33`	33
`CONFIGURATION_BIT_TYPE_DESKTOP_AUTO_EMOJI_CONVERSION_ENABLED`	34
`CONFIGURATION_BIT_TYPE_UNKNOWN_35`	35
`CONFIGURATION_BIT_TYPE_UNKNOWN_36`	36
`CONFIGURATION_BIT_TYPE_DESKTOP_COMPACT_MODE_ENABLED`	38

RichPresenceType¶

Name	Number	Description
`RICH_PRESENCE_TYPE_UNKNOWN`	0
`RICH_PRESENCE_TYPE_IN_CALL_STATE`	1
`RICH_PRESENCE_TYPE_UNKNOWN_3`	3
`RICH_PRESENCE_TYPE_UNKNOWN_4`	4
`RICH_PRESENCE_TYPE_UNKNOWN_5`	5
`RICH_PRESENCE_TYPE_DEVICE`	2
`RICH_PRESENCE_TYPE_LAST_SEEN`	6

FieldMask¶

Name	Number	Description
`FIELD_MASK_REACHABLE`	1
`FIELD_MASK_AVAILABLE`	2
`FIELD_MASK_MOOD`	3
`FIELD_MASK_IN_CALL`	6
`FIELD_MASK_DEVICE`	7
`FIELD_MASK_LAST_SEEN`	10

DeleteType¶

Name	Number	Description
`DELETE_TYPE_UNKNOWN`	0
`DELETE_TYPE_UPPER_BOUND`	1

SyncFilter¶

Name	Number	Description
`SYNC_FILTER_UNKNOWN`	0
`SYNC_FILTER_INBOX`	1
`SYNC_FILTER_ARCHIVED`	2

SoundState¶

Name	Number	Description
`SOUND_STATE_UNKNOWN`	0
`SOUND_STATE_ON`	1
`SOUND_STATE_OFF`	2

CallerIdSettingsMask¶

Name	Number	Description
`CALLER_ID_SETTINGS_MASK_UNKNOWN`	0
`CALLER_ID_SETTINGS_MASK_PROVIDED`	1

PhoneVerificationStatus¶

Name	Number	Description
`PHONE_VERIFICATION_STATUS_UNKNOWN`	0
`PHONE_VERIFICATION_STATUS_VERIFIED`	1

PhoneDiscoverabilityStatus¶

Name	Number	Description
`PHONE_DISCOVERABILITY_STATUS_UNKNOWN`	0
`PHONE_DISCOVERABILITY_STATUS_OPTED_IN_BUT_NOT_DISCOVERABLE`	2

PhoneValidationResult¶

Name	Number	Description
`PHONE_VALIDATION_RESULT_IS_POSSIBLE`	0

OffnetworkAddressType¶

Name	Number	Description
`OFFNETWORK_ADDRESS_TYPE_UNKNOWN`	0
`OFFNETWORK_ADDRESS_TYPE_EMAIL`	1

GroupLinkSharingStatus¶

Name	Number	Description
`GROUP_LINK_SHARING_STATUS_UNKNOWN`	0
`GROUP_LINK_SHARING_STATUS_ON`	1
`GROUP_LINK_SHARING_STATUS_OFF`	2