How to: Forward a Lync audio conversation

Learn how to programmatically forward a Microsoft Lync 2013 audio call by using Microsoft Lync 2013 SDK.

Applies to: Lync 2013 | Lync Server 2013

Call forwarding overview

To forward an incoming audio conversation, you must obtain the AVModality on the conversation. You forward an audio conversation to either a Contact instance representing the person receiving the transferred call or a ContactEndpoint representing a user’s phone. The conversation is forwarded by calling into BeginForward on the AVModality and pass the Contact or ContactEndpoint as the first argument of the method.

The forwarding feature described in this topic does not create a set of call routing rules to be published on behalf of the local user. Instead, it implements client-side logic that responds to a previously routed call by forwarding it to another user.

When forwarding or transferring a conversation using the audio/video modality, the instant messaging modality is connected to the target participant automatically. When a call is transferred or forwarded to a public switch telephone network (PSTN) telephone, video and IM are disconnected and cannot be reconnected.

Prerequisites

The prerequisites for forwarding an audio call are as follows:

• Microsoft Lync 2013 must be installed and running on the development computer.

• You must have sign-in credentials for Microsoft Lync Server 2013.

• Microsoft Lync 2013 SDK must be installed on the development computer.

Core concepts to know

Forward an audio conversation

The client call forwarding operation should be started as soon as an audio call invitation is received by the platform. The earliest opportunity to forward the call is the ConversationAdded event. To forward an audio conversation, you must obtain the Microsoft.Lync.Model.Conversation.Conversation instance to be forwarded from the event data argument.

To forward an audio conversation

1. Define an event callback method to handle the ConversationAdded event raised when an audio conversation is received.

2. Get the LyncClient instance and verify that the client is signed in to the server.

   For information about signing in to Microsoft Lync Server 2013, see How to: Sign a user in to Lync.

3. Register for the ConversationAdded event on the ConversationManager instance.

Handle conversation events

To handle conversation events

1. Check the State of the audio/video modality on the new conversation triggering the event. If the state is ModalityState.Notified, you can forward the new conversation.

2. Check the availability of the ModalityAction.Forward on the audio/video modality of the new conversation by calling into CanInvoke on the modality. If true is returned, you can forward the conversation.

   Tip
   If you're forwarding to one of the local user’s phones, get the appropriate Phone instance by calling into GetPhone. You read the Endpoint property to get a ContactEndpoint that is passed into BeginForward. If you're forwarding to another user, get the appropriate Contact or ContactEndpoint instance. Call into Forward and pass the Contact instance obtained in the previous step.

Code examples: Audio conversations

Class field declarations

        private LyncClient _LyncClient;

ConversationAdded event

The following example handles the ConversationAdded event by forwarding any incoming audio conversation to a specified phone number.

Caution
The example only illustrates the procedural tasks used to forward a call. For an example of a complete event handler, see How to: Start a Lync audio conversation.

        /// <summary>
        /// Handles ConversationAdded state change event raised on ConversationsManager
        /// </summary>
        /// <param name="source">ConversationsManager The source of the event.</param>
        /// <param name="data">ConversationsManagerEventArgs The event data. The incoming Conversation is obtained here.</param>
        void ConversationsManager_ConversationAdded(ConversationsManager source, ConversationsManagerEventArgs data)
        {
            if (data.Conversation.Modalities[ModalityTypes.AudioVideo].State == ModalityState.Notified)
            {
                Contact _ForwardContact = _LyncClient.ContactManager.GetContactByUri("TEL:+14255551212");
                object[] asyncState = { data.Conversation.Modalities[ModalityTypes.AudioVideo], "FORWARD" };
                data.Conversation.Modalities[ModalityTypes.AudioVideo].BeginForward(_ForwardContact, ModalityCallback, asyncState);
            }
        }
        /// <summary>
        /// Called on the LyncClient worker thread when an audio/video modality action completes.
        /// </summary>
        /// <param name="ar">IAsyncResult. The state of the asynchronous operation.</param>
        private void ModalityCallback(IAsyncResult ar)
        {

            Object[] asyncState = (Object[])ar.AsyncState;
            try
            {
                if (ar.IsCompleted == true)
                {
                    if (asyncState[1].ToString() == "RETRIEVE")
                    {
                        ((AVModality)asyncState[0]).EndRetrieve(ar);
                    }
                    if (asyncState[1].ToString() == "HOLD")
                    {
                        ((AVModality)asyncState[0]).EndHold(ar);
                    }
                    if (asyncState[1].ToString() == "CONNECT")
                    {
                        ((AVModality)asyncState[0]).EndConnect(ar);
                    }
                    if (asyncState[1].ToString() == "FORWARD")
                    {
                        ((AVModality)asyncState[0]).EndForward(ar);
                    }
                }
            }
            catch (LyncPlatformException)
            { }
        }

See also

• What you can do with Lync conversations