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

In August 2026 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 public integration guide does not say.

TL;DR: The Agent Desktop shell parses XML only, maps only the actions NOTIFY and END, and recognises a session solely by its ExternalReferenceID (a UUID). An END ends the session internally but does not remove the session card. To clear a card, send an OUTBOUND payload without an Action element for the card’s reference, and send the END immediately after it. Waiting between the two leaves a tab open.

We first published this post with the advice “wait until the call activity is findable, then end”. Measurements on real calls in September 2026 showed that this is wrong, so the timing section below replaces it.

Why does the Agent Desktop ignore JSON CTI payloads?

The CTI widget runs in a frame inside the Agent Desktop and talks to the shell through the browser’s postMessage API. SAP describes the widget approach in the guide SAP Service Cloud Version 2 integration with Third-Party CTI Providers. What the guide does not make obvious: the shell we tested only parses XML. Send the same content as JSON, as some examples suggest, and nothing happens. 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. Once you know it, the XML contract is stable and small. A minimal inbound notification looks like this:

<payload>
  <Type>CALL</Type>
  <EventType>INBOUND</EventType>
  <Action>NOTIFY</Action>
  <ANI>+41410000000</ANI>
  <ExternalReferenceID>3f2b6c1e-8d4a-4f7e-9a51-2c0d7e9b4a10</ExternalReferenceID>
</payload>

Three rules we verified against the shell:

• Only NOTIFY and END are actions. Any other Action value, ACCEPT included, is left empty. This sounds like a limitation; it is the lever for the card problem further down.
• EventType is upper-cased and taken over as the session type. The values that work are INBOUND, OUTBOUND, UPDATE_ACTIVITY, TRANSFER, PUSH, CALLENDED and CALL_ERROR.
• ExternalReferenceID must be a UUID. It is the only key by which the shell recognises a session again.

Which ID must match across CTI messages?

The whole session hangs on that one ExternalReferenceID. It must be identical in every message for the call and in the phone activity your widget creates in the CRM. Let two components each generate 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 stale sessions.

ID discipline is boring, which is exactly why it slips. Generate the UUID once when the call arrives, pass it along to every component, never regenerate it.

Why do screen-pop session cards not close?

This is where the guide leaves you alone. The Agent Desktop shows two different things, and they disappear in different ways:

	Popover	Session card
Where	Next to the minimised CTI bar	Above the tabs, also with the bar open
When visible	Only while the CTI bar is minimised; opening the bar closes it	Until the shell filters it out by reference ID
Removed by	Acknowledgement from the dock view	A payload that falls into the shell’s session-start block

Two behaviours surprised us. An END ends the session in the shell’s internal state, but it does not remove the session card. And the notification toast is never acknowledged on END. Both have to be cleared by the widget itself.

The payload that removes a standing card is this one, with no Action element and the reference of the card that is still on screen:

<payload>
  <Type>CALL</Type>
  <EventType>OUTBOUND</EventType>
  <ANI>+41410000000</ANI>
  <ExternalReferenceID>3f2b6c1e-8d4a-4f7e-9a51-2c0d7e9b4a10</ExternalReferenceID>
</payload>

Why it works: the shell removes a card only inside the block that handles a session start, and it skips that block for NOTIFY, END, UPDATE_ACTIVITY, CALLENDED and CALL_ERROR. Leaving Action out is what gets you in. OUTBOUND is the right event type because the shell creates no interaction for it: no new workspace tab opens, while the filter that removes the card still runs.

Send start and END back to back

The catch: that payload also starts a session. Removing the card is a side effect of the block, not its purpose. So the END for the same reference has to follow immediately.

We measured this on real calls in September 2026. When several seconds passed between the start and the END (in our first version because the END waited for the phone activity to be created and indexed), the shell opened an Agent Desktop tab with a running timer and put the green session badge on the CTI icon. The late END did not bring it back. Our original advice, “wait until the activity is findable, then end”, produced exactly that.

The sequence that works:

1. Call ends: create or update the phone activity in the CRM, carrying the same reference ID. Do this on its own schedule.
2. Clear the card: send the OUTBOUND payload without Action for the standing reference.
3. In the same breath, send END for that reference.
4. Clear the toast and popover from the widget, because the shell will not do it for you.

When you integrate against a black box, plan for observation, not only for reading. The contract you ship against is the one you measure.

How should you roll out native screen pop?

Behind a flag, per tenant. Telephony is the one integration where every agent notices every regression within minutes. We rolled the native mode out tenant by tenant, which is what let us learn these lessons without a hot support phone. Before switching a tenant on, we check four things:

• Every payload is XML, and no code path still sends JSON.
• One UUID per call, reused in every message and in the phone activity.
• Card removal and END are sent together, with no waiting in between.
• A test call inbound and outbound leaves no card, no toast and no open tab behind.

The shell code changes with SAP releases, so we re-run that test call after each release. If you are building against the Agent Desktop yourself and see behaviour that contradicts this post, tell us.

Where this fits

Screen pop is the last step of a CTI integration, not the first. For the architecture around it (caller lookup, phone activities, the telephony provider side) read our technical guide to CTI integration with SAP Sales Cloud V2. The widget itself is built as a custom app on SAP BTP, and how we use Sales and Service Cloud V2 in our own company is described in how we run SAP Sales Cloud and Service Cloud ourselves.

The Agent Desktop behaviour above is not in the public integration guide; SAP’s Service Cloud V2 documentation covers the supported CTI surface. We build this kind of telephony integration on SAP BTP as part of Service Cloud V2 delivery. Ask us about your setup.