Google Talk for Developers

Shared Status Messages

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

  • Introduction
  • Determining Server Support
  • Requesting Current Status and Message Lists
  • Changing the Current Status or Message
  • How the Server Broadcasts Presence
  • About Google Talk Extensions
  • Introduction

    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.

    Determining Server Support

    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' to='romeo@gmail.com' from='gmail.com'>
      <query xmlns='http://jabber.org/protocol/disco#info'>
        ...
        <feature var='google:shared-status'/>
        ...
      </query>
    </iq>

    Requesting Current Status and Message Lists

    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' to='romeo@gmail.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 <show> values: 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' to='romeo@gmail.com/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.
      status-min-ver

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

    The default requested shared status version is 1. Clients that support a higher version must specify the version number in the version attribute of the <query> element, as shown in example 3 above. Clients can use status-min-ver information to optionally display hints in the user interface when a user tries to select invisible mode while logged in with a client that does not support invisibility.

        <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 <show> value is supported by Google Talk, but not as a shared status value.)
    • dnd User is busy.
    • default Maps to the default, available state; user is able to chat.
            <status> The message to display in the client.
        <invisible> The current invisible mode setting for the user.
          value Allowed values are:
    • true: User is invisible. Google Talk will not advertise presence for clients that support shared-status version 2 or higher.
    • false: User is not invisible.

    Changing the Current Status or Message

    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 <status> and <show> elements.

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

    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 <status> and <show> elements. 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' to='romeo@gmail.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 <presence> stanza 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' to='romeo@gmail.com/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>

    How the Server Broadcasts Presence

    Whenever a shared-status client sends a google:shared-status IQ set, the server stores the <show> and <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 <status> value.

    Example 7. Client sends a request to change the capabilities and <show> value.

    <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 <status> value used is the current shared value, not the value just sent by the <presence> stanza.

    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>

    About Google Talk Extensions

    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.

    Authentication required

    You need to be signed in with Google+ to do that.

    Signing you in...

    Google Developers needs your permission to do that.