Estendere il widget con la live chat SDK
Il widget standard che copi dal workstream con Copy Live Chat Widget 2.0 Script copre la maggior parte dei casi, ma quando serve controllare aspetto e comportamento la documentazione indica due strade distinte.
La prima è il customizable live chat widget 2.0, costruito sopra Omnichannel Chat SDK e Live Chat Widget UI Component Library. Al portal developer basta modificare lo snippet: aggiungere “v2” dopo l’attributo dello script e aggiungere data-customization-callback puntando a una funzione JavaScript che contiene lo styling CSS dei componenti. Questa strada personalizza la UI ma non tocca le impostazioni funzionali configurate in Copilot Service admin center.
La seconda è costruire il proprio widget con la Omnichannel Live Chat Widget UI Components library, un insieme di componenti React riusabili basati su Fluent UI, insieme alla Omnichannel Chat SDK, pacchetto open source che espone metodi e funzionalità di chat. Attenzione a un vincolo esplicito: “The Omnichannel Chat SDK is a prerequisite for installing the Omnichannel Live Chat Widget UI Components library.”
Sul widget web lato client agisci invece con i metodi della live chat SDK, esposti dal namespace Microsoft.Omnichannel.LiveChatWidget.SDK: startChat, closeChat, startProactiveChat, getAgentAvailability, la terna setContextProvider / getContextProvider / removeContextProvider e la terna setAuthTokenProvider / getAuthTokenProvider / removeAuthTokenProvider. Gli eventi sono altrettanto d’esame: lcw:ready, lcw:error, lcw:startChat, lcw:closeChat, lcw:chatQueued, lcw:chatRetrieved, lcw:threadUpdate, lcw:onMessageReceived, lcw:onMessageSent, lcw:onMinimize, lcw:onMaximize. La regola operativa da ricordare è che i metodi vanno invocati dopo che l’evento lcw:ready è stato sollevato.
Esiste poi una terza strada dichiarativa, la web engagement orchestration: sposta gli override di configurazione dal JavaScript delle tue pagine all’admin center, tramite Engagement Rulesets, versioni e regole con Conditions e Actions, e ti fa distribuire un unico tag di script su tutto il sito. La documentazione applica questa funzionalità a Dynamics 365 Contact Center (embedded e standalone) e a Dynamics 365 Customer Service.
Le authentication settings, e quando non sono un optional
Le authentication settings servono a validare un cliente già autenticato su un dominio ed estrarre informazioni dalle context variables definite, così da distinguere clienti anonimi e autenticati e costruire regole su quelle variabili. I canali supportati sono Chat e Apple Messages for Business, e per quest’ultimo il supporto è dichiarato deprecato.
Il record si crea in Copilot Service admin center, in Customer support > Customer Settings > sezione Authentication settings > Manage > New Authentication Settings, compilando Name, Owner, Authentication type (OAuth 2.0, non modificabile), Public key URL e Javascript client function. Poi va agganciato: si apre il chat widget nelle impostazioni del workstream, scheda Behaviors, campo Authentication settings. Creare il record senza associarlo non produce nulla.
Il flusso lato sviluppo richiede una coppia di chiavi RSA256, un endpoint che espone la chiave pubblica e un servizio che genera il JWT con almeno i claim iss, iat, exp e sub (dove sub porta il GUID del record contact o account) più lwicontexts per le context variables. Due dettagli che l’esame ama: la funzione JavaScript deve restituire il JWT entro 10 secondi per evitare il timeout, e il metodo setContextProvider non è supportato per la chat autenticata, quindi i contesti vanno passati dentro il payload del JWT. Il representative, cioè l’operatore umano, vede l’esito nel campo Authenticated della sezione Conversation summary, impostato a Yes o No.
Qui sta il punto che rende l’autenticazione un prerequisito e non una scelta estetica: la pagina della persistent chat elenca fra i prerequisiti che le authentication settings siano configurate. Senza autenticazione non abiliti la chat persistente con la casella Make chats persistent, né hai senso nel mostrare Show previous conversations.
Mobile nativo: Messaging SDK, non WebView
Per un’app mobile nativa la documentazione offre due opzioni e prende posizione netta: “We strongly recommend that you use the native mobile SDKs because they deliver superior feature support and performance.” Le SDK sono pubblicate su GitHub come Contact Center Messaging SDK - Android e Contact Center Messaging SDK - iOS, e contengono un’app di esempio, un’interfaccia di messaggistica pronta all’uso, l’insieme completo delle funzioni di ciclo di vita per costruire una UI su misura e il supporto alle notifiche push con Azure Notification Hub. Due note importanti: lo stile dell’interfaccia pronta si definisce via codice nell’app, non dall’admin center; e Microsoft raccomanda di usare le SDK con chat autenticata e persistente.
L’alternativa è renderizzare il widget web dentro una WebView, componente disponibile sia su Android sia su iOS. È possibile, ma dichiarato limitato per prestazioni, usabilità e funzionalità: “Live chat widget features such as escalating to voice and video and downloading the chat transcript aren’t supported through a webview.” In quello scenario userai i data tag data-render-mobile e data-hide-chat-button, abiliterai il DOM storage su Android e chiuderai la conversazione chiamando closeChat, eventualmente in ascolto di lcw:threadUpdate quando è il representative a terminarla. Una confusione tipica da evitare: la web engagement orchestration non copre questo scenario, perché la doc dice esplicitamente che vale solo per il web e non per le contact center messaging SDK di iOS e Android.
Un canale tutto tuo con le messaging API
Le messaging API sono endpoint RESTful pensati per integrazioni service-to-service, che permettono di portare dentro l’omnichannel un canale di messaggistica non supportato nativamente senza SDK né interfacce lato client. Consentono di avviare e chiudere conversazioni, inviare messaggi e allegati per conto del cliente, ricevere aggiornamenti in tempo reale via webhook e gestire il contesto della conversazione. Gli endpoint sono POST /conversation/create, il POST sulla singola conversazione per messaggi, typing e chiusura, GET /conversations, il GET dei messaggi e il GET del contesto, più il webhook che riceve messaggi ed eventi con payload conformi al Bot Framework Activity Schema.
La configurazione richiede il ruolo System Administrator, un messaging workstream con regole di routing e una sottoscrizione Azure attiva. Si registra un’app confidential client in Microsoft Entra, si ottiene un token OAuth 2.0 e ogni chiamata porta gli header Authorization, channel-id e organization-id: senza header di autenticazione la chiamata risponde 401 Unauthorized. Il canale vive come record nella tabella msdyn_occustommessagingchannel, con i campi msdyn_appid, msdyn_tenantid e msdyn_webhookurl; l’autenticazione del webhook si appoggia alla managed identity di Power Platform e a una federated credential costruita sul FICSubject ottenuto da GetComponentManagedIdentityFIC. Infine il canale va aggiunto al workstream seguendo la procedura del custom channel.
Non confondere questa strada con il custom channel via Direct Line API 3.0, che passa da un agent registrato su Azure Bot Service e si configura in Customer support > Channels > Messaging accounts, scegliendo Custom come Channel e Azure bot framework come Method. E ricorda l’avvertenza esplicita: le messaging API non sono raccomandate per app mobile o web che le invochino direttamente dal dispositivo dell’utente; per gli scenari client-to-service la doc rimanda alle SDK native o ai chat widget.