Skip to main content

Migrating your Live Connect v4.1 app to v5.0

Migrating your app

One of the key design principles in developing Live Connect, Version 5.0 was ensuring a relatively painless migration from Windows Live Messenger Connect, Version 4.1. This of course includes functional parity in terms of supported operations but also ensuring that user consent granted to your app is not lost during the upgrade process.

In this document, we will talk about how to move your Windows Live Messenger Connect v 4.1 apps to Live Connect v5.0.

Supported operations in Live Connect v5.0

In Live Connect v5.0, there is functional parity in the operations supported when compared to Messenger Connect, v 4.1. A number of new operations have also been added. Here is a list of all the supported operations in v5.0 when compared to v4.1.

If your app uses a v4.1 scope that you want to maintain user consent for when migrating, see the “Mapping between v4.1 and v5.0 offers” section later in this guide for details.

Identity (profiles)

The following table describes the new operations available when compared to v4.1.

OperationIn v4.1?In v5.0?
User’s profile infoYesYes
User’s profile imageYesYes
User’s birthdayYesYes
User’s email addressesNoYes
User’s postal addressesNoYes
User’s phone numbersNoYes

 

Hotmail

The following table describes the new operations available when compared to v4.1.

OperationIn v4.1?In v5.0?
User’s contactsYesYes
User’s friendsYesYes
User’s calendarsYes (partial)Yes
User’s calendar eventsYes (partial)Yes
Subscribe to external calendarsNoYes

 

SkyDrive

The following table describes the new operations available when compared to v4.1.

OperationIn v4.1?In v5.0?
User’s root folderNoYes
User’s foldersYesYes
User’s albumsYesYes
User’s storage quotaNoYes
User’s single folderYesYes
User’s single albumYesYes
User’s single fileYesYes
User’s single photoYesYes
User’s photo tagsNoYes
User’s photo commentsNoYes

 

Messenger

The following table describes the new operations available when compared to v4.1.

OperationIn v4.1?In v5.0?
User’s statusYesYes
User’s activitiesYesNo


How to modify settings for your 4.1 app?

If you have an existing app, you can reuse that app’s client ID for your Live Connect v5.0 app. If you want to modify some of the app’s settings, you can do this at the Live Connect app management site. You can also visit the app management site for creating a new app.

Referencing the APIs in v5.0

The Live Connect APIs include implementations for JavaScript, managed languages like C#, iOS, Android, and Representational State Transfer (REST).  You can download the latest version of the Live SDK by visiting the download section in the Live Connect Developer Center.

Referencing the APIs with JavaScript

Client-side websites and scripts that use JavaScript

To reference the APIs, for client-side websites and scripts that use JavaScript, set a reference to a web-based version of the wl.js file from your code, like this.

<script src="//js.live.net/v5.0/wl.js"></script>

A web-based debugging version of wl.js, called wl.debug.js, is also available. It is an uncompressed version of wl.js. To call it, substitute wl.debug.js for wl.js, like this.

<script src="//js.live.net/v5.0/wl.debug.js"></script>

Web-based localized versions of the APIs are available for JavaScript. You add a URL segment that specifies the culture for the localized version that you want to use. For example, to load the web-based Japanese version, your app uses a URL like this.

<script src="//js.live.net/v5.0/ja/wl.js"></script>

For a complete list of supported localized versions, see Supported locales.

Referencing the APIs with REST

Use the info in Server-side scenarios to learn about available REST calls and their syntax. To learn how to make REST calls for your specific platform and programming language combination, see your documentation.

Moving to OAuth 2.0

Differences between OAuth WRAP and OAuth 2.0

Messenger Connect v4.1 uses a protocol called OAuth WRAP to get user consent for the data that your app needs. Live Connect v5.0 uses an evolved version of OAuth WRAP, OAuth 2.0. There are many similarities between the two protocols and a few differences as well.

To learn more about OAuth WRAP, see the Messenger Connect OAuth WRAP reference page.

To learn more about OAuth 2.0, see the Live Connect OAuth 2.0 reference page.

Reusing your Messenger Connect v4.1 refresh token

If your app requested and obtained a refresh token from Messenger Connect v4.1 with the OAuth WRAP authorization code flow, this refresh token can be reused in the Live Connect v5.0 OAuth 2.0 flows. This is beneficial as it allows your app to migrate to Live Connect v5.0 without your users needing to reauthenticate. In the case where a refresh token has expired, you would need to get consent from your user. You can easily detect this by checking for an error on the call. If you do get an exception, we recommend you use the equivalent Wave 5 scopes listed here.

In Messenger Connect v4.1, a refresh token was used to get a new access token by making a POST request with the refresh token to consent.live.com by sending the following request.

Messenger Connect v4.1 refresh token request

POST /RefreshToken.aspx



Host: consent.live.com



wrap_refresh_token={refresh_token}

Using a refresh token in Live Connect v5.0 to get a new access token looks very similar, although there are some additional request parameters required.

Live Connect v5.0 refresh token request

POST /oauth20_token.srf



Host: login.live.com



Content-Type: application/x-www-form-urlencoded



client_id={RT}&redirect_uri={REDIRECT_URI}&client_secret={CLIENT_SECRET}&refresh_token={REFRESH_TOKEN}&grant_type=refresh_token

The Messenger Connect v4.1 response contains just the access token to be used by your app. Note that the scope is not provided in the request to the token endpoint. This is required in order for your application to reuse consent from v4.1.

Messenger Connect v4.1 refresh token response

wrap_access_token="{access_token}"&wrap_access_token_expires_in={expiration}

The Live Connect v5.0 response looks as follows. Note that Live Connect v5.0 returns a new refresh token, which your app must remember in place of the refresh token it used for the original request. Also note that the format of the response is in JavaScript Object Notation (JSON) as compared to the query string format used in v4.1.

Live Connect v5.0 refresh token response

{

    "access_token": "{access_token}",

    "expires_in": {expires_in},

    "refresh_token": "{refresh_token}",

    "scope": "{original scope passed}",

    "token_type": "bearer"

}

Mapping between v4.1 and v5.0 offers

In order to reuse the user consent acquired by your app obtained in v4.1, all requests must omit the scope parameter. If you are creating a new app or need the user to re-consent, please use these scopes. The following table provides the mapping between the scopes your app may have used in v4.1 and the functional equivalents in v5.0.

v4.1v5.0
WL_Profile.Viewwl.basic
wl.emails
WL_Profile.ViewFullwl.basic
wl.emails
wl.birthday
WL_Profile.UpdateStatuswl.share
WL_Contacts.Viewwl.basic
wl.contacts_birthday
WL_Activities. Viewwl.basic
WL_Activities.Updatewl.share
WL_Photos.Viewwl.photos
WL_Applications.Createwl.applications_create


Moving to the v5.0 API

In order to interact with the REST API, the app must make the appropriate HTTP call to the following URL.

{HTTP Method} https://apis.live.net/v5.0/{PATH}?access_token={access_token}

Where:

{HTTP Method} – the appropriate HTTP method: GET(read), PUT(update), POST(create), DELETE(delete), MOVE(move), or COPY(copy)

{PATH} – the path for the particular resource

{access_token} – See the “” section

Calling an operation

In order to call an operation, you must know this info.

  1. The path you want to call. See the “Supported operations in Live Connect v5.0” section earlier in this guide for details.
  2. The HTTP method that must be used. See the “Supported operations in Live Connect v5.0” section earlier in this guide for details.
  3. A valid access token.
  4. The type of request body to construct for a POST or PUT call.  See the REST Reference for details.

The libraries have built in functionality to support the different type of HTTP calls as well as ensure that the access token specified is valid at all times. In addition to these, the libraries also have support for downloading and uploading a file (although currently this is not supported for JavaScript for the web).

In v5.0, we offer a convenient, powerful, and elegant way to interact with the Live Connect REST API. The WL.api method accesses data by a property, which contains a JSON-formatted object that defines the values of the method.

Below is an example of how you can use the library to get a user’s profile info. Calls can be made to retrieve different user data by simply replacing the path and the HTTP method as needed.

JavaScript

function greetUser_onClick() {

    WL.api({

        path: "me",

        method: "GET"

    }).then(

        function (response){

            document.getElementById("infoArea").innerText =

                "Hello, " + response.first_name + " " +

                response.last_name + "!";

        },

        function (responseFailed){

            document.getElementById("infoArea").innerText =

                "Error calling API.";

        }

    );

}

For more information on the API model for the various libraries, see the Live Connect API .

Mapping operations between v4.1 and v5.0 operations

In v4.1, an app was able to do this.

  1. Get a user’s contacts.
  2. Get a user’s profile info and profile pictures.
  3. Get info about a user’s folders, albums, files, and photos.
  4. Share a user’s status.

A v5.0 app can do these operations and take advantage of the other operations that are made available in v5.0. See the “Supported operations in Live Connect v5.0” section earlier in this guide.

However, there is a change on how these operations are called in v5.0. The following sections will walk through the semantics of making these calls.

Get a user’s contacts

In order to get a user’s contact list, the app must get consent from the user. If your v4.1 app already has the WL_Contacts.View scopes, then reconsent is not required, and the consent will be carried forward.

In v4.1, contacts were loaded by doing this.

JavaScript request

function signInComplete(signInCompletedEventArgs) {

    if (signInCompletedEventArgs.get_resultCode() != Microsoft.Live.AsyncResultCode.success) {

        //  Process on failure.

        return;

    }

    // Get the data context and load contacts.

    dataContext = signInCompletedEventArgs.get_dataContext();

    dataContext.loadAll(Microsoft.Live.DataType.contacts, contactsLoaded);

}



function contactsLoaded(dataLoadCompletedEventArgs) {

    …

    contactsCollection = dataLoadCompletedEventArgs.get_data();

    …

    }

}

REST request

GET https://apis.live.net/v4.1/cid-CID/contacts/AllContacts

In v5.0, we have made loading contacts simpler by adding this friendlier syntax.

Contacts

The following code snippet shows how to get a user’s contact info using the v5.0 REST API.

JavaScript request

function readContact_onClick() {

    WL.api({

        path: "me/contacts",

        method: "GET"

    }).then(

        function (response) {

            parseResult(response)

        },

        function (responseFailed) {

            document.getElementById("infoArea").innerText =

                "Error calling API.";

        }

    );

}

REST request

GET https://apis.live.net/v5.0/me/contacts?access_token={access_token}

JSON response

{

   "data": 

   [

	{

         "id": "contact.e7fd4a29000000000000000000000000", 

         "first_name": "William", 

         "last_name": "Flash", 

         "name": "William Flash", 

         "gender": null, 

         "is_friend": false, 

         "is_favorite": false, 

         "user_id": null, 

         "email_hashes": [], 

         "updated_time": "2011-09-22T17:33:09+0000"

        }

   ]

}

For other supported operations for contacts, See Hotmail (contacts). For other supported operations for contacts, See Hotmail (contacts).

Get a user’s profile info and profile image

To get a user’s profile info and profile picture, the app must get consent from the user. If your v4.1 app already has the WL_Profile.View scopes, then reconsent is not required, and the consent will be carried forward.

In v4.1, profiles were loaded by doing this.

JavaScript

function loadAllProfiles() {

    dataContext.loadAll(Microsoft.Live.DataType.profiles, profilesLoaded);

}



function profilesLoaded(dataLoadCompletedEventArgs) {

    profileCollection = dataLoadCompletedEventArgs.get_data();

    Sys.Debug.trace("Profiles are loaded.");

}

REST request

GET https://apis.live.net/v4.1/cid-CID/Profiles/

In v5.0, we have made loading profiles simpler by adding this friendlier syntax.

Profile info

The following code snippet shows how to get a user’s profile info using the v5.0 REST API.

JavaScript request

function profile_onClick() {

    WL.api({

        path: "me ",

        method: "GET"

    }.then(

        function (response) {

            parseResult(response)

        },

        function (responseFailed) {

            document.getElementById("infoArea").innerText =

                "Error calling API.";

        }

    ));

}

REST request

GET https://apis.live.net/v5.0/me?access_token={access_token}

JSON response

{

   "id": "9d24497f7fef8f33", 

   "name": "William Flash", 

   "first_name": "William", 

   "last_name": "Flash", 

   "link": "http://profile.live.com/cid-9d24497f7fef8f33/", 

   "birth_day": 1, 

   "birth_month": 4, 

   "birth_year": null, 

   "gender": "male", 

   "emails": {

      "preferred": "willamf@hotmail.com", 

      "account": "willamf@hotmail.com", 

      "personal": "williamf@hotmail.com", 

      "business": null

   }, 

   "locale": "en_US", 

   "updated_time": "2012-01-10T03:22:09+0000"

}

Profile image in v5.0

JavaScript request

function profilePicture_onClick() {

    WL.api({

        path: "me/picture",

        method: "GET"

    }).then(

        function (response) {

            parseResult(response)

        },

        function (responseFailed) {

            document.getElementById("infoArea").innerText =

                "Error calling API.";

        }

    );

}

REST request

GET https://apis.live.net/v5.0/me/picture?access_token={access_token}

JSON response

{

   "location": "http://blufiles.storage.msn.com/....."

}

For other supported operations for a user’s profile, see Identity (Profiles).

User’s folders, albums, files, and photos

To get info about a user’s photos, the app must get consent from the user. If your v4.1 app already has the WL_Photos.View scope, then reconsent is not required for reading photos and the consent will be carried forward.

In v4.1, photos were loaded by doing this.

JavaScript

function loadAllPhotos() {

    dataContext.loadAll(Microsoft.Live.DataType.photos, profilesLoaded);

}



function profilesLoaded(dataLoadCompletedEventArgs) {

    profileCollection = dataLoadCompletedEventArgs.get_data();

    Sys.Debug.trace("Profiles are loaded.");

}

REST request

GET https://apis.live.net/v4.1/cid-CID/Photos/

In v5.0, we have made loading albums and photos simpler by adding this friendlier syntax.

Reading album properties

The following code snippet shows how to get a user’s album info using the v5.0 REST API.

JavaScript request

function readFolder_onClick() {

             WL.api({

                path: "album.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!125",

                method: "GET"

            }).then(

                function (response) {

                    document.getElementById("infoLabel").innerText = 

                        "Folder properties: name = " + response.name + ", ID = " + response.id;                

                }, 

                function (responseFailed) {

                    document.getElementById("infoLabel").innerText = 

                        "Error reading folder properties: " + responseFailed.error.message;

                }

            );

}

REST request

GET

https://apis.live.net/v5.0/album.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!125?access_token={access_token}

JSON response

{

    "name": "Wallpapers",

    "description": null,

    "parent_id": "folder.9d24497f7fef8f33",

    "upload_location": "https://apis.live.net/v5.0/folder.9d24497f7fef8f33.9D24497F7FEF8F33!165/files/",

    "count": 0,

    "link": "https://skydrive.live.com/redir.aspx?cid=9d24497f7fef8f33&page=view&resid=9D24497F7FEF8F33!165&parid=9D24497F7FEF8F33!161",

    "type": "album",

    "shared_with": 

        {



            "access": "Just me"

        },

    "created_time": "2008-03-17T08:02:39+0000",

    "updated_time": "2008-03-17T08:02:39+0000"

}

In v5.0, we made it easier to get info about a user’s SkyDrive files and folders.

Reading folder properties

The following code snippet shows how to get a user’s folder info using the v5.0 REST API.

JavaScript request

function readFolder_onClick() {

             WL.api({

                path: "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!125",

                method: "GET"

            }).then(

                function (response) {

                    document.getElementById("infoLabel").innerText = 

                        "Folder properties: name = " + response.name + ", ID = " + response.id;                

                }, 

                function (responseFailed) {

                    document.getElementById("infoLabel").innerText = 

                        "Error reading folder properties: " + responseFailed.error.message;

                }

            );

}

REST request

GET

https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!125?access_token={access_token}

JSON response

{

    "name": "Videos",

    "description": null,

    "parent_id": "folder.9d24497f7fef8f33",

    "upload_location": "https://apis.live.net/v5.0/folder.9d24497f7fef8f33.9D24497F7FEF8F33!165/files/",

    "count": 0,

    "link": "https://skydrive.live.com/redir.aspx?cid=9d24497f7fef8f33&page=view&resid=9D24497F7FEF8F33!165&parid=9D24497F7FEF8F33!161",

    "type": "folder",

    "shared_with": 

    {



        "access": "Just me"

    },

    "created_time": "2008-03-17T08:02:39+0000",

    "updated_time": "2008-03-17T08:02:39+0000"

}

Reading file and photo properties

The following code snippet shows how to get a user’s file and photo info using the v5.0 REST API.

JavaScript request

function readFile_onClick() {

             WL.api({

                path: "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!125",

                method: "GET"

            }).then(

                function (response) {

                    document.getElementById("infoLabel").innerText = 

                        "Folder properties: name = " + response.name + ", ID = " + response.id;                

                }, 

                function (responseFailed) {

                    document.getElementById("infoLabel").innerText = 

                        "Error reading folder properties: " + responseFailed.error.message;

                }

            );

}

REST request

GET

https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!125?access_token={access_token}

JSON response

{

"name": "2208120743_7c41fa4524_o.jpg",

"description": null,

"parent_id": "folder.9d24497f7fef8f33.9D24497F7FEF8F33!265",

"size": 397298,

"comments_count": 0,

"comments_enabled": true,

"tags_count": 0,

"tags_enabled": true,

"picture": "http://storage.live.com/....s1p0p7c41fa4524_o.jpg",

"source": "http://storage.live.com/...._o.jpg",

"upload_location": "https://apis.live.net/v5.0/file.9d24497f7fef8f33.9D24497F7FEF8F33!293/content/",

}

Update status

To update a user’s status, the app must get consent from the user. If your v4.0 app already has the WL_Activities.Update scope, then reconsent is not required, and the consent will be carried forward.

The following code snippet shows how to set a user’s status using v4.1.

JavaScript request

dataContext.loadAll(Microsoft.Live.DataType.Activities, nil, activitiesLoadded); }



function activiiessLoaded(dataLoadCompletedEventArgs) {

    …

    activitiesCollection = dataLoadCompletedEventArgs.get_data();

    …

    }

}

activitiesCollection.add(newActivity);

activitiesCollection.save(saveCompleted);

REST request

POST https://apis.live.net/v4.1/cid-CID/Activities



Authorization: Bearer ACCESS_TOKEN

Content-Type: application/json



{

    ……."

}

In v5.0, you do this.

JavaScript request

WL.api({

   path: "me/share",

   method: "POST",

   body: {

      message: "Hello, Windows Live!"

   } 

   }).then(function(response){ 

                  //status updated.

          });

REST request

POST https://apis.live.net/v5.0/me/share 



Authorization: Bearer ACCESS_TOKEN

Content-Type: application/json



{

    message: "Explore Windows Live",

    link: "http://explore.live.com/home",

    description: "Stay in touch and share your world: email, photos, movies, video chat, and more!",

    picture: "http://explore.live.com/a1ce...part of URL omitted for brevity...481c.jpg",

    name: "Windows Live Home"

}

JSON response

{

 "status": "Hello, Windows Live!"

}