voIPReceived Element

Article
05/23/2014

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Indicates that client application has received a VoIP event.

Syntax

<voIPReceived/>

Attributes

None.

Element Information

Parent Element

Element	Description
conference	Grouping for conference-related events.

Child Elements

Element	Occurrence	Description
displayName Element	1	The display name of the caller.
isConference Element	0 or 1	Indicates incoming VoIP call is a conference call.
uri Element	1	The uri of the caller.
from Element	1	The from header of the SIP INVITE. This includes the uri and all other parameters in case client needs them.
priority Element	0 or 1	Indicates the priority an Office Communications Server assigned to the VoIP call.
redirectable Element	1	Indicates the call is redirectable.
subject Element	0 or 1	The subject line as set by an originating Office Communications Server.
canReplyWithIM Element	1	Indicates the caller can receive an IM reply. A false value indicates: The calling user cannot accept IM. A conversation with the same confId attribute is currently active.

Remarks

This event is the initial VoIP invitation that prompts the client application to display a VoIP invitation dialog to the user according to the call forwarding rules selected by the user. When the call forwarding rules have not been set or an existing rule indicates the call should not be forwarded, the following logic should be applied.

A Unified Communications client application can only redirect an incoming call to a telephone, reply with an IM, reject the call, or forward to a voice mail number.

The redirectable and canReplyWithIM elements constrain the response behavior of the client application receiving the VoIP invitation.

If the redirectable element contains a true value, the user can redirect the invitation to either a telephone handset or another user. To do this, the client application should present the user with a dialog displaying a list of phone numbers from which to choose a redirect number. The source of the phone number list can be the selfPresence category contactCard that contains all phone numbers configured by the user. To redirect the VoIP invitation to a phone number, issue the voIPRedirect request.

When redirectable is false, any set call forwarding rule cannot be executed and the audio invite cannot be manually redirected. The user receives the audio invite, but cannot redirect. The user must answer the call or ignore the toast to generate a timeout on the invitation.

If the canReplyWithIM element contains a true value, the calling user is an Office Communicator user and is capable of receiving IM conversations. The user might choose to respond to the VoIP invitation with a new IM conversation. In this case, the uri element contained in the voIPReceived event must be used when making the voIPReplyWithIM request. The presented dialog should give the user call answering options according to the elements described above.

In the event there is an open IM conversation with the initiator of the VoIP invitation prior to the invitation, the canReplyWithIM element contains a false value. A new IM conversation cannot be started with a user when an IM conversation is currently open with that user.

If the user has chosen to forward all incoming VoIP calls to her voice mail number, the client application must make the voIPTerminate request. The child action element must be filled with the string voicemail to redirect the call to a voice mail number. Finally, the user might want to simply ignore the call. In this case, using the voIPTerminate with an action of none ends the call with no further action.

Note

Development of The dialog discussed in the narrative above is the responsibility of the developer implementing this API.

Examples

In this example, Hao Chen has received a VoIP invitation from Naoki at Contoso.com. The device that Naoki is using to initiate the VoIP is able to accept an IM reply and can also participate in a voice conversation using a telephone handset.

The Unified Communications client application should read the logged-on user's self-presence contact card category to load a list of all of the user's phone numbers into a list on a dialog to display. In addition, the dialog should present the logged-on user with the choice of replying to the invitation with a new IM conversation.

<cwaEvents>
   <conference confId="1" eid="101">
      <voIPReceived>
          <displayName>Naoki Sato</DisplayName>
          <uri>SIP:naokiS@contoso.com</uri>
          <from>"naoki" &lt;naoki@contoso.com&gt;…</from>
          <redirectable>True</redirectable>
          <canReplyWithIM>True</canReplyWithIM>
          <priority>urgent</priority>
          <isConference>False</isConference>
          <subject>Project Deadline Extended</subject>
      </voIPReceived>
   </conference>
</cwaEvents>

Hao has chosen to redirect the VoIP session to her office telephone number. Note the format of the uri value. When redirecting to a telephone, the uri value must be formatted: +1 plus the telephone number without formatting characters such as hyphen and parenthesis.

The Communicator Web Access server redirects the VoIP session to the specified telephone number and the device at that location begins to ring.

<conference rid="10" confId="1">
    <voIPRedirect>
       <uri>tel:+12343336434</uri>
    </voIPRedirect>
</conference>