This document describes the XMPP extension used by Google Talk to enable multiple applications signed in as the same user to report the same status message.
Note: This extension is not intended to become a standard and is subject to change.
Table of Contents
Google Talk, like many chat clients, lets a user display a custom status message to other users. The Google Talk server stores lists of recently used status messages, and you can request and modify these values. This XEP extension enables a client to retrieve and modify these stored message lists, and also provides notifications so that all resources can report the same status and message. Whenever any resource changes its status or message, all other resources will be notified with the new values.
A client must first learn whether a server supports this extension by using service discovery. A client should send the following IQ stanza to discover what features the server supports..
Example 1. Client service discovery request
<iq type='get' to='gmail.com'> <query xmlns='http://jabber.org/protocol/disco#info'/> </iq>
If the server supports the user settings extension, the reply will include the 'google:shared-status' feature as shown here:
Example 2. Client service discovery response
<iq type='result' firstname.lastname@example.org' from='gmail.com'> <query xmlns='http://jabber.org/protocol/disco#info'> ... <feature var='google:shared-status'/> ... </query> </iq>
A client can query the server for the current lists of status messages stored by the user. Sending this query also registers the client to receive notifications whenever any instance of that user changes the displayed status message, or if the stored list values change.
To query for the current list, send an IQ query qualified by the 'google:shared-status' namespace, as shown here:
Example 3. Client requests status lists.
<iq type='get' email@example.com' id='ss-1' > <query xmlns='google:shared-status' version='2'/> </iq>
The server will respond with the lists of stored messages, as well as
information about its message-storing capabilities. Each response includes
several lists; each list is associated with one status value. Google
Talk servers only recognize lists associated with two
dnd and default. If other show values are used, there is no guarantee
that a client will understand or display them. The following code shows
an example query response.
Example 4. Server responds to a shared status message response with messages and capabilities.
<iq type='result' firstname.lastname@example.org/orchard' id='ss-1'> <query xmlns='google:shared-status' status-max='512' status-list-max='3' status-list-contents-max='5' status-min-ver='2'> <status>Pining away</status> <show>default</show> <status-list show='default'> <status>Pining away</status> <status>Wherefore indeed</status> <status>Thinking about the sun</status> </status-list> <status-list show='dnd'> <status>Chilling with Mercutio</status> <status>Visiting the monk</status> </status-list> <invisible value='false'/> </query> </iq>
The previous stanza includes two lists, once for the default status (available), and one for the busy status ("dnd"). Each status list is enclosed in a <status-list> element with a show element describing the status associated with it. It also includes the current status (default) and message ("Pining away").
The following table describes the <elements> and attributes in this query response.
|Element or Attribute||Description|
|<query>||Outer wrapper element for the response. Attributes of this element describe the server's status message capabilities.|
|status-max||The maximum length in characters for any individual status message.|
|status-list-max||The maximum number of status lists the server can store.|
|status-list-contents-max||The maximum number of messages that the server can store in a list.|
The minimum shared status version supported by all of the clients the user is logged in with. If a non-shared status aware client is logged in, this value is
The default requested shared status version is 1. Clients that support a higher version must specify the version number in the
|<status>||The current message displayed on the clients.|
|<show>||The current status of the user.|
|<status-list>||Holds a number of messages to associate with the status value described by the show attribute.|
|show||The status to associate with these lists. The following two values
are supported by Google Talk; other values are not supported
by the Google Talk client. (The idle
|<status>||The message to display in the client.|
|<invisible>||The current invisible mode setting for the user.|
|value||Allowed values are:
Once you have registered as a shared-status-aware client, the server will rewrite your presence
stanzas and you must use shared-status to change your
status or the status message. To change your shared-status, send an IQ set of the same
form as the IQ result returned by the server when you queried for the current status.
Include the new status and message values in the top-level
The lists you send in your IQ set will replace the lists currently stored by the server. You should therefore resend the existing lists unless you want to clear these messages from the server. If the message that you are replacing is not in the appropriate status list, you should add it to the top of the appropriate status message list. If the list length then exceeds the server's maximum list length, remove the oldest message from that list to make room.
Note: Because Google Talk interprets the 'away' status as idle, and idleness is a per-connection property, you cannot set
an 'away' status using this method. To set an idle status message, send a standard
To report a status change, send an IQ query qualified by the 'google:shared-status' namespace. Place the new status
and message values in the top level
You must include both these elements, even if you are only changing
one of them.
The following stanza demonstrates a request to change the status message from Pining away to Juliet's here. Note that Juliet's here was added to the list for the active status.
Example 5. Changing the current message.
<iq type='set' email@example.com/orchard' id='ss-2'> <query xmlns='google:shared-status' version='2'> <status>Juliet's here</status> <show>default</show> <status-list show='default'> <status>Juliet's here</status> <status>Pining away</status> <status>Wherefor indeed</status> <status>Thinking about the sun</status> </status-list> <status-list show='dnd'> <status>Chilling with Mercutio</status> <status>Visiting the monk</status> </status-list> <invisible value='false'/> </query> </iq>
In response to your request, the server will send the following IQ set
to all registered clients for this user. It will also send a standard
to all the subscribed contacts for this user.
Example 6. Server sends status message notification to all registered clients for this user.
<iq type='set' firstname.lastname@example.org/orchard' id='ss-3'> <query xmlns='google:shared-status' status-min-ver='2'> <status>Juliet's here</status> <show>default</show> <status-list show='default'> <status>Juliet's here</status> <status>Pining away</status> <status>Wherefore indeed</status> <status>Thinking about the sun</status> </status-list> <status-list show='dnd'> <status>Chilling with Mercutio</status> <status>Visiting the monk</status> </status-list> <invisible value='false'/> </query> </iq>
Whenever a shared-status client sends a
set, the server stores the
<status> values and
rewrites that client's last-sent presence stanza to include the new values. The server then
broadcasts the new presence stanza to all subscribed contacts unless the user is in invisible mode.
Whenever a client sends a presence stanza the server will rewrite the 'show' and 'status' values according to these rules before broadcasting.
<show>The server will broadcast the presence stanza's 'show' unless the current shared show value is dnd. In that case, the server broadcasts dnd. (You must reset the dnd
<show>value using shared status.)
<status>The server will rewrite the presence stanza with the last shared status value.
The following example is a simple presence stanza sent by a shared-status-aware
client when the resource sends an "away" presence notification. The server
will ignore the
Example 7. Client sends a request to change the capabilities and
<presence> <show>away</show> <status>A far, far better thing</status> <c xmlns='http://jabber.org/protocol/caps' node='http://www.google.com/xmpp/client/caps' ver='0.92'/> </presence>
The server rewrites and sends out the following value to all subscribed
contacts and other instances. Note that the
used is the current shared value, not the value just sent by the
Example 8. Server rewrites the
<show> value and sends a notification
to all clients and subscribed contacts.
<presence> <show>away</show> <status>Juliet's here</status> <c xmlns='http://jabber.org/protocol/caps' node='http://www.google.com/xmpp/client/caps' ver='0.92'/> </presence>
Extensibility is one of the greatest strengths of XMPP, the IETF standard protocol on which Google Talk is built. While XMPP itself defines a bare set of features, the protocol encourages third parties to develop their own extensions. During the development of Google Talk, we found it useful to define extensions to implement features not already found in XMPP or any of its currently defined extensions.The protocol defined in this document is currently used by the Google Talk clients and servers. However, note that it is not currently part of a proposed standardized extension, and therefore may change as we work to standardize these features.