Ad-hoc phone number dialing using the Office Communicator SDK
I'm gonna chalk this up to one of things that's painfully obvious after the fact... I'm using the IMessengerAdvanced::StartConversation method of the Office Communicator automation SDK to dial ad-hoc phone numbers, e.g. simply dialing Clarity's front desk at +13128633100 as opposed to selecting a contact in Communicator and dialing one of its listed phone numbers.
Communicator would attempt to dial the number but the call to StartConversation would throw a not-so-helpful COMException.
vConversationData
The SDK documentation describes the StartConversation method, but is vague on its parameters. The trick here is to correctly populate the vConversationData parameter.
Here's what the SDK says about the vConversationData parameter:
A VARIANT value to hold a XML binary large object (BLOB) used to send data dependent on the chosen conversation type. For focus-based conference call, this parameter is used to pass in the conference URI as the content of a <ConfURI> element. For PSTN calls, the parameter contains an array of TEL URIs, as a <TelURIs> element.
Pretty misleading, because we won't be BLOB'ing anything!
Formatting Phone Numbers
Before being passed to the StartConversation method, phone numbers have to be prefixed with tel: to explicitly specify that this is a phone number.
As part of configuration Office Communications Server for voice, you can add regular expressions to normalize the way Communicator dials phone numbers, e.g. when I simply dial 39XX, Communicator knows that this is my Clarity extension and dials it as +131286339XX.
What this means is that if you have these rules in place, you don't need to worry much about normalizing the phone number before passing it to the StartConversation method.
Of course, if you specify a phone number that doesn't match any of your normalizing regular expressions, Communicator won't be able to make the phone call. Communicator handles this gracefully, you don't need to handle an exception in your code.
IMessengerAdvanced::StartConversation
Here's the obvious part:
The way the vConversation data document was phrased, I was trying stuff like:
<TelURIs><TelURI>tel:+13128633100</TelUri></TelURIs>
XML Blob, I think not ...