> For the complete documentation index, see [llms.txt](https://library.zoom.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://library.zoom.com/technical-library/it/servizi-business/zoom-contact-center/expert-insights/integrate-engagement-data.md).
# Integra i dati di coinvolgimento
Scritto da Justin Steinberg
### Panoramica
Zoom centro di contatto genera dati di engagement preziosi durante ogni interazione con il cliente, incluse le registrazioni delle chiamare, le trascrizioni, gli appunti degli agenti e le disposizioni. Continua a leggere per scoprire come archiviare i dati di engagement in sistemi esterni (ad esempio, CRM e altri sistemi di registrare) per creare una vista unificata del cliente, Abilita un coaching efficace degli agenti o soddisfare i requisiti di conformità quando si utilizza Zoom centro di contatto.
Divideremo i diversi metodi di Integrazioni per aiutarti. Scegli l'approccio migliore in base a come i tuoi agenti possono lavorare con maggiore efficienza.
Il metodo migliore dipende principalmente da un fattore chiave: **l'applicazione in cui gli agenti gestiscono le loro interazioni**. Le due opzioni di cui parleremo sono:
1. Agenti che utilizzano il Connettore CTI CRM ZCC pronto all'uso all'interno del CRM.
2. Agenti che lavorano nell'app Zoom Workplace, il che richiede una soluzione personalizzata con le API ZCC e i Webhook.
***
### Integrazioni del Connettore CTI CRM pronto all'uso
Questo è il metodo più semplice. Se i tuoi agenti utilizzano un Connettore CTI CRM ZCC, la maggior parte dei dati di engagement può essere sincronizzata automaticamente tra la piattaforma Zoom e il CRM appropriato.
#### Come funziona
Il Connettore CTI incorpora l'interfaccia dell'agente ZCC direttamente nel CRM. Quando un engagement termina, dati come registrazioni, trascrizioni, note e disposizioni vengono salvati automaticamente in Zoom e collegati al relativo registrare (per esempio, un ticket o un contatto) nel tuo CRM.
#### Requisiti di configurazione
La funzionalità per consentire la sincronizzazione dei dati tra Zoom e il CRM è disponibile «out of the box», ma richiede l'attivazione nel portale amministratori ZCC.
Completa i seguenti passaggi:
{% stepper %}
{% step %}
**Abilita nel portale amministratori ZCC**
Accedi al portale amministratori Zoom come amministratore. Nel [Centro admin](https://zoom.com/account), vai a CX management → centro di contatto → Integrazioni → [Applicazioni](https://zoom.com/cci/index/admin#/admin-integrations).
Trova le Integrazioni CRM pertinenti e abilita le Impostazioni appropriate per consentire l'archiviazione dei dati nel tuo CRM.
{% endstep %}
{% step %}
**Autorizzazioni CRM**
Rivedi e segui le [Guide di configurazione delle Integrazioni CRM](https://support.zoom.com/) per verificare che il tuo utente di Integrazioni CRM abbia le autorizzazioni di scrittura necessarie per tutti gli oggetti rilevanti.
{% endstep %}
{% endstepper %}
#### Piattaforme CRM supportate
Questa funzionalità è accessibile tramite il Connettore ZCC CRM CTI quando gli agenti usano i seguenti CRM:
* Salesforce
* Zendesk
* ServiceNow
* Microsoft Dynamics
* HubSpot
Con i connettori CRM CTI, non è richiesta alcuna configurazione speciale e le Integrazioni salveranno i dati di engagement nel CRM, in modo predefinito.
***
### Integrazioni personalizzate tramite API
Se i tuoi agenti usano l'app nativa Zoom Workplace o ZCC Smart Embed, avrai bisogno di una soluzione personalizzata per trasferire i dati di engagement. Il modo principale per farlo è con le API di Zoom centro di contatto.
Esistono due approcci principali per accedere ai dati di engagement tramite l'API:
* **Interrogazione:** Interroga periodicamente la API Zoom per vedere se nuovi dati di engagement sono disponibili.
* **Webhook:** Ricevi una Notifica in tempo reale da Zoom non appena una trascrizione è pronta.
Esiste anche un terzo approccio, **Integrazioni Flow Events**, che funziona per determinati tipi di dati.
#### Interrogazione delle API Zoom del centro di contatto
Per scaricare i dati di engagement, devi interrogare gli endpoint API Zoom appropriati. È importante notare che tipi diversi di dati provengono da API diverse, quindi probabilmente dovrai creare una logica di polling per ogni endpoint rilevante.
Molte API relative agli engagement all'interno di Reports V2 (CX analisi) ora supportano il filtraggio dell'orario di fine con `end_time_from` e `end_time_to`. Preferisci questi parametri quando disponibili, così i tuoi job di polling recuperano gli engagement in base a quando sono effettivamente terminati. Questo aiuta a ridurre i record mancanti perché i dati completi dell'engagement (inclusi i dati di report V2) vengono finalizzati alla fine dell'engagement.
| Per ottenere questi dati... | Sondaggio questa API... | Utilizzando questo campo... | Note: |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------- |
|
| `download_url` | Per le segreterie telefoniche lasciate in una casella di posta del centro di contatto. |
| Trascrizione della segreteria telefonica |
| `trascrizione_url` | Richiede che la trascrizione sia abilitata per la casella di posta. |
{% hint style="danger" %}
**Avviso**
Gli URL di download (`download_url`, `trascrizione_url`, `playback_url`, e così via) forniti da queste API Zoom sono **rimborsato** link pubblici. Sono progettati per l'accesso programmatico e richiedono autenticazione API (ad esempio, token di accesso nell'intestazione Authorization) per scaricare il file associato.
Ciò significa:
* Non puoi salvare questi URL direttamente in un CRM affinché un utente ci faccia clic. Un utente che fa clic sul link nel proprio browser non sarà autenticato e il download non andrà a buon fine.
* Il metodo corretto è che il tuo servizio backend utilizzi l'URL per recuperare il file. Il tuo servizio può quindi archiviare il file nel tuo sistema (come Amazon S3, Azure Blob Storage o l'archiviazione file del tuo CRM) e fornire da lì un link sicuro ai tuoi utenti.
{% endhint %}
{% hint style="warning" %}
**Attenzione**
**Ritardi di elaborazione - Registrazioni vocali e video:**
Questi dati non sono disponibili nell'istante in cui una chiamare termina. L'audio deve essere prima elaborato e caricato, il che può richiedere diversi minuti per le chiamate lunghe. Per assicurarti di non perdere le registrazioni, imposta il `query_date_type` parametro su `recording_end_time` quando esegui il polling dell'API List recordings. Questo recupera i dati in base al momento in cui l'elaborazione è terminata, non a quando la chiamare è terminata.
Per i job di riconciliazione incentrati sul coinvolgimento di Reports V2 (CX Analisi), utilizza finestre temporali sovrapposte con `end_time_from` e `end_time_to` per fornire un margine di sicurezza per l'elaborazione ritardata e i problemi temporanei di consegna.
{% endhint %}
Per ulteriori informazioni sulle API di Zoom centro di contatto, vedere [API del centro di contatto](https://developers.zoom.us/docs/api/contact-center/) documentazione.
#### Usa i webhook per gli Eventi in tempo reale
Per un approccio più immediato, guidato dagli eventi, puoi iscriverti ai webhook ZCC. Questo è il metodo più efficiente per ottenere Integrazioni quasi in tempo reale.
**Come funziona**
1. Iscriviti agli eventi appropriati nel Zoom App Marketplace.
2. Quando si verifica un Evento, Zoom invia una Notifica al tuo URL webhook (o alla tua connessione WebSocket).
3. Il payload dell'Evento contiene i dati di cui hai bisogno, direttamente oppure come URL/ID per chiamare l'API in un secondo momento.
**Eventi Webhook comuni per i dati di coinvolgimento**
* **Dati di fine coinvolgimento pronti:** contatto\_center.cx\_engagement\_end\_data\_ready (segnala che i dati del report V2 di fine coinvolgimento sono pronti per essere recuperati)
* **Registrazione Voce/Video:** contatto\_center.recording\_completed (fornisce un `download_url`)
* **Trascrizione voce/video:** contatto\_center.registrazione\_trascrizione\_completata (fornisce una `trascrizione_url`)
* **Trascrizione della messaggistica:** contatto\_center.engagement\_messaggistica\_trascrizione\_completata (fornisce una `trascrizione_url`)
* **Note:** contatto\_center.engagement\_nota\_aggiunta (fornisce una `nota` campo con i dati della nota)
* **Disposizione:** contatto\_center.engagement\_disposizione\_aggiunta (fornisce una `nome_disposizione` campo con i dati della disposizione)
**Pattern consigliato: attiva il recupero quando i dati di engagement sono pronti**
Quando ricevi `contatto_center.cx_engagement_end_data_ready`, consideralo il segnale che i dati V2 del report di fine engagement sono completi per quell'engagement. A quel punto, dovrai chiamare l'API dei dati di log di Historical Engagement e qualsiasi altra API pertinente per raccogliere il set di dati finale. In questo Evento, usa `engagement_id` come chiave di ricerca e poi recupera gli artefatti completi dell'engagement dai tuoi endpoint richiesti.
{% hint style="warning" %}
**Attenzione**
* **Fai attenzione a più Eventi:** La `note_added` e `disposizione_added` gli eventi possono attivarsi più volte per un singolo coinvolgimento (ad esempio, se un agente salva diverse note o una chiamata viene trasferita). La logica della tua applicazione deve essere in grado di gestirlo.
* **Ridondanza incorporata:** La consegna dell'Evento non è sempre garantita al 100% (ad esempio, il tuo endpoint o la connessione websocket potrebbero essere temporaneamente non disponibili).
* **Strategia di backup:** Consigliamo di eseguire uno script di riconciliazione utilizzando le API di polling con `end_time_from` e `end_time_to` finestre per intercettare gli eventi mancanti e colmare le lacune nei dati.
{% endhint %}
Per ulteriori informazioni sugli eventi di Zoom centro di contatto webhook/Websocket, vedi [webhook del centro di contatto](https://developers.zoom.us/docs/api/contact-center/events/) documentazione.
#### Integrazioni degli eventi di Flow
Per alcuni tipi di dati, puoi inviare i dati direttamente a un sistema esterno dall'editor Flow di ZCC utilizzando uno script di Evento JavaScript.
**Dati supportati e limitazioni:**
* **Disposizione:** Può essere accessibile su tutti i tipi di canale di coinvolgimento In entrata utilizzando la `global_system.Engagement.disposizione` variabile.
* **Trascrizione:** Disponibile solo per coinvolgimenti di messaggistica In entrata (ad esempio, Web chat) utilizzando la `global_system.Engagement.trascrizione` variabile.
* **Più Flow:** Quando si lavora con più Flow nella configurazione, in particolare quando un Flow utilizza il `RouteTo` widget per connettersi a un altro Flow, è essenziale assicurarsi che Script di Evento e trigger identici siano Configura correttamente in tutti i Flow.
Questo metodo è più potente in un Flow di messaggistica, dove puoi combinare sia la trascrizione sia la disposizione in un singolo Evento.
**Passaggi di configurazione**
Segui questi passaggi per Configura il tuo flow:
{% stepper %}
{% step %}
**Aggiungi uno Script di Evento**
Nel tuo Flow ZCC (ad esempio, un flow Web chat), fai clic sul widget Start.
Individua gli Script di Evento e Aggiungi uno Script di Evento per gli Eventi, come Engagement Closed e/o disposizione salvata.
{% endstep %}
{% step %}
**Aggiungi il tuo JavaScript personalizzato**
L'esempio seguente recupera sia la disposizione sia la trascrizione, quindi le invia insieme a un'API esterna.
```javascript
funzione async main () {
try {
// Ottieni l'oggetto disposizione dalla sua variabile
const disposizione_data = var_get()['global_system.Engagement.disposizione'];
// Ottieni l'oggetto trascrizione completo
const trascrizione_data = await req.get(var_get()['global_system.Engagement.trascrizione']);
// Prepara un payload con tutti i dati che vuoi inviare
const payload_to_send = {
disposizione: disposizione_data.data.result,
trascrizione: trascrizione_data.data.result.trascrizione
};
// Definisci la destinazione per i tuoi dati
const external_api_url = '';
// Invia i dati combinati al tuo sistema esterno
const response = await req.post(external_api_url, payload_to_send);
// Registra la risposta dal sistema esterno per la risoluzione dei problemi
log.debug("Risposta API esterna: " + JSON.stringify(response.data));
} catch (error) {
log.debug("Si è verificato un errore nello script Evento della trascrizione: " + error);
}
}
```
{% endstep %}
{% endstepper %}
***
### Riepilogo e raccomandazioni
Scegli il metodo di Integrazioni che meglio si allinea al flusso di lavoro dei tuoi agenti e alle risorse tecniche.
| Se i tuoi agenti usano... | Allora la tua migliore opzione è... | Considerazioni chiave: |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Il Connettore ZCC CTI in un CRM supportato | Le Integrazioni integrate |
Percorso più semplice
Nessun codice richiesto
La Sincronizza dei dati di Engagement è già integrata
|
| L'app Zoom Workplace o Smart Embed | Webhook API più riconciliazione del polling filtrata in base all'orario di fine |
Usa contatto\_center.cx\_engagement\_end\_data\_ready come trigger di recupero
Poi riconcilia con end\_time\_from/end\_time\_to finestre
Migliora l'efficienza riducendo al contempo gli engagement mancati
|
| Un flusso di messaggistica In entrata (e la necessità di inviare dati) | Script Evento del flusso |
Di nicchia, ma potente
Richiede JavaScript
Funziona meglio per inviare trascrizioni di messaggistica e disposizioni
|
Comprendendo questi diversi percorsi, puoi costruire una soluzione di Integrazioni robusta e affidabile che ti offre una visione completa delle interazioni con i clienti. Combinare il recupero attivato da Evento con la riconciliazione filtrata in base all'ora di fine ti aiuta a ridurre le chiamate API non necessarie, migliorando al contempo la completezza.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://library.zoom.com/technical-library/it/servizi-business/zoom-contact-center/expert-insights/integrate-engagement-data.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
