Native Screen Pop in the SSCV2 Agent Desktop: What the PDF Does Not Tell You

This month we moved our telephony widget from a custom side panel to the native screen pop of the SAP Sales and Service Cloud V2 Agent Desktop. A call comes in, the agent sees the caller, the right workspace opens, and when the call ends, the session ends. Simple on paper. The interesting part was everything the official documentation does not say.

Three lessons stuck.

Silence is the worst error message

The Agent Desktop shell and the CTI widget talk to each other through browser postMessage events, and the payload has to be XML. Not JSON, XML, in the year 2026. Send the same content as JSON and the shell’s reaction is nothing at all. No error, no log line. Your adapter believes it is integrated; the shell believes nobody called. That silence cost us an afternoon that a single error response would have turned into ten minutes.

The lesson is general: when you integrate against a black box, plan for observation, not just for reading. The contract you actually ship against is the one you measure, prima vista impressions included.

One ID, everywhere, or nothing correlates

The whole session hangs on one external reference ID that must be identical across every message and the call activity in the CRM. Let two components each invent their own ID and you get the ugliest failure mode there is: the visible part works, the cleanup does not, and by lunchtime the agent has a desktop full of zombie sessions.

ID discipline is boring, which is exactly why it slips. Generate once, pass it along, never regenerate.

You inherit the other system’s timing

Ending a session only works when the shell can find the call activity, and the search index behind that lookup lags a few seconds behind reality. Send the goodbye too early and it misses; nobody says goodbye twice, so the session lives forever.

Our fix: settle, wait until the activity is actually findable, then end, and end again if needed. Elegant? No. Correct against the system as it really behaves? Yes. When you integrate against an index, its timing becomes your timing, whether the PDF mentions it or not.

And ship it behind a flag

We rolled the native mode out per tenant, behind a flag. Telephony is the one integration where every agent notices every regression within minutes. A controlled rollout is not caution for its own sake; it is what let us learn these lessons without a hot support phone.

If you are building against the Agent Desktop yourself and see behaviour that contradicts this post, tell us. This contract was assembled a posteriori, one surprise at a time.