Google Talk for Developers

Extended Contact Attributes

This document describes the XMPP extension used by Google Talk to expose additional information about members of a user's roster.

Note: This extension is not intended to become a standard and is subject to change.

Table of Contents

  • Introduction
  • Determining Server Support
  • Retrieving Extended Contact Attribute Values
  • Setting Extended Contact Attribute Values
  • Incrementing the Message Count
  • Getting Attribute Update Notifications
  • About Google Talk Extensions
  • Introduction

    The Google Talk Service stores additional information not specified in the XMPP standard about members of a user's roster. These extended values include a count of emails and instant messages sent to this contact, and other useful information. You can set and retrieve these values using this extension.

    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:roster' 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:roster'/>
        ...
      </query>
    </iq>

    Retrieving Extended Contact Attribute Values

    A client can query the server for extended attribute values stored for each roster member. These values are stored by the server. You cannot query for specific values or specific contacts; you can only query for all extended values for all contacts. To query for these values, a client does a standard roster request, which includes a ext attribute that is qualified by the 'google:roster' namespace. This attribute specifies which version of the extended attributes to retrieve. This document describes attributes in the Version 2 attribute set.

    Querying for extended roster member attributes registers the client to receive notifications whenever these values (other than message count attributes mc and emc) change. The following snippet shows a request for extended attribute values.

    Example 3. Client requests Version 2 extended attributes.

    <iq type='get'
        from='romeo@gmail.com/orchard'	
        id='google-roster-1'>
      <query xmlns='jabber:iq:roster' xmlns:gr='google:roster' gr:ext='2'/>
    </iq>

    The server responds to this request with a roster list containing one <item> element per roster member. Each <item> element includes all of the extended attribute values stored for that member. (All attributes are qualified by the google:roster namespace). The following shows one item in a query response.

    Example 4. Server responds with extended roster member attributes.

    <iq type='result'
        to='romeo@gmail.com/orchard'
        id='google-roster-1'>
      <query xmlns='jabber:iq:roster' xmlns:gr='google:roster' gr:ext='2'>
        ...
        <item jid='hamlet@denmark.lit' name='Hamlet' subscription='both'
            gr:t='B' gr:mc='82' gr:emc='5' gr:w='9'/>
        ...
      </usersetting>
    </iq>

    The following table shows the attributes defined in Version 2 of the extended contact attribute set. An <item> element does not need to have values specified for all attributes.

    Attribute Name Description
    mc [read, limited-write] The number of messages sent to and from this contact. You can increment this value using a special syntax described in Incrementing the Message Count. This and emc are used to sort the members returned to a query.
    emc [read-only] The number of emails sent to and from this contact. Emails must be sent through Gmail for the Google Talk server to be counted in this tally. This and mc are used by the client to sort the contacts on the roster.
    w [deprecated, read-only] A weight assigned to this contact. Superceded by mc and emc.
    rejected [read-only] A boolean value indicating whether a subscription request from this client was ever rejected by the user. "true" indicates that it has. This is provided so that a client can block repeated subscription requests.
    t [optional, read-write] A description for this contact. It can be one of the following values. If this attribute is not returned by the server, you should assume that the contact should not be blocked and should be displayed normally.
    • B   The contact is blocked. The server will not broadcast your presence to, or accept messages from, this contact.
    • H   The contact is hidden. The client should not display this contact to the user.
    • P   The contact is pinned. The client should always display this contact to the user.
    autosub [deprecated, read-only] A boolean value indicating whether the server added this contact automatically. "true" indicates that it did. Missing or "false" indicates that it did not.
    alias-for [optional, read-only] If this contact was superseded by another contact, this attribute will be present and set to the new contact JID. This happens when a user invites a Gmail contact to use Google Talk, and the invited user then creates a new Google Talk JID. The original email address of the invitee will be superseded by the Google Talk JID. If this value is present, the client should hide this contact in favor of the newer contact identified by this value.
    inv [optional, read-only] If present, it will have the value "A" indicating that the user invited this contact to create a Google Talk account. If absent, this was not an invited contact.

    Setting Extended Contact Attribute Values

    You can set the values of read-write extended attributes by sending a IQ set to the server. Currently you can only set the t extended attribute, but you can also increment the mc and emc values as described in Incrementing the Message Counts.

    To set a read-write attribute, send a roster set with an 'ext' attribute qualified by the 'google:roster' namespace, containing an <item> element for each contact to update. The item should have the attribute (qualified by the google:roster namespace) and new value for that contact. The following code demonstrates how to block a roster member.

    Example 5. Setting the t attribute value to block a roster member.

    <iq type='set'
        id='google-roster-2'
        type='set'>
      <query xmlns='jabber:iq:roster' xmlns:gr='google:roster' gr:ext='2'>
          <item jid='hamlet@denmark.lit' gr:t='B'/>
      </query>
    </iq>

    In response to your request, the server sends an acknowledgment to the sender (for example, <iq type='result' id='google-roster-2'/>), and sends a roster update to all connected resources, as described in Getting Roster Update Notifications.

    Incrementing the Message Count

    The mc message count value is tracked for you by the server. Although you cannot directly modify the mc attribute, you can increment it by sending one of two types of IQ set messages. You might want to increment the message count yourself when the user initiates a voice chat with another client, because the server does not currently include voice connections in its message count.

    Incrementing the mc attribute causes an update notification the same as for any other attribute updates.

    You can increase the message count in two ways: by a number, or up to a specific number:

    To increase the message count by a number, send a IQ set containing an <increment-mc> element, with a jid attribute set to the contact to increment, and a numerical value attribute to add to the current count.

    Example 6. Client increments the message count by two

    <iq type='set'
        id='google-roster-4'>
      <increment-mc xmlns='google:roster' jid='hamlet@denmark.lit' value='2'/>
    </iq>

    To increase the message count up to a specific number, send a IQ set containing an <boost-mc> element, with a jid attribute set to the contact to increment, and a numerical value attribute of the new value. The new value must be greater than the current message count or the server will return an error.

    Example 7. Client increases the message count to twelve

    <iq type='set'
        id='google-roster-4'>
      <boost-mc xmlns='google:roster' jid='hamlet@denmark.lit' value='12'/>
    </iq>

    Getting Attribute Update Notifications

    If a client sends a query for extended contact attribute values, it will a roster update whenever any of those values change. The notification will a roster item containing all of the modified attributes (qualified by the 'google:roster' namespace).

    The following IQ set will be sent to all connected resources if one of them blocks the user "hamlet@denmark.lit".

    Example 8. Server sends attribute update notification to all registered clients for this user.

    <iq type='set'
        id='google-roster-3'>
      <query xmlns='google:setting' xmlns:gr='google:roster' gr:ext='2'>
          <item jid='hamlet@denmark.lit' gr:t='B'/>
      </query>
    </iq>

    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.