Using Activity Window feature in WL Messenger to make your Agents stand out

imiluk — Mon, 11 Aug 2008 21:00:00 GMT

1. What is an Activity Window (AW) and how can it be used to enhance Agents?

The Activity Window is an area in the Messenger Client that allows Windows Live Agents developers to provide rich content to the user to make the Agents experience much more engaging than simply conversing through the conversation window. This can also greatly increase the interaction between the user and agent.

Activity Windows can be used to enhance Agents by providing rich content such as Animation, Games, Videos, Charts, Tables, etc… that are not possible to display in the Conversation Window. Activity Windows is also able to accept input (just like any web page can) through mouse or keyboard, and send this data to the Agent, which can respond in turn.

Note: AWs are a feature of Windows Live Messenger and has a lot more functionality to offer that are unrelated to Windows Live Agents. For more information about Activity Windows, please follow this link: http://msdn2.microsoft.com/en-us/library/aa751014.aspx Activity Windows are a feature of Windows Live Messenger. This document only addresses how to use AW in the context of Windows Live Agents. For more information about Activity Windows, please follow this link: http://msdn2.microsoft.com/en-us/library/aa751014.aspx

2. What you need to implement AWs for Windows Live Agents:

a. Basic knowledge of the following technologies:

i. HyperText Markup Language (HTML)

ii. BuddyScript (scripting language used to add logic to Agents)

iii. Javascript (JS) *

iv. eXtensible Markup Language (XML) *

b. Familiarity with the Messenger Activity API Process.

c. A hosting site to host your Activity Window pages and JS code.

d. An application provisioned for your specific Activity Window by Messenger. (please see section 7 for more information on this)

e. Last but not the least, you need the user’s consent to display the AW. (The end user needs to Accept the invitation from your agent to start an Activity Window).

* These are needed only if using the Data Interchange method of interacting with the AW. Currently this method is only available to internal Agents developers but should be available to external Agents developers in a future release.

3. Basic Idea of how User à Agentà AW interaction works:

a. First, anapplication ID is provisioned by Microsoft points to your specific Agent’s AW. This enables Windows Live Messenger to know which Activity it needs to call when the user accepts the invitation.

b. When the user asks a question for which the Agent has an answer that can be displayed in the AW, the Agent will send the output data to the AW application (hosted in the hosting site that you provide) instead of the conversation window.

c. Once the AW application receives the data, the code in the AW uses the data to display the content requested.

d. In certain cases, it is also possible for the AW code to send data back to the Agent.

4. AW Implementations used in Agents:

There are several ways to achieve the functionality shown in the above diagram. The ones used by WL Agents team so far include the following:

a. Page Drive

Samples of Agents using this method include Encarta Instant Answers agent and MSN Music agent.

b. Data Interchange using Javascript Object Notation (JSON) and XML*

Samples of Agents using this method include College Football Guru agent.

*As of this time, this method is still in Beta and available only to internal Agents developers. We expect to make this available to external Agents developers in a future release.

5. The Page Drive method

Taking the example from MSN Music agent, it uses the AW to display Artist information when the user asks for it.

BuddyScript code is used to match on the user input, and if the user input is understood to be a request for Artist info, we search our list of Artist info.

Sample Code:

subpattern AnArtist

<Your subpattern of an artist here>

? What do you know about ARTIST=AnArtist?

ARTIST_ID = ArtistIDFromArtistName(ARTIST)

If ARTIST_ID < 0

- Sorry, I don’t have info about ARTIST :-(

exit all

- Let me take you to the MSN Music page about ARTIST =>

call PageDrive(StringConcat(“http://music.msn.com/artist/?artist=, ARTIST_ID, “#”))

BuddyScript code that calls the Page Drive procedure

In the above sample code, this is the handle that is executed when someone asks a question about an artist. The code will get an Artist ID and then call the PageDrive procedure which simply takes the URL string, starts up the AW process, and (assuming the user accepted the AW invitation), displays the page indicated by the URL in the AW.

The PageDrive procedure is part of the WL Agents Activity Window Utilities API. This main package for handling AW functions in Agents is called WLMActivityUtilities.pkg and can be found under Modules\Shared\Utilities directory.

On the AW side, there is also JavaScript code that handles the request. Once the AW receives the request, the following JS code (embedded in an HTML file) is triggered.

Sample JS Code:

function Channel_OnDataReceived() {

var myData=window.external.Channel.Data;

DisplayDebugInfo("received data: " + myData);

if (myData=="READY") {

Channel_OnRemoteAppLoaded();

return;

}

// Input sent by the BuddyScript code follows the format:

// param1=value1\nparam2=value2 ...

var myDataArray=myData.split("\n");

var destinationURL="";

for (var i=0; i < myDataArray.length; i++) {

if (myDataArray[i].indexOf("url=")==0) {

destinationURL = myDataArray[i].substring(4);

} else if (myDataArray[i].indexOf("debug=")==0) {

debugInfo = myDataArray[i].substring(6) * 1; // * 1 to make sure we have a number

}

if (destinationURL!="") {

// Go to the new location

DisplayDebugInfo("URL=" + destinationURL);

top.mainFrame.location.href = destinationURL;

}

Snippet of Javascript code that handles data from the Agent’s PageDrive procedure

To learn more about the different JS functions provided by the Window Live Messenger Activity API, please see their documentation.

6. The Data Interchange method (a Sneak Peek)

Oftentimes it is not sufficient and certainly less interesting to simply use the AW to page drive to a URL. After all, AWs should be engaging and should provide rich content and functionality in order to increase user interaction time with your agent.

Windows Live Agents provides another way to implement AW in your Agent that allows for more complex AW displays. This is accomplished through data interchange using Javascript Object Notation (JSON) (please see http://www.json.org for more info) and eXtensible Markup Language (XML).

In a nutshell, here is how this works:

Note: The Data Interchange method is currently not available for use as of this time by external Agents Developers because it is still in Beta. More detailed information will be posted on the Windows Live Agents Team blog as soon as this feature becomes available for external Agents developers.

7. All about the AW Application ID

The AW Application ID allows the MSN Messenger Client to determine which Activity it should load when the user accepts your Agent’s invitation to start an Activity Window session. This application ID can be obtained by contacting the Window Live Gallery team at http://gallery.live.com and submit a request. Please click here to read a post for more information regarding this process.

The msgrp2p.xml file contains information that the Messenger client uses to load your AW application. It looks like this:

<?xml version="1.0"?>

<Entry>

<EntryID>99999999</EntryID>

<Name>Windows Live Agents Sample Activity</Name>

<Description>Windows Live Agents SDK Activity Description</Description>

<URL>http://localhost/activity.html</URL>

<EnableIP>False</EnableIP>

<ActiveX>False</ActiveX>

<SendFile>False</SendFile>

<SendIM>False</SendIM>

<ReplaceIM>False</ReplaceIM>

<UserProperties>False</UserProperties>

<Hidden>false</Hidden>

</Entry>

The elements to take note here are the ones bolded and displayed in red. The P4 Application ID that is provided to you by the Messenger team goes into the EntryID. The Name should be the name of the Activity that you are developing, and will appear in the Window Title of the AW. The Description is a description of the Activity, and the URL element specifies where the Messenger client will take the user once he accepts the invitation to start an AW.

Shown below is sample BuddyScript code that the Agent uses to get the Application Name and Application ID that will be passed to the AW in order to indicate which AW Application should be loaded.

function overrides MSNSLPGetAgentMainP4ApplicationName()

return " Windows Live Agents Sample Activity "

function overrides MSNSLPGetAgentMainP4ApplicationId()

return "99999999"

procedure MSNSLPSendInvitationToOpenP4Application(APP_ID, APP_NAME)

if LogActivityUsage()

call LogActivityInvitationMade()

call IncrementIgnoredInvitationAttempts() // This invitation is ignored until an event accepts or rejects it

SESSION_INVITE_STRING = StringConcat("msnslp invite session ", APP_ID, ";1;", APP_NAME)

ABSendServiceEvent(SESSION_INVITE_STRING)

Note: For testing purposes, in order to see the Activity that you are developing even before you get it provision, you can put the EntryID value of 7, and provide correct values for Name, Description, and URL. Then, restart your Messenger client. When it starts up, you can talk to your agent, accept an invitation, and your Messenger client will automatically send you to the URL that you specified in the msgrp2p.xml.

For more information about this, please refer to Windows Live Messenger Activity SDK.

---------------------------------------------------------------------

Blog post contributor(s): Alan Chan

Windows Live Agents Team Blog : Activity Window

Using Activity Window feature in WL Messenger to make your Agents stand out