An Overview of the Lync APIs

Microsoft Lync Server has a wide range of APIs and extensibility points for the client-side, middle-tier and server-side. These enable a variety of powerful solutions to be built on top of the core platform.

Client-Side – Lync 2010 SDK

The Lync 2010 SDK is the current client-side SDK for Lync 2010. It contains the Lync 2010 API, the Lync controls for WPF and Silverlight, sample applications, documentation, and an MSI for the redistributable.

The Lync 2010 API is a fully managed API for implementing Lync functionality in custom applications. It can be used to automate the running instance of the Lync client, or to build a complete replacement for the Lync client when the Lync client is in UI Suppression mode. Either way, the Lync 2010 client must be installed on the machine. This API is not compatible with previous versions of the client (i.e. Communicator 2007 and Communicator 2007 R2)

Applications that automate the Lync client can sign in and out of Lync, pull information from Lync (such as a contact’s presence), and change the logged-on user’s presence information. They can initiate IM conversations and send instant messages and contextual data, and initiate Audio/Video calls. In addition, conversations windows for conversations that are initiated using the Lync API can be docked inside the application, giving the impression that the conversation window is part of the custom application. Common scenarios are – integrating presence and click-to-communicate into Line-of-Business applications, creating screen-pops, creating conversation window extensions, using docking to add buttons to a conversation window.

When Lync is in UI Suppression mode, the user will not be able to start the Lync client by running the executable – instead, an application using the Lync 2010 API must be responsible for starting Lync and providing all UI for Lync-related features. It is not possible to display any of the standard Lync UI when in UI Suppression mode, so it really is up to the developer to implement all required UI, including conversation windows and contact searches. The Lync API provides access to almost all of the functionality of the Lync client, enabling powerful custom UIs to be built. Common scenarios are – creating kiosk applications, creating custom clients targeted to a subset of Lync tasks.

The Lync 2010 Controls for WPF and Silverlight provide a simple way to build clients that display information from and perform tasks with the running instance of Lync – for example, there are controls for displaying a contact’s presence and contact card, changing the logged on users status, initiating conversations and audio/video calls, and many others. They follow the UI style of the Lync client, and are templatable, so can be re-skinned easily. Applications that use the Lync Controls can also use the Lync API for any logic that is not addressed by the controls. The Lync controls do not work against Lync in UI suppression mode. Common scenarios are – integrating presence and click-to-communicate into Line-of-Business applications, integrating presence and click-to-communicate into existing Silverlight-based apps (e.g. an intranet corporate directory).

Client-Side – Conversation Window Extensions

Conversation Window Extensions are more an extensibility point than an API, but are crucial in building rich CEBP-style applications. A conversation window extension is a web application that can be “embedded” in a conversation window. This is best illustrated with a picture:

TimePrompt - An application running in a conversation window extension

Conversation window extensions host a web page. A Silverlight application on that web page can use the Lync 2010 API and Silverlight controls to interact with the underlying conversation, and to send contextual data to the participant in the conversation. Contextual data is application-specific data that will not be seen by the users, but can be received and processed by the application in the extensibility window. This is a really powerful way to allow users to collaborate on data in real-time.

Conversation windows extensions are new to Lync 2010, so are not available with Communicator 2007 or Communicator 2007 R2.

Common scenarios are – displaying additional information relevant to the conversation, allowing users to collaborate on data.

Client-Side – NameCtrl Control

NameCtrl is an ActiveX Control that provides the Persona Menu functionality in web-based applications such as SharePoint and Dynamics CRM:

Persona Menu

Being an ActiveX control, it is relatively simple to integrate NameCtrl into your own web pages, assuming Internet Explorer is used to access them.

Common scenarios are – integrating presence and click-to-communicate into existing html pages (e.g. an intranet corporate directory).

Client-Side – Office Communicator Automation API

The Office Communicator Automation API (OCAA) is a client-side COM-based API that allows an application to automate the running instance of Lync. The Lync client must be installed on the target machine, and must be running in order for an application to use this API.

Using this API, a custom application can perform many of the same tasks as Lync – for example, signing in and out of Lync, displaying contacts and presence, managing contacts and groups and starting conversations.

This API has been around since Communicator 2007, but has been de-emphasized with the Lync 2010 release in favour of the richer and easier to use Lync 2010 API. The benefit this has over the Lync 2010 API is that an application written using OCAA will run against Communicator 2007 and Communicator 2007 R2. However, support for it is unlikely to continue indefinitely.

Common scenarios are – integrating presence and click-to-communicate into Line-of-Business applications, creating screen-pops.

OCAA MSDN Documentation

Client-Side – Unified Communications Client API

The Unified Communications Client API (UCCA) is a client-side COM-based API that allows you to create custom endpoints, enabling replacements for the Lync client to be built, without the requirement of having the Lync client installed on the machine. It is effectively an API wrapper around a SIP stack and RTP codecs.

Like OCAA, this API has been around since Communicator 2007, but has now been de-emphasized in favour of the Lync 2010 API. The benefit this has over the Lync 2010 API is that an application written using UCCA doesn’t require the Lync client to be installed, and will work against Communications Server 2007 and Communications Server 2007 R2. However, the API will be deprecated in Wave 15.

Common scenarios are – creating kiosk applications, creating custom clients targeted to a subset of Lync tasks.

UCCA MSDN Documentation

Client-Side – Miscellaneous Extensibility Points

Custom Menu Commands allow custom commands to be added to various menus in Lync. These are configured (via the registry) to start an application and pass thorough the SIP URIs of all participants in the conversation. There is a great walkthrough of this here.

Third-party Collaboration Application Integration enables Lync to kick off a web-based application for all participants in a conversation.

Command-line parameters tell Lync to perform particular tasks, such as opening a conversation window for a given phone number. The parameters are in the form of URLs, and so can be placed in web pages to provide a convenient way to perform actions in Lync.

Middle-Tier – Unified Communications Managed API

The Unified Communications Managed API (UCMA) 3.0 SDK is the current incarnation of UCMA (UCMA 1.0 was released with Office Communications Server 2007, UMCA 2.0 with Office Communications Server 2007 R2). UCMA 3.0 applications will run against Office Communications Server 2007 R2 with limitations. The SDK contains the UCMA 3.0 Core API, the UCMA 3.0 Workflow API, sample and reference applications, documentation and tools.

UCMA 3.0 Core API is a fully managed API which allows you to build applications that register to Lync as endpoints. UCMA applications can log on to the Lync infrastructure as existing users (either by using their credentials, or by impersonation), or can be configured to use one or more Active Directory “Contact” objects, which can appear as contacts in the Lync client.

UMCA applications can create and respond to IM and Audio/Video conversations and conferences, publish and subscribe to presence, modify contacts and contact groups (if logged on as a user) and perform text-to-speech and speech-to-text operations.

Applications are generally deployed to a dedicated application server (or pool of applications servers). An application server must be registered with Lync server to enable a trust relationship between the two.

UCMA 3.0 allows highly scalable and resilient applications to be created. A UCMA application can be configured and optimised for client-like behaviour (making lots of requests), or server-like behaviour (handling lots of requests).

Common scenarios are – creating query/response bots (e.g. that can be IM’d to return stock prices), creating notification bots (e.g. that notify users when a stock’s price breaches a threshold), creating contact centre applications, creating custom clients that can’t be created using Lync 2010 API.

UCMA 3.0 Workflow API is built on the UCMA 3.0 Core API, and can simplify building certain types of UCMA application. The API comes with a a set of Windows Workflow Foundation activities for performing tasks such as answering an incoming call, responding to voice or DTMF input, and asking the user questions.

Common scenarios are – creating Interactive Voice Response (IVR) applications, creating voice companion applications.

Server-Side – Lync Server 2010 SDK

The Lync Server 2010 SDK is used to create applications that act as filters – they can “plug in” to a front-end server and inspect, modify and reroute SIP messages as they pass through the server. The SDK includes the Lync Server API, documentation, sample applications and tools.

Filters are implemented as MSPL scripts. MSPL is a custom scripting language designed for this purpose. For more complex applications, the MSPL script can be configured to dispatch messages to a separate process, often a Windows service.

Common scenarios are – creating compliance applications, creating billing and archiving applications.

Lync Server SDK MSDN Documentation

13 thoughts on “An Overview of the Lync APIs

  1. Can a custom developed website OR web application sign in and out of Lync, pull information from Lync (such as a contact’s presence), and change the logged-on user’s presence information. The website can also initiate IM conversations and send instant messages and contextual data, and initiate Audio/Video calls.

    • Pretty much yes to everything, except A/V. I’m assuming the end users won’t have Lync installed, right?

      The right way to do this is to build a UCMA 3.0 application that exposes functionality via WCF or Web Services, and have the web site call this. This would allow both anonymous and known users to view presence, change their presence status, start and participate in IM conversations, and package up and send/recieve contextual info. The only limitation is going to be around audio/video calling – there is no satisfactory way to do this over the web.

      Take a look at these two codeplex projects – they should be a great starting point for you:
      – Orbit One’s Lync Presence and Chat widget
      – Clarity Consulting’s HTML Presence Controls

  2. I’m writing application that will integrate/automate Lync 2010. The one thing that I would like to avoid is .Net runtime dependency. I know that I can use OCAA (which is COM based) but it is marked as deprecated and wouldn’t be supported beyond Lync 2010. Is there any way to use new Lync 2010 API from unmanaged code without depending on .Net runtime? Is new Lync 2010 API also COM exposed?

  3. A colleague and I are modifying an application for a communication hardware device and we are trying to incorporate many different softphones such as skype and lync. However the application is written in C++ so we are trying to determine what the best method of approaching this problem is?

    Help would be appreciated greatly.

  4. Hi,

    Is there any code example for an implimentation like
    ” creating notification bots (e.g. that notify users when a stock’s price breaches a threshold)” with UCMA
    mentioned in this artical. Would realyy help me.
    Thanks,

  5. Can the SDK hook into existing winforms application and allow things like showing a popup when a phone call is being received which then loads another form to keep notes and auto get the length of time from the phone call, also forward the call (and the notes) to another lync user?

    • Sure, you can use the Lync 2010 API from a winforms app, and detect incoming calls (see the article here). To get duration, you could watch the Conversation.StateChanged event to determine when the call starts and ends. FOrwarding a conversation is described here

  6. Hi,

    That was a nice article. By the way, I’m building an app using xcode that integrate with Lync. I’m using PJSIP to make a call and send IM. But now i’m facing a problem, i can’t retrieve contact list from lync. How can i retrieve the contact list using the xcode? Do i need an API to retrieve? or I should prepare a WCF to retrieve the contact list?

    thanks.
    best regards,
    Alfred Angkasa

    • So your application is running on OSX? Lync on the mac doesn’t have an API, so that’s not an option. If you can deploy applications to the server environment, your best bet is to build a UCMA application that retrieves this information, and access it via a web/wcf service.

      • UCMA? do you have any tutorial using UCMA? i mean by establish the connection, update the presence, do some chat and video. if i have to use UCMA, do i need to install mobility service?

        and i also download lync app for my iphone and android. But somehow i can’t login using my lync ID. But using lync client at my computer, i can login properly. thanks. :)

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>