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.
Look out for Part 4, which is coming tomorrow and will cover using UCMA to build a Skype for Business IVR system.
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.
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.
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.
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.