Click to Rate and Give Feedback
MSDN
MSDN Library
Live Services SDK
Other APIs
 Querying with the Windows Live Pres...

  Switch on low bandwidth view
Querying with the Windows Live Presence API

The Windows Live Presence API is an HTTP API for accessing a Windows Live™ Messenger user’s presence. The Windows Live Presence API returns presence in JavaScript Object Notation (JSON) or as a JavaScript function. For a Web site to query a Windows Live Messenger user’s presence, the Messenger user must give permission to share presence and receive messages from the Web. The Web site should invite the user to share the user's Messenger presence. For more information, see Inviting Users to Share Online Presence.

The Presence API is designed to be easy to use directly from the browser. Access the API using a URL of the following format:

http://messenger.services.live.com/users/[ID]/[resource]/[?queryparameters]

The [ID] is of format id@apps.messenger.live.com, where "id" is a numerical user ID.

The [resource] is either:

  • presence: For presence JSON or JavaScript
  • presenceimage: for an image icon denoting the user’s presence

The JSON result for presence is formatted as shown in the following example, assuming that 12BACD345678 is the ID of the user whose presence is being queried:

{
   "status": "Offline",
   "icon": {
   "height": 16,
   "url": "http://settings.messenger.live.com/static/w13r2/Conversation/img/Status_Online.gif",
   "width": 16
   },
   "statusText": "Online",
   "id": "12BACD345678@apps.messenger.live.com",
   "displayName": "Name"
}

The Presence API can be used in combination with the Windows Live Messenger IM Control to show the presence of other users who are online and available for messaging. For example:

<a href=”http://settings.messenger.live.com/conversation/imme.aspx?...” target=”_blank”>
   <img src=”http://messenger.services.live.com/users/12BACD345678@apps.messenger.live.com/presenceimage”>
</a>

If the cb query parameter is passed in the URL for a presence resource request, the JSON result will be enclosed within the specified JavaScript callback function. The cb query parameter is optional and only valid when the presence resource is requested. Otherwise, the parameter is ignored.

The JavaScript function name must have the following characteristics:

  • It must reference a valid JavaScript function.
  • It can only have the following characters: a-z, A-Z, 0-9, and underscore (_).
  • It must contain at least one character, and not exceed 128 characters (inclusive).

In this example, the following URL:

http://messenger.services.live.com/users/12BACD345678@apps.messenger.live.com/presence/?cb="ShowStatus"&mkt=en-US

will insert the JSON response into the ShowStatus function, resulting in the following:

ShowStatus({"status": "Offline", "icon": {
     "height": 16, "url": "http://settings.messenger.live.com/static/w13r2/Conversation/img/Status_Offline.gif",
     "width": 16 }, 
     "statusText": "Offline", 
     "id": "12BACD345678@apps.messenger.live.com", 
     "displayName": "Name" })

You can access presence data directly from a Web page by calling the presence API by using the HTML <script> tag. In this example HTML page, the status for user 12BACD345678@apps.messenger.live.com is returned when the page loads:

<html >
<head>
   <title>Display User Presence</title>
</head>
<body>   
   <div id="innerFrame"></div>
   
   <script type="text/javascript" language="javascript">   
   function showpresence(presence)
   {
      var innerFrame = document.getElementById('innerFrame');
         
      var statusIcon = document.createElement('img');
      statusIcon.style.border = 'none';
      statusIcon.src = presence.icon.url;
      statusIcon.width = presence.icon.width;
      statusIcon.height = presence.icon.height;
      statusIcon.alt = presence.statusText;
      statusIcon.title = presence.statusText;

      var displayName = document.createElement('span');
      displayName.style.fontFamily = 'Tahoma, Verdana, sans-serif';
      displayName.style.fontSize = '9pt';
      displayName.title = presence.displayName;
      
      var statusText = document.createElement('span');
      statusText.style.fontFamily = 'Tahoma, Verdana, sans-serif';
      statusText.style.fontSize = '9pt';
      statusText.title = presence.statusText;
      
      var br = document.createElement('br');
      
      innerFrame.appendChild(statusIcon);
      innerFrame.appendChild(br);
      innerFrame.appendChild(displayName);
      innerFrame.appendChild(br);
      innerFrame.appendChild(statusText);
      
      if ((displayName.innerText !== undefined)&&(statusText.innerText !== undefined))
      {
         displayName.innerText = presence.displayName;
         statusText.innerText = presence.statusText;
      }
      else if ((displayName.textContent != undefined)&&(statusText.textContent !== undefined))
      {
         displayName.textContent == presence.displayName;
         statusText.textContent == presence.statusText;
      }
   }
   </script>
   <script type="text/javascript" language="javascript"
src="http://messenger.services.live.com/users/12BACD345678@apps.messenger.live.com/presence/?cb=showpresence">
   </script>
</body>
</html>

By loading the JavaScript function call in the SCRIPT\SRC element, the browser calls the callback function named in the cb query parameter with the result of the presence API call and executes the function. The callback function can operate on the presence object and display the user's status in the desired way.

The next code example links to the presence image for a user from an HTML <img> element:

<img src="http://messenger.services.live.com/users/12BACD345678@apps.messenger.live.com/presenceimage/" alt="status" />

This displays the 16 x 16 PNG icon image that represents the user's status.

© 2009 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker