How to: Connect to a Persistent Chat server

2018-06-11

Learn how to use the Microsoft Lync Server 2013 Persistent Chat API to connect to a Persistent Chat server.

Applies to: Lync 2013 | Lync Server 2013

To call any Lync Server 2013 Persistent Chat API functionality, an application must first establish a connection to the underlying Persistent Chat server. This involves connecting to a Microsoft Lync Server 2013 instance by using Microsoft Unified Communications Managed API (UCMA) on a LocalEndpoint instance and then connecting to the underlying Persistent Chat server on a PersistentChatEndpoint instance.

In UCMA, a LocalEndpoint is either a UserEndpoint or an ApplicationEndpoint. A client-side Lync Server 2013 Persistent Chat API application will most likely use UserEndpoint. An implementation of connecting to Lync Server 2013 computer on a UserEndpoint is illustrated as follows.

    ClientPlatformSettings platformSettings = new ClientPlatformSettings(_appName, transport);
    CollaborationPlatform collabPlatform = new CollaborationPlatform(platformSettings);
    collabPlatform.EndStartup(collabPlatform.BeginStartup(null, null));

    UserEndpointSettings userEndpointSettings = new UserEndpointSettings(userSipUri, lyncServer);
    userEndpointSettings.Credential = usingSso ?
        SipCredentialCache.DefaultCredential : new NetworkCredential(username, password);
    UserEndpoint userEndpoint = new UserEndpoint(collabPlatform, userEndpointSettings);
    userEndpoint.EndEstablish(userEndpoint.BeginEstablish(null, null));

As shown in the code, connecting a UserEndpoint instance to Lync Server 2013 requires a specification of the transport protocol (transport of the Tls or Tcp value), the address of the server instance or pool (lyncServer of the "server.contoso.com" format), the user’s SIP URI (userSipUri of "sip:user@domain"), and credentials. When Single-Sign-On In is used (usingSso=true), Windows credentials of the currently logged-on user is used. Otherwise, the user name (userName of "user@domain") and password (password) must be explicitly supplied.

A server-side or middle-tier Lync Server 2013 Persistent Chat API application must use an ApplicationEndpoint to connect to the underlying Lync Server 2013. An implementation is illustrated as follows.

        public static ApplicationEndpoint ConnectLyncServerWithAppEndpoint(string userSipUri)
        {
            // Create a UCMA ApplicationEndpoint to connect to Lync server
            Console.WriteLine("Connecting to Lync Server... ");

            // Trusted app uses MTLS. Dig for our cert here.
            X509Store certificateStore = new X509Store(StoreName.My, StoreLocation.LocalMachine);
            certificateStore.Open(OpenFlags.ReadOnly);

            X509Certificate2Collection certs = certificateStore.Certificates.Find(X509FindType.FindBySubjectName, "client.contoso.com", true);
            if (certs.Count < 1)
            {
                return null;
            }

            X509Certificate2 cert = certs[0];

            // Init platform (parameters have to match the objects created with New-CsTrustedApplication(Pool/computer) cmdlets)
            ServerPlatformSettings platformSettings = new ServerPlatformSettings("PersistentChat.Test", // App type, good for urn
                                                                                 "client.contoso.com", // App FQDN
                                                                                 4585,                // App port
                                                                                 @"sip:client.contoso.com@contoso.com;gruu;opaque=srvr:grsample:uCFg9SltSVSXRkVxjKxvJwAA", // Trusted app GRUU
                                                                                 cert);

            CollaborationPlatform collabPlatform = new CollaborationPlatform(platformSettings);

            // 

            // Initialize the platform
            collabPlatform.EndStartup(collabPlatform.BeginStartup(null, null));

            // Active Directory User object-based ApplicationEndpointSettings:
            ApplicationEndpointSettings appEndpointSettings = new ApplicationEndpointSettings(userSipUri);
            ApplicationEndpoint appEndpoint = new ApplicationEndpoint(collabPlatform, appEndpointSettings);

            // Set the outbound proxy (the Lync pool)
            appEndpoint.SetProxyInformation("pool0.contoso.com", 5061);
            // Sign in to Lync server.
            appEndpoint.EndEstablish(appEndpoint.BeginEstablish(null, null));

            Console.WriteLine("\tSuccess");
            return appEndpoint;
        }

The SIP URI used to create an ApplicationEndpoint must correspond to an Active Directory User object.

When the LocalEndpoint instance is connected to Lync Server 2013, the application can proceed to connect to a PersistentChatEndpoint. This is shown in the following code.

     // Extract default Persistent Chat server uri via in-band provisioning

    ProvisioningData provisioningData = appEndpoint.EndGetProvisioningData(appEndpoint.BeginGetProvisioningData(null, null));
                    
    PersistentChatConfiguration ChatConfiguration = provisioningData.PersistentChatConfiguration;
    Uri ChatServerUri = new Uri(ChatConfiguration.DefaultPersistentChatUri);

    // Connect to Persistent Chat Server
    PersistentChatEndponit ChatEndpoint = new PersistentChatEndpoint(ChatServerUri, localEndpoint);
    ChatEndpoint.EndEstablish(ChatEndpoint.BeginEstablish(null, null));

Here, localEndpoint is either userEndpoint or appEndpoint mentioned in the code listings discussed earlier. ChatServerUri identifies the services of the underlying Microsoft Lync Server 2013 Persistent Chat computer. For Microsoft Lync Server 2010 Group Chat, the default chat server URI is "sip:ocschat@domain.com", where "domain" stands for the domain name of the enterprise network. In Microsoft Lync Server 2013 Persistent Chat, the chat server URI is explicitly configured by the server administrator as part of server installation. The application can retrieve the chat server URI value using in-band provisioning by reading the DefaultPersistentChatUri() property.

Before connecting to the Lync Server 2013 Persistent Chat by calling BeginEstablish(AsyncCallback, Object) and EndEstablish(IAsyncResult) on the newly instantiated PersistentChatEndpoint object, the application might want to register interested events raised by the chat endpoint. To get notified of any invitation from a chat room, register and handle the ChatRoomInvitationReceived events. To receive notifications when the connection state changes on the PersistentChatEndpoint instance, register and handle the ConnectionStateChanged events.

Share via

How to: Connect to a Persistent Chat server

See also

Concepts

Feedback

Additional resources