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 in the following format.
http://messenger.services.live.com/users/[ID]/[resource]/[?queryparameters]
The [ID] should be in the following format where "id" is a numeric user ID.
id@apps.messenger.live.com
The [resource] is either presence or presenceimage.
-
presence is used to indicate presence JSON or JavaScript.
-
presenceimage is used to indicate an image icon denoting the user’s presence.
The JSON result for presence is formatted as shown in the following example, which assumes 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, as shown in the following 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 valid only 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 include 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 is used to insert the JSON response into the ShowStatus function.
http://messenger.services.live.com/users/12BACD345678@apps.messenger.live.com/presence/?cb="ShowStatus"&mkt=en-US
The following code is the result of this action.
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" })
To access presence data directly from a Web page, call 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 xmlns="http://www.w3.org/1999/xhtml">
<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 src attribute on the script 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.
The following 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.