Skype for Business – A Developer’s Guide : Part 3 – UCWA

I’ve put together a series of 4 short videos, aimed at developers who are coming to Skype for Business development for the first time and want to know what’s possible. The videos show some of what you can do with some of the APIs and SDKs Microsoft make available with Skype for Business.

In this video I use the Unified Communications Web API to bring online web chat to a webpage, without requiring special plugins, using JavaScript and the UCWA helper libraries.

Accompanying Blog Post: UCWA Sample Project – Online Chat Example
Source Code: github.com/tomorgan/UCWASimpleWebpageChatExample

Look out for Part 4, which is coming tomorrow and will cover using UCMA to build a Skype for Business IVR system.

Full Transcript:

Hello. My name’s Tom Morgan. I write about Skype for Business development on my blog, thoughtstuff.co.uk. I’ve put together this short 4-part video series, designed for developers who are just getting started in Skype for Business development, or are curious about what’s possible. There are 4 videos in the series.

The first video covered the history of Skype for Business, showed some screenshots and listed the different types of development tools. The second video looked at the Client SDK using a worked example to illustrate what’s possible.

In this video we’re going to examine UCWA, the Unified Communications Web API. I need an example company to illustrate what I’m doing here so I have this sample page. It’s got a rather lovely Bootstrap template, as you can see. What I’ve done is replace part of the Contact section, and I’m going to show you what the code does first before we dig into it because then I think it’ll make more sense.

So, I’ve got this totally vanilla template page here. If I go to the Contact section, this is where it looks slightly different – what I’ve done is I’ve replaced the Contact Us section with this Online Chat feature. Now, this is going to take a few moments to log in. What it’s actually doing behind the scenes (I’ll just explain what it’s doing whilst it does it) it’s signing in using UCWA, the Web API, it’s signing in as a user to the Lync network, to my Lync network, and then what it’s doing is looking at my availability, so the availability of the person signed in on the left there, you can see the Skype client. What that means is, in the code I’ll show you in a minute, there’s code which says “if my status is Available, show the Online Chat is available, and if my status is anything other than Available, then say that it’s offline”. So, if I were to change my status here to Busy – it’s a little bit slower than some of the other SDKs and APIs because it is web-based but as you can see, it’s updated and it’s saying “Chat Offline”.

So, let’s go back to being Available again so that it lights up the Chat Online div, and I’m just going to put in here and say “hello, I need help!”

OK, so you can see what it’s done – it’s started a new conversation with me here – so I’ve got the Lync popup here, so I can accept that over here, and I can say “what’s the problem?” (with my bad typing), and you’ll see it on the screen.

Now, what’s really interesting, and worth pointing out here is that on the screen here, this is just HTML and JavaScript. There’s nothing clever about this at all. You don’t need, obviously we are on the same machine here, both these applications are on the same machine, but it doesn’t need to be like that – this is your user’s machine here on the right – they don’t have to have Lync, this could work wherever.

So, now that I’ve shown you what it does, let’s dig into the code and see what it does, and how it does it. Now, it’s just worth pointing out at this stage that this is just an example product, example worked solution just to show you what’s possible. There’s lots of reasons why this sort of approach wouldn’t work in a production environment, for instance your signing in as an individual user each time, so that doesn’t scale. And, you’re checking the availability of a single person, which again doesn’t really scale in anything other than the smallest companies. But it’s a good way of showing you what’s possible with UCWA, you can build on that, and add those extra features in later.

OK, so let’s look at some of this code. Now, in the introductory video, I said that one of the things which Microsoft had done to make UCWA much more useful than it might otherwise have been is that they’ve created a lot of helper libraries in JavaScript, I guess they presume (and probably correctly) that lots of people who want to use UCWA are going to be doing so in JavaScript. So,I can show you that, if you look on the contact page, you can see there’s a whole bunch of JavaScript helper files which I’m importing here just to make things like signing in, caching, the transport – so the way UCWA works is all HTTP Request & Response, so anything on top of that you need to write, so everything then becomes quite complicated. So, it’s great that they’ve provided these helpers because it really helps you jumpstart the process and get on and build UCWA applications.

I’ve split the JavaScript I’ve written into 2 parts: there’s the logging in and the subscribing to presence, and then the instant messaging. I’m not going to go through it bit-by-bit, but I’m hoping that by looking at it, you can see that it’s not as complicated as you think it’s going to be.

So the first thing that happens in this sign-in to Lync is a process that’s known in the Skype for Business world as Autodiscovery. And really what that means is, it’s taking the name you’re logging in as, so it might be [email protected] – it’s taking the thoughtstuff.co.uk bit and it’s doing what’s called Autodiscovery, which means it just kind of resolves it and works out which server it needs to present these credentials at. It will try a couple of known variants, and it will try HTTPS first, and then HTTP if that’s allowed, and it will run through until it finds the right server, and the right setup, and when it does it will pass it back, so in this JavaScript here what it’s going to do is pass back this handle here, handleAutoDiscovery, and hopefully there’s a link in it, if not something bad happened, but we’ve got this link which means that we can send some credentials and start the authentication process. And again, the authentication process is going to call back on handleLogin. So, this is example code so there’s nothing really in the way of handling errors, I’m assuming you’re going to log straight in and everything is going to work perfectly, and then when you do the first thing you’re going to want to do is subscribe to presence.

Because UCWA is, like I say, based on this HTTP Request & Response, it uses events, which use long-polling in the background to provide some of its information, and that explains a little bit the slight lag which we saw when running the example. The Events helper here is really useful in abstracting a lot of that work. So really all I need to say is “I’m interested in contact presence”. When you get contact presence, or when it’s updated, in this case I’m calling the same function each time because I don’t really care whether it’s the first time, or subsequent times that the presence was received. And all I’m really doing is I’m looking at a single person’s presence, and this variable here which I’ve previously filled in with my details, so that’s the list of SIP addresses, and obviously you can have more SIP addresses in there if you’re subscribing to lots of different people, but I’ve only got one. And then in the callback, again all I really care about is whether or not people are online, so if they are online, all I’m saying here is hide or show the online / offline divs. And that’s how that works, that’s the only complicated part in the whole process – which really isn’t that complicated at all.

So, when it comes to sending an IM, again it’s not as hard as you think it’s going to be. So, here is the onClick for the Send Button. Now, when you click the Send Button it might be in one of two states: you might already be in a conversation, in which case all you really want to do is send a message on that conversation. Or it might be the first time you click the button, in which case you also need to set up the whole conversation and get it going, and do all of that.

Assuming for a moment that it’s the first time, and that you’re doing it with StartNewConversation – again it comes down to registering for different types of information before you post to say that, yes, you want to start some messaging. So, here I am calling back for 3 particular pieces of information, 3 particular events:handle conversation, handle message and handle messaging. Now, if you listened to the introductory video you’ll know about conversations and the Instant Message modality within those conversations, and that’s really what I’m subscribing to here – you’ve got conversation which is the outer wrapper, within that you’ve got the messaging modality which is the actual Instant Message part of that, and then within that you’ve got the actual messages, the actual “to” and “from”, bits of text which make up that conversation. So in each of these cases I’m doing something slightly different each time. In handleConversation really the only thing I’m looking at is whether the status has changed to Disconnected – if it has I’m just going to put something in the message, on the screen just to say the conversation has ended. So you could actually get rid of that completely, it’s just a nicety.

In handleMessaging, again I’m only checking the one state, which is whether or not I’m connected, and with that payload that comes back you get some extra links, for sending messaging, and stopping messages. And this is a good example of how UCWA works in how all the calls, when they come back, how they link off with hyperlinks to functions and other parts – so it makes it quite a nice, discover-able platform to use. The idea is that you can make very dynamic applications with it – so within this payload that comes back you can see it’s very easy for me to start messaging because I just post back on the startMessaging URL. Likewise, sending a message – I know exactly now for this conversation – now that it’s connected I know exactly where I’m supposed to post my messages.

And handling a message here – this is the actual message itself, and all I’m doing is appending it to the div with – I think…oh yeah OK – these are received messages, right, so really just so that it’s formatted nicely and slightly differently, so I’ve formatted them in different colours – that’s the only exciting thing that’s happening there. And, I think that’s it, the only other thing is the SendMessage itself – which again is just posting it to that URL which we just had discovered, and at that point, that’s when I write out the sent, which it’s slightly different CSS class, just so it looks slightly different.

And that’s really all there is to it – again it’s not a deep dive, but hopefully (and again it’s not necessarily a production ready example, there’s things that aren’t right with it, there’s things you wouldn’t want to put live) but hopefully it’s been useful to see in a relatively short space of time that you can put together something which gives you a way for your users to interact with you on Skype for Business in a way that works on a web browser, in a way that doesn’t require them to have Lync installed, or even any plugins, you can do all this, all this text and presence based stuff you can do purely just with HTML and JavaScript.

So, I hope you found it useful. If you’d like to look at the code it’s all on GitHub, so you can take it and try it out for yourself, fork it and build projects with it, the address is on the screen now for both the code, and there’s a blog post which goes into a bit more detail about how this works as well. You can find more information about Skype for Business development on my blog – thoughtstuff.co.uk, or you can also follow me on Twitter, I’m @tomorgan. Thanks for watching.