Getting rerouted messages to the right UCMA endpoint

One of the great things you can do with the Lync Server SDK is reroute calls to a UCMA application. Your MSPL script or managed SIP application can intercept any call that goes through the Front End Server (or any SIP request or response, more generally) and send it to a UCMA application you’ve written, rather than the originally intended recipient. Your application can then handle the request, and proxy it through to the destination, or block it, or do something else entirely. There are more uses for this than I can possibly describe here: recording, call filtering, auto-attendants, compliance, call billing, you name it.

Typically in a case like this the UCMA application has a default routing endpoint so that it will answer all of these calls that have a To SIP URI that doesn’t belong to the application. But what if you don’t want all rerouted calls to go to a single endpoint? What if you need to have a number of endpoints in your application – let’s say one for recording and another for call filtering – and your Lync Server SDK application needs to somehow specify which of the endpoints the rerouted call should go to?

You can’t define multiple default routing endpoints – by definition there can be only one, since it’s the catch-all endpoint where requests go when they can’t be matched to any other endpoint. But what you can do is use the ms-application-aor header.

This is a relatively little-known header that is sort of UCMA’s last resort option for matching requests to endpoints. UCMA checks for it if it can’t find an endpoint for a request based on the To header or the Conversation ID. If the header is present on a request, and it contains a SIP URI matching exactly one endpoint that the application has active, the request will go to that endpoint.

There are a couple of caveats. First, the SIP URI in the ms-application-aor header has to be what’s called an “owner URI,” or “address of record” (which is what the “aor” part of the header name stands for). That means it has to be a SIP URI that belongs to a user (e.g. sip:user@example.com), not a SIP URI like a GRUU that belongs to the specific endpoint.

Second, the ms-application-aor header has to contain a SIP URI that matches exactly one, and no more than one, endpoint managed by the application. If the application has two endpoints registered for the same user (rare, but possible) UCMA won’t be able to match the request to a specific one and will return a 485 Ambiguous failure response.

Adding the header itself is fairly simple. In MSPL, you would do something like the following:

AddHeader("ms-application-aor", "sip:specificuser@example.com");

If you then proxy the request to your UCMA application, it will go to the endpoint with the SIP URI sip:specificuser@example.com.