Screen pop nativo nell'Agent Desktop di SSCV2: quello che il PDF non vi dice

Ad agosto 2026 abbiamo spostato il nostro widget telefonico da un pannello laterale personalizzato allo screen pop nativo dell’Agent Desktop di SAP Sales and Service Cloud V2. Arriva una chiamata, l’agente vede chi chiama, si apre l’area di lavoro giusta e, quando la chiamata finisce, finisce anche la sessione. Sulla carta è semplice. La parte interessante è tutto ciò che la guida pubblica di integrazione non dice.

In sintesi: la shell dell’Agent Desktop analizza solo XML, mappa solo le azioni NOTIFY ed END e riconosce una sessione esclusivamente dal suo ExternalReferenceID (un UUID). Un END chiude la sessione internamente, ma non rimuove la scheda di sessione. Per rimuovere una scheda inviate un payload OUTBOUND senza elemento Action con il riferimento della scheda e subito dopo l’END. Se aspettate tra i due, resta aperta una scheda di lavoro.

Nella prima versione di questo articolo consigliavamo di «attendere che l’attività telefonica sia trovabile, poi chiudere». Le misurazioni su chiamate reali di settembre 2026 hanno dimostrato che era sbagliato; la sezione sui tempi qui sotto sostituisce quel consiglio.

Perché l’Agent Desktop ignora i payload CTI in JSON?

Il widget CTI gira in un frame dentro l’Agent Desktop e comunica con la shell tramite l’API postMessage del browser. SAP descrive l’approccio a widget nella guida SAP Service Cloud Version 2 integration with Third-Party CTI Providers. Quello che la guida non rende evidente: la shell che abbiamo testato analizza solo XML. Inviate lo stesso contenuto in JSON, come suggeriscono alcuni esempi, e non succede nulla. Nessun errore, nessuna riga di log. Il vostro adattatore crede di essere integrato; la shell crede che nessuno abbia chiamato.

Quel silenzio ci è costato un pomeriggio che un solo messaggio d’errore avrebbe ridotto a dieci minuti. Una volta nota la regola, il contratto XML è stabile e contenuto. Una notifica minima per una chiamata in entrata ha questo aspetto:

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

Tre regole che abbiamo verificato sulla shell:

• Solo NOTIFY ed END sono azioni. Qualsiasi altro valore di Action, ACCEPT compreso, resta vuoto. Sembra un limite; è invece la leva per il problema delle schede più avanti.
• EventType viene convertito in maiuscolo e ripreso come tipo di sessione. I valori che funzionano sono INBOUND, OUTBOUND, UPDATE_ACTIVITY, TRANSFER, PUSH, CALLENDED e CALL_ERROR.
• ExternalReferenceID deve essere un UUID. È l’unica chiave con cui la shell riconosce una sessione.

Quale ID deve coincidere in tutti i messaggi CTI?

L’intera sessione dipende da quell’unico ExternalReferenceID. Deve essere identico in ogni messaggio relativo alla chiamata e nell’attività telefonica che il widget crea nel CRM. Se due componenti generano ciascuna il proprio ID, si ottiene il peggior errore possibile: la parte visibile funziona, la pulizia no, e a mezzogiorno l’agente ha il desktop pieno di sessioni orfane.

La disciplina sugli ID è noiosa, ed è proprio per questo che sfugge. Generate l’UUID una volta sola all’arrivo della chiamata, passatelo a ogni componente, non rigeneratelo mai.

Perché le schede di sessione dello screen pop non si chiudono?

Qui la guida vi lascia soli. L’Agent Desktop mostra due elementi diversi, che spariscono in modi diversi:

	Popover	Scheda di sessione
Dove	Accanto alla barra CTI ridotta	Sopra le schede di lavoro, anche con la barra aperta
Quando è visibile	Solo finché la barra CTI è ridotta; aprendo la barra si chiude	Finché la shell non la filtra tramite l’ID di riferimento
Si rimuove con	Conferma dalla vista dock	Un payload che entra nel blocco di avvio sessione della shell

Due comportamenti ci hanno sorpreso. Un END chiude la sessione nello stato interno della shell, ma non rimuove la scheda di sessione. E la notifica a comparsa non viene mai confermata con END. Entrambe le cose deve gestirle il widget.

Il payload che rimuove una scheda rimasta a schermo è questo, senza elemento Action e con il riferimento della scheda ancora visibile:

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

Perché funziona: la shell rimuove una scheda solo all’interno del blocco che gestisce l’avvio di una sessione, e salta quel blocco per NOTIFY, END, UPDATE_ACTIVITY, CALLENDED e CALL_ERROR. Omettere Action è ciò che vi fa entrare. OUTBOUND è il tipo di evento giusto perché la shell non crea alcuna interazione: non si apre una nuova scheda di lavoro, mentre il filtro che rimuove la scheda viene comunque eseguito.

Inviare avvio ed END uno dopo l’altro

Il rovescio della medaglia: questo payload avvia anche una sessione. La rimozione della scheda è un effetto collaterale del blocco, non il suo scopo. L’END per lo stesso riferimento deve quindi seguire immediatamente.

Lo abbiamo misurato su chiamate reali a settembre 2026. Quando tra l’avvio e l’END passavano alcuni secondi (nella nostra prima versione perché l’END attendeva che l’attività telefonica fosse creata e indicizzata), la shell apriva una scheda dell’Agent Desktop con il timer in corsa e metteva il badge verde di sessione sull’icona CTI. L’END tardivo non la richiudeva più. Il nostro consiglio originale, «attendere che l’attività sia trovabile, poi chiudere», produceva esattamente questo.

La sequenza che funziona:

1. Fine chiamata: create o aggiornate l’attività telefonica nel CRM con lo stesso ID di riferimento, con i suoi tempi.
2. Rimozione della scheda: inviate il payload OUTBOUND senza Action per il riferimento ancora visibile.
3. Subito dopo, inviate l’END per quel riferimento.
4. Chiudete notifica e popover dal widget, perché la shell non lo fa.

Quando ci si integra con una scatola nera, bisogna prevedere l’osservazione, non solo la lettura. Il contratto su cui si va in produzione è quello che si misura.

Come introdurre lo screen pop nativo?

Dietro un interruttore, tenant per tenant. La telefonia è l’unica integrazione in cui ogni agente nota ogni regressione in pochi minuti. Abbiamo attivato la modalità nativa un tenant alla volta, ed è questo che ci ha permesso di imparare senza un telefono di supporto rovente. Prima di attivare un tenant verifichiamo quattro punti:

• Ogni payload è XML e nessun percorso di codice invia ancora JSON.
• Un UUID per chiamata, riutilizzato in ogni messaggio e nell’attività telefonica.
• Rimozione della scheda ed END partono insieme, senza attese.
• Una chiamata di prova in entrata e in uscita non lascia schede, notifiche né schede di lavoro aperte.

Il codice della shell cambia con i rilasci SAP, quindi ripetiamo la chiamata di prova dopo ogni rilascio. Se sviluppate anche voi sull’Agent Desktop e osservate un comportamento che contraddice questo articolo, fatecelo sapere.

Dove si colloca

Lo screen pop è l’ultimo passo di un’integrazione CTI, non il primo. Per l’architettura attorno (identificazione del chiamante, attività telefoniche, lato del provider telefonico) leggete la nostra guida tecnica all’integrazione CTI con SAP Sales Cloud V2. Il widget stesso è costruito come app personalizzata su SAP BTP, e come usiamo Sales e Service Cloud V2 nella nostra azienda lo raccontiamo in come usiamo noi stessi SAP Sales Cloud e Service Cloud.

Il comportamento dell’Agent Desktop descritto sopra non compare nella guida pubblica di integrazione; la documentazione SAP di Service Cloud V2 copre l’interfaccia CTI supportata. Realizziamo queste integrazioni telefoniche su SAP BTP nell’ambito di Service Cloud V2. Scriveteci.