Dynamics 365 Telephony Integration for Developers (Part 3): Click-to-Dial & Screen Pop

This is Part 3 of our developer series on Dynamics 365 telephony integration. In Part 2 we set up the widget and its event-handling structure. Now let's implement the two features agents notice immediately: click-to-dial and screen pop.

Click-to-Dial: Letting Agents Dial From a Record

Click-to-dial means an agent clicks a phone number displayed on a Dynamics 365 record, and your widget receives that number and starts a call. Dynamics 365 automatically turns phone number fields into clickable links, and CIF v2 exposes an event called "onclicktoact" that fires whenever one of those links is clicked.

Microsoft.CIFramework.addHandler("onclicktoact", function (event) {
  const phoneNumber = event.data;
  startCallWithYourProvider(phoneNumber);
});

The startCallWithYourProvider function is where your own telephony SDK takes over, actually dialing the number through whatever backend you're using, whether that's a Twilio Voice SDK call, a SIP invite, or a request to your own calling API.

It's worth handling a few edge cases here: phone numbers can arrive with inconsistent formatting (spaces, dashes, country codes), so normalizing the number before dialing will save you a lot of support tickets later.

Screen Pop: Opening the Right Record Automatically

Screen pop is the feature where, the instant a call comes in, the matching customer record opens automatically, without the agent lifting a finger. Your widget receives the caller ID from your telephony backend, and then asks CIF v2 to search Dynamics 365 for a matching contact and open it.

Microsoft.CIFramework.searchAndOpenRecords(
  JSON.stringify({
    entityName: "contact",
    searchOptions: { filter: "telephone1 eq '" + callerNumber + "'" }
  }),
  true
);

The second argument (true) tells CIF to open the record automatically if exactly one match is found. If no match is found, most implementations fall back to creating a new contact or a new phone call activity so the agent still has somewhere to take notes, rather than staring at a blank screen while the caller is already talking.

Handling Multiple Matches Gracefully

Sometimes a phone number matches more than one record, for example a shared office line. Instead of guessing, it's better to have your widget present a short list of matches for the agent to pick from, using a simple search call rather than the auto-open version, so the agent stays in control of which record gets associated with the call.

Testing These Two Features Together

A good way to validate both features end to end is to simulate an inbound call to a known test contact's number and confirm the record opens within a second or two, then click a phone number on a different record and confirm your provider receives the correctly formatted number. Doing this in a sandbox environment before rolling out to production agents will catch most formatting and timing issues early.

What's Next

With click-to-dial and screen pop working, Part 4 of this series covers what happens after the call: automatically logging call activities in Dataverse, and handling authentication securely so your integration is ready for production.