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.5.3+ 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).

If this login method fails, try the manual login method instead:

hangups --manual-login

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 “hangups” (or “iOS” in older versions).

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, manual_login=False)

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.
• manual_login (bool) – If true, prompt user to log in through a browser and enter authorization code manually. Defaults to false.

Raises:

GoogleAuthError – If authentication with Google fails.

hangups.get_auth(credentials_prompt, refresh_token_cache, manual_login=False)

Authenticate with Google.

Parameters:

• refresh_token_cache (RefreshTokenCache) – Cache to use so subsequent logins may not require credentials.
• credentials_prompt (CredentialsPrompt) – Prompt to use if credentials are required to log in.
• manual_login (bool) – If true, prompt user to log in through a browser and enter authorization code manually. Defaults to false.

Returns:

Google session cookies.

Return type:

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

static get_authorization_code()

Prompt for authorization code.

Returns:Google account authorization 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, max_retries=5, retry_backoff_base=2)

Instant messaging client for Hangouts.

Maintains a connections to the servers, emits events, and accepts commands.

Parameters:

• cookies (dict) – Google session cookies. Get these using get_auth().
• max_retries (int) – (optional) Maximum number of connection attempts hangups will make before giving up. Defaults to 5.
• retry_backoff_base (int) – (optional) The base term for the exponential backoff. The following equation is used when calculating the number of seconds to wait prior to each retry: retry_backoff_base^(# of retries attempted thus far) Defaults to 2.

on_connect = None

Event fired when the client connects for the first time.

on_reconnect = None

Event fired when the client reconnects after being disconnected.

on_disconnect = None

Event fired when the client is disconnected.

on_state_update = None

Event fired when an update arrives from the server.

Parameters:state_update – A StateUpdate message.

coroutine connect()

Establish a connection to the chat server.

Returns when an error has occurred, or disconnect() has been called.

coroutine disconnect()

Gracefully disconnect from the server.

When disconnection is complete, connect() will return.

get_request_header()

Return request_header for use when constructing requests.

Returns:Populated request header.

static get_client_generated_id()

Return client_generated_id for use when constructing requests.

Returns:Client generated ID.

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 upload_image(image_file, filename=None, *, return_uploaded_image=False)

Upload an image that can be later attached to a chat message.

Parameters:

• image_file – A file-like object containing an image.
• filename (str) – (optional) Custom name for the uploaded file.
• return_uploaded_image (bool) – (optional) If True, return UploadedImage instead of image ID. Defaults to False.

Raises:

hangups.NetworkError – If the upload request failed.

Returns:

UploadedImage instance, or ID of the uploaded image.

coroutine add_user(add_user_request)

Invite users to join an existing group conversation.

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 easter_egg(easter_egg_request)

Send an easter egg event to a conversation.

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.

coroutine get_group_conversation_url(get_group_conversation_url_request)

Get URL to allow others to join a group conversation.

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 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 modify_otr_status(modify_otr_status_request)

Enable or disable message history in a conversation.

coroutine send_offnetwork_invitation(send_offnetwork_invitation_request)

Send an email to invite a non-Google contact to Hangouts.

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.

class hangups.client.UploadedImage(image_id, url)

Details about an uploaded image.

Parameters:

• image_id (str) – Image ID of uploaded image.
• url (str) – URL of 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.

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.

coroutine fire(*args, **kwargs)

Fire this event, calling all observers with the same arguments.

High-Level APIs

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

Conversation List

coroutine hangups.build_user_conversation_list(client)

Build UserList and ConversationList.

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

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

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

Maintains a list of the user’s conversations.

Using build_user_conversation_list() to initialize this class is recommended.

Parameters:

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

on_event = None

Event fired when an event occurs in any conversation.

Parameters:conv_event – ConversationEvent that occurred.

on_typing = None

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

Parameters:typing_message – TypingStatusMessage that occurred.

on_watermark_notification = None

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

Parameters:watermark_notification – WatermarkNotification that occurred.

get_all(include_archived=False)

Get all the conversations.

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

get(conv_id)

Get a conversation by its ID.

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

coroutine leave_conversation(conv_id)

Leave a conversation.

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

Conversation

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

A single chat conversation.

Use ConversationList methods to get instances of this class.

on_event = None

Event fired when an event occurs in this conversation.

Parameters:conv_event – ConversationEvent that occurred.

on_typing = None

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

Parameters:typing_message – TypingStatusMessage that occurred.

on_watermark_notification = None

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

Parameters:watermark_notification – WatermarkNotification that occurred.

id_

The conversation’s ID (str).

users

List of conversation participants (User).

name

The conversation’s custom name (str)

May be None if conversation has no custom name.

last_modified

When conversation was last modified (datetime.datetime).

latest_read_timestamp

Timestamp of latest read event (datetime.datetime).

events

Loaded events sorted oldest to newest.

(list of ConversationEvent).

watermarks

Participant watermarks.

(dict of UserID, datetime.datetime).

unread_events

Loaded events which are unread sorted oldest to newest.

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

(list of ConversationEvent).

is_archived

True if this conversation has been archived.

is_quiet

True if notification level for this conversation is quiet.

is_off_the_record

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

update_conversation(conversation)

Update the internal state of the conversation.

This method is used by ConversationList to maintain this instance.

Parameters:conversation – Conversation message.

add_event(event_)

Add an event to the conversation.

This method is used by ConversationList to maintain this instance.

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

get_user(user_id)

Get user by its ID.

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

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

Send a message to this conversation.

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

Parameters:

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

Raises:

NetworkError – If the message cannot be sent.

coroutine leave()

Leave this conversation.

Raises:NetworkError – If conversation cannot be left.

coroutine rename(name)

Rename this conversation.

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

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

coroutine set_notification_level(level)

Set the notification level of this conversation.

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

coroutine set_typing(typing=1)

Set your typing status in this conversation.

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

coroutine update_read_timestamp(read_timestamp=None)

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

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

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

coroutine get_events(event_id=None, max_events=50)

Get events from this conversation.

Makes a request to load historical events if necessary.

Parameters:

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

Returns:

List of ConversationEvent instances, ordered newest-first.

Raises:

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

next_event(event_id, prev=False)

Get the event following another event in this conversation.

Parameters:

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

Raises:

KeyError – If no such ConversationEvent is known.

Returns:

ConversationEvent or None if there is no following event.

get_event(event_id)

Get an event in this conversation by its ID.

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

Conversation Event

class hangups.ConversationEvent(event)

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

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

Parameters:event – Event message.

timestamp

When the event occurred (datetime.datetime).

user_id

Who created the event (UserID).

conversation_id

ID of the conversation containing the event (str).

id_

ID of this event (str).

class hangups.ChatMessageEvent(event)

An event that adds a new message to a conversation.

Corresponds to the ChatMessage message.

text

Text of the message without formatting (str).

segments

List of ChatMessageSegment in message (list).

attachments

List of attachments in the message (list).

class hangups.OTREvent(event)

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

Corresponds to the OTRModification message.

new_otr_status

The conversation’s new OTR status.

May be either OFF_THE_RECORD_STATUS_OFF_THE_RECORD or OFF_THE_RECORD_STATUS_ON_THE_RECORD.

old_otr_status

The conversation’s old OTR status.

May be either OFF_THE_RECORD_STATUS_OFF_THE_RECORD or OFF_THE_RECORD_STATUS_ON_THE_RECORD.

class hangups.RenameEvent(event)

An event that renames a conversation.

Corresponds to the ConversationRename message.

new_name

The conversation’s new name (str).

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

old_name

The conversation’s old name (str).

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

class hangups.MembershipChangeEvent(event)

An event that adds or removes a conversation participant.

Corresponds to the MembershipChange message.

type_

The type of membership change.

May be either MEMBERSHIP_CHANGE_TYPE_JOIN or MEMBERSHIP_CHANGE_TYPE_LEAVE.

participant_ids

UserID of users involved (list).

class hangups.HangoutEvent(event)

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

Corresponds to the HangoutEvent message.

event_type

The Hangout event type.

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

class hangups.GroupLinkSharingModificationEvent(event)

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

Corresponds to the GroupLinkSharingModification message.

new_status

The new group link sharing status.

May be either GROUP_LINK_SHARING_STATUS_ON or GROUP_LINK_SHARING_STATUS_OFF.

Chat Message Segment

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

A segment of a chat message in ChatMessageEvent.

Parameters:

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

static from_str(text)

Construct ChatMessageSegment list parsed from a string.

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

static deserialize(segment)

Construct ChatMessageSegment from Segment message.

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

serialize()

Serialize this segment to a Segment message.

Returns:Segment message.

Notifications

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

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

Parameters:

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

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

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

Parameters:

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

User List

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

Maintains a list of all the users.

Using build_user_conversation_list() to initialize this class is recommended.

Parameters:

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

get_user(user_id)

Get a user by its ID.

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

get_all()

Get all known users.

Returns:List of User instances.

User

class hangups.user.NameType

Indicates which type of name a user has.

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

DEFAULT = 0

NUMERIC = 1

REAL = 2

class hangups.user.UserID(chat_id, gaia_id)

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

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

A chat user.

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

name_type = None

The user’s name type (NameType).

full_name = None

The user’s full name (str).

first_name = None

The user’s first name (str).

id_ = None

The user’s ID (UserID).

photo_url = None

The user’s profile photo URL (str).

emails = None

The user’s email address (str).

is_self = None

Whether this user is the current user (bool).

upgrade_name(user_)

Upgrade name type of this user.

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

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

static from_entity(entity, self_user_id)

Construct user from Entity message.

Parameters:

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

Returns:

User object.

static from_conv_part_data(conv_part_data, self_user_id)

Construct user from ConversationParticipantData message.

Parameters:

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

Returns:

User object.

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
usec_since_last_seen	2	uint64	optional

Presence

Field	Number	Type	Label	Description
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	Description
user_id	1	ParticipantId	optional
client_generated_id	2	string	optional
notification_level	3	NotificationLevel	optional

Formatting

Field	Number	Type	Label	Description
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 place coordinates.
name	3	string	optional	Name of the place.
address	24	EmbedItem	optional	Address of the place.
geo	25	EmbedItem	optional	Geographic location of the place.
representative_image	185	EmbedItem	optional	Representative image of the place (map with pin).

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.
postal_address	36003298	EmbedItem.PostalAddress	optional	Embedded postal address.
geo_coordinates	36736749	EmbedItem.GeoCoordinates	optional	Embedded geographical coordinates.
image	40265033	EmbedItem.Image	optional	Embedded image.

EmbedItem.PostalAddress

Field	Number	Type	Label	Description
street_address	35	string	optional

EmbedItem.GeoCoordinates

Field	Number	Type	Label	Description
latitude	36	double	optional
longitude	37	double	optional

EmbedItem.Image

Field	Number	Type	Label	Description
url	1	string	optional

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	Description
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	Description
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	Timestamp of the user’s last read message in the conversation.

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	Description
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	Description
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	Read state (watermark position) for every conversation participant.
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	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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	Description
conversation_id	1	ConversationId	optional
sender_id	2	ParticipantId	optional
timestamp	3	uint64	optional
type	4	TypingType	optional

SetConversationNotificationLevelNotification

Field	Number	Type	Label	Description
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	Description
sender_id	1	ParticipantId	optional
conversation_id	2	ConversationId	optional
latest_read_timestamp	3	uint64	optional

ConversationViewModification

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

EasterEggNotification

Field	Number	Type	Label	Description
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	Description
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	Description
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	Description
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	Description
response_header	1	ResponseHeader	optional
conversation	2	Conversation	optional
new_conversation_created	7	bool	optional

DeleteConversationRequest

Field	Number	Type	Label	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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

Location

Field	Number	Type	Label	Description
place	1	Place	optional

SendChatMessageRequest

Field	Number	Type	Label	Description
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
user_id	9	ParticipantId	optional
location	10	Location	optional	TODO: incomplete

SendChatMessageResponse

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

ModifyOTRStatusRequest

Field	Number	Type	Label	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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	Description
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

Indices and tables

• Index
• Module Index
• Search Page