The Windows Live Messenger Library gives you a way to add custom presence properties to the signed-in user.  There are a bunch of ways you can use this.

The most basic use for custom presence is to let your WLML application know which of the user's contacts are signed into the same application. By knowing that, you can show an icon or light up extra features when two people are chatting in your application.

Another way to use it is to add some personal information that goes above and beyond the normal Personal Message in Messenger. For example, if you're adding Messenger to a music site, you can add information on what music is now playing.

I've implemented a simple example here. This is the same as the

Messenger Hello World application, but it uses custom presence to show a * when one of the users in your contact list is also signed into the example application.

How to implement Custom Presence

To use custom presence, you need to define two new objects in your code. The first is the presence extension object that will be added to the user's presence:

    var EXTENSION_NAME = ‘ExtNm’ // 6 chars or less
    function MyPresenceExtension(name, content) {   
       this.name = name;   
       this.content = content; } 
    MyPresenceExtension.prototype.get_name = function() {   
        return this.name; 
    }
    MyPresenceExtension.prototype.get_content = function() {   
        return this.content; 
    }

The presence extension object must support the get_name() function. The name has to be 6 or fewer alphanumeric characters. This is a simple example of a presence extension with just a name/value pair.

Then, create a presence extension factory. This is an object that knows how to serialize and deserialize your presence extension to and from a string.

	MyPresenceFactory = function () {} 
	MyPresenceFactory.prototype.serialize = function(prop) { 
	return prop.get_content(); 
	} 
	MyPresenceFactory.prototype.deserialize = function(name, content) { 
	return new MyPresenceExtension(name, content); 
	}

After these objects are defined, you can hook it up. After sign in, add an instance of your custom presence factory to the user object, and then add the property itself to your user (here the content is just set to '*'):

	/* Called by the Messenger Library when sign-in is complete. */ 
    function signInCompleted(sender, e) {
        if (e.get_resultCode() === Microsoft.Live.Messenger.SignInResultCode.success) { 
        _user.set_presenceFactory(new MyPresenceFactory());
        addCustomPresence();
      [...]	

	/* Add a custom presence extension to the signed-in user */
	function addCustomPresence() { 
    endpointCollection = _user.get_endpoints(); 
        endpointPresence = endpointCollection.get_item(0).get_presence();
        extensionCollection = endpointPresence.get_extensions();
        extensionCollection.add(new MyPresenceExtension(EXTENSION_NAME, '*'));
    }
 

Now all that's left is to look for the property on users in the contact list.               

    // for each endpoint of this contact's presence, check for presence extension
    // the address comes from Contact.get_currentAddress()
    function getCustomPresenceContent(address) {
        endpointEnum = address.get_endpoints().getEnumerator();
        while (endpointEnum.moveNext()) {
            endpoint = endpointEnum.get_current();
            extensionEnum = endpoint.get_presence().get_extensions().getEnumerator();
            while (extensionEnum.moveNext()) {
                extension = extensionEnum.get_current();
                if (extension.get_name() == EXTENSION_NAME) {
                    return extension.get_content();
                }
            }
        }
        return '';
    }

Hope this helps get you started with custom presence. Questions? Post in the Messenger API Forums on MSDN. I'll answer any of them that I can.

Here's how to get started developing with the Windows Live Messenger Library. You can develop Messenger Library applications with the following languages:

• HTML and JavaScript
• C#, Silverlight, and JavaScript
• C# with Script#

HTML and JavaScript is the quickest way to get started with Messenger Library development.

Prerequisites:

• A site accessible through a full domain name.  This is normally a site visible from the Internet, but you can also rig up a 'fake' domain name for testing on a local web server. Angus Logan has a good how-to.
• Channel.htm from the Messenger Library SDK. You'll need to host this file to enable cross-domain communication - that is, to let live.com talk through the browser to the JavaScript code you'll write.
• A Privacy Policy. The Messenger Library will check for a privacy policy before it lets the user sign in. You can create a placeholder file to get started - I just created Privacy.htm with the content "Insert Privacy Policy Here". Before deploying your application, you'll need to create a real privacy policy.

To get started, get the source code from the Messenger Hello World app. The Hello World app has three files:

• Privacy.htm
• Channel.htm
• Default.htm

Default.htm has all the source code for the application, including the HTML, JavaScript and CSS. Deploy these files to your web site and you're in business!

Load default.htm in your browser and click Sign In.

If it's not working

One more thing: if you're deploying the files to something other than the root directory of your site, you may need to change this line in default.htm:
_signin = new Microsoft.Live.Messenger.UI.SignInControl('signinframe', privUrl, chanUrl, 'en-US');

Change privUrl and chanUrl to the actual URL for privacy.htm and channel.htm. That should fix the problem.

Keiji Kanazawa's MIX08 session is now up for your viewing pleasure. He goes deep into the code and shows you how to get started.

Check it out here: Adding Instant Messaging to Any Site

You can stream it with Silverlight, get a WMV file, or download it for your iPod or Zune.

I'm fired up about heading to MIX in a few days!

Now that the Windows Live Messenger Library is out in beta, they've updated the list of MIX sessions to include one on the Messenger Library. I got to meet Keiji when he was working on this session - it is filled with info and some deep code.

Wednesday, March 5 4:30 PM - 5:45 PM, Delfino 4003
Speaker(s): Keiji Kanazawa, Nikhil Kothari
Audience(s): Technical
Session Type: Breakout

Learn how your web site visitors can engage with Windows Live Messenger users by taking advantage of the Windows Live Messenger control and library. This session covers how to code with the Messenger Library in JavaScript or C# (using Script#), and we also show how you can drive Microsoft Silverlight UI with the Messenger Library.

If you're heading to MIX shoot me an email (click Contact above or email jasonk at akona consulting dot com).

With the Windows Live Messenger Library, you can turn your site into its own social network. Visitors to your site can sign into their Windows Live Messenger account and chat with their friends from right inside your web page. Imagine your web community growing exponentially as users invite their friends - and those friends tell their own friends about the experience.

Here's a quick tour of the features in the Messenger library.  In upcoming posts I'll dig deep into each of these features and show you some code you can drop right into your site.

Cool new UI

You can build any new Messenger UI you want.  It can be HTML + JavaScript, Silverlight, or even Flash. This is one example from iBloks Video Messenger:

You control the whole experience except for signin. All the details of sign-in and authentication are handled by Microsoft. Your site doesn't even have to ask for the user's ID and password. You just create a <div> to host the signin control:

The user clicks Sign in and Windows Live ID handles the rest.

Contacts & Conversations

The Messenger Library exposes the users contact list so your site can show their list of buddies however you like.

From this list, your users can start up a conversation. Conversations can be one-on-one, or free-for-alls with up to 25 people.

Presence

The library gives you access to the user's display picture, online status and personal message. You can give the user a way to change their status and personal message.

Application Messages & Presence Extensions

The Windows Live Messenger Library also enables a few things that can't be done with the desktop Messenger client. Presence Extensions let you set properties on the user's presence. One way to use this is set a flag when users log into your site. Then you can sense if the two users in a conversation are both on your site and enable custom features accordingly.

Application Messages are custom message types that your site can use to implement special features. If both users are signed into your Messenger implementation, your application can send custom messages that you create. These message can do many things - send pictures, notify users about updated content, or even set up an online game.