> 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/pt/servicos-corporativo-for-plan/zoom-contact-center/expert-insights/integrate-engagement-data.md).
# Integrar dados de engajamento
Escrito por Justin Steinberg
### Visão geral
O Zoom central de contato gera dados valiosos de envolvimento durante cada interação com o cliente, incluindo gravações de chamadas (ligar), transcrições, notas do agente e disposições. Continue lendo para aprender como gravar e armazenar dados de envolvimento em sistemas externos (por exemplo, CRM e outros sistemas de registro) para criar uma visão unificada do cliente, Habilitar um coaching eficaz de agentes ou atender aos requisitos de conformidade ao usar o Zoom central de contato.
Vamos detalhar os diferentes métodos de Integrações para ajudar você a Escolher a melhor abordagem com base em como seus agentes podem trabalhar com maior eficiência.
O melhor método depende principalmente de um fator-chave: **o aplicativo onde os agentes estão gerenciando suas interações**. As duas opções que discutiremos são:
1. Agentes usando o Conector ZCC CRM CTI pronto para uso dentro do CRM.
2. Agentes trabalhando no aplicativo Zoom Workplace, o que requer uma solução personalizada com APIs do ZCC e webhooks.
***
### Integrações do Conector CRM CTI pronto para uso
Este é o método mais direto. Se seus agentes estiverem usando um Conector CRM CTI do ZCC, a maioria dos dados de envolvimento poderá ser sincronizada automaticamente entre a plataforma Zoom e o CRM apropriado.
#### Como Funciona
O Conector CTI incorpora a interface do agente ZCC diretamente no CRM. Quando um envolvimento termina, dados como gravações, transcrições, notas e disposições são salvos automaticamente no Zoom e vinculados ao registro relevante (por exemplo, um ticket ou contato) em seu CRM.
#### Requisitos de Configuração
A funcionalidade que permite a sincronização de dados entre o Zoom e o CRM vem "pronta para uso", mas requer ativação no portal de administração do ZCC.
Conclua as etapas a seguir:
{% stepper %}
{% step %}
**Habilitar no portal de administração do ZCC**
Faça login no portal de administração do Zoom como administrador. No [Centro de administração](https://zoom.com/account), vá para gestão de CX → central de contato → Integrações → [Aplicativos](https://zoom.com/cci/index/admin#/admin-integrations).
Encontre a Integração de CRM relevante e selecione "Habilitar" nas Configurações apropriadas para Permitir o armazenamento de dados em seu CRM.
{% endstep %}
{% step %}
**Permissões de CRM**
Revise e siga os [guias de configuração da Integrações de CRM](https://support.zoom.com/) para verificar se o usuário da sua Integrações de CRM tem as permissões de gravação necessárias para todos os objetos relevantes.
{% endstep %}
{% endstepper %}
#### Plataformas de CRM Compatíveis
Esta funcionalidade está disponível por meio do Conector ZCC CRM CTI quando os agentes usam os seguintes CRMs:
* Salesforce
* Zendesk
* ServiceNow
* Microsoft Dynamics
* HubSpot
Com os conectores CRM CTI, nenhuma configuração especial é necessária, e os dados de envolvimento serão salvos no CRM pela Integrações, por padrão.
***
### Integrações personalizadas via APIs
Se seus agentes usarem o aplicativo nativo Zoom Workplace ou o ZCC Smart Embed, você precisará de uma solução personalizada para transferir dados de envolvimento. A principal maneira de fazer isso é com as APIs do Zoom central de contato.
Existem duas abordagens principais para acessar dados de envolvimento via API:
* **Polling:** Consulte periodicamente a API do Zoom para ver se novos dados de envolvimento estão disponíveis.
* **Webhooks:** Receba uma notificação em tempo real do Zoom assim que uma transcrição estiver pronta.
Há também uma terceira abordagem, **Integrações de Flow Events**, que funciona para certos tipos de dados.
#### Consultando as APIs do Zoom central de contato
Para baixar dados de envolvimento, você deve consultar os pontos de extremidade de API apropriados do ZCC. É importante observar que diferentes tipos de dados vêm de APIs diferentes, então você provavelmente precisará criar lógica de polling para cada ponto de extremidade relevante.
Muitas APIs relacionadas a envolvimento nos Relatórios V2 (Análises de CX) agora dão suporte à filtragem por horário de término com `end_time_from` e `end_time_to`. Prefira esses parâmetros quando estiverem disponíveis para que seus trabalhos de polling recuperem os envolvimentos com base em quando eles realmente terminaram. Isso ajuda a reduzir registros perdidos porque os dados completos do envolvimento (incluindo dados do Relatório V2) são finalizados no fim do envolvimento.
| Para Obter Estes Dados... | Consulte Esta API... | Usando Este Campo... | Notas: |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------- |
|
| `transcrição_url` | Requer que a transcrição esteja ativada para a caixa de entrada. |
{% hint style="danger" %}
**Aviso**
Os URLs de download (`download_url`, `transcrição_url`, `playback_url`, e assim por diante) fornecidos por estas APIs do Zoom são **não** links públicos. Eles foram projetados para acesso programático e exigem autenticação da API (por exemplo, token de acesso no cabeçalho Authorization) para baixar o arquivo associado.
Isto significa:
* Você não pode salvar esses URLs diretamente em um CRM para que um usuário clique. Um usuário que clicar no link no navegador não estará autenticado, e o download falhará.
* O método correto é o seu serviço de backend usar o URL para buscar o arquivo. Seu serviço pode então armazenar o arquivo no seu próprio sistema (como Amazon S3, Azure Blob Storage ou o armazenamento de arquivos do seu CRM) e fornecer um link seguro aos seus usuários a partir daí.
{% endhint %}
{% hint style="warning" %}
**Atenção**
**Atrasos no processamento - gravações de voz e vídeo:**
Esses dados não estão disponíveis no instante em que um ligar termina. O áudio precisa ser processado e enviado primeiro, o que pode levar vários minutos em ligações longas. Para garantir que você não perca gravações, defina o `query_date_type` parâmetro para `recording_end_time` ao consultar a API List recordings. Isso obtém dados com base no momento em que o processamento terminou, não quando o ligar terminou.
Para trabalhos de reconciliação centrados em engajamento do Reports V2 (CX Análises), use janelas de tempo sobrepostas com `end_time_from` e `end_time_to` para fornecer uma margem de segurança para processamento atrasado e problemas transitórios de entrega.
{% endhint %}
Para mais informações sobre as APIs do Zoom Central de contato, consulte [APIs da Central de contato](https://developers.zoom.us/docs/api/contact-center/) documentação.
#### Use Webhooks para Eventos em Tempo Real
Para uma abordagem mais imediata, baseada em Evento, você pode assinar os webhooks do ZCC. Este é o método mais eficiente para Integrações quase em tempo real.
**Como Funciona**
1. Subscreva os eventos adequados no Zoom App Marketplace.
2. Quando um Evento ocorre, o Zoom envia uma notificação para a sua URL de webhook (ou para a sua conexão WebSocket).
3. A carga útil do Evento contém os dados de que você precisa, seja diretamente ou como um URL/ID para um ligar posterior à API.
**Eventos de webhook comuns para dados de engajamento**
* **Dados de término da interação prontos:** contato\_center.cx\_engagement\_end\_data\_ready (sinaliza que os dados de denunciar V2 de fim do engajamento estão prontos para recuperação)
* **Gravação de voz/vídeo:** contato\_center.recording\_completed (fornece um `download_url`)
* **Transcrição de voz/vídeo:** central de contato.recording\_transcrição\_completed (fornece um `transcrição_url`)
* **Transcrição de mensagem:** central de contato.engagement\_mensagem\_transcrição\_completed (fornece um `transcrição_url`)
* **Notas:** central de contato.engagement\_note\_added (fornece um `nota` campo com os dados da nota)
* **Disposição:** central de contato.engagement\_disposição\_added (fornece um `disposição_name` campo com os dados da disposição)
**Padrão recomendado: acionar a recuperação quando os dados do engajamento estiverem prontos**
Quando você receber `central de contato.cx_engagement_end_data_ready`, trate-o como o sinal de que os dados da V2 do relatório de fim de engajamento estão completos para esse engajamento. Nesse ponto, chame a API de dados de registro de engajamento histórico e quaisquer outras APIs relevantes para coletar o conjunto final de dados. Neste Evento, use `engagement_id` como sua chave de consulta e, em seguida, busque os artefatos completos do engajamento nos seus pontos de extremidade necessários.
{% hint style="warning" %}
**Atenção**
* **Esteja ciente de vários Eventos:** O `note_added` e `disposição_added` os eventos podem ser acionados várias vezes para um único engajamento (por exemplo, se um agente salvar várias notas ou se uma ligar for transferida). A lógica do seu aplicativo deve ser capaz de lidar com isso.
* **Inclua redundância:** A entrega de Evento nem sempre é 100% garantida (por exemplo, seus pontos de extremidade ou conexão websocket podem estar temporariamente indisponíveis).
* **Estratégia de backup:** Recomendamos executar um script de reconciliação usando APIs de polling com `end_time_from` e `end_time_to` janelas para capturar eventos perdidos e eliminar lacunas nos dados.
{% endhint %}
Para mais informações sobre os eventos de webhook/Websocket da central de contato Zoom, consulte [Webhooks da central de contato](https://developers.zoom.us/docs/api/contact-center/events/) documentação.
#### Integrações de Eventos de fluxo
Para determinados tipos de dados, você pode enviar dados diretamente para um sistema externo a partir do editor de fluxo do ZCC usando um Script de Evento JavaScript.
**Dados compatíveis e limitações:**
* **Disposição:** Pode ser acessado em todos os tipos de canal de engajamento Recebidas usando a `global_system.Engagement.disposição` variável.
* **Transcrição:** Acessível apenas para engajamentos de mensagem Recebidas (por exemplo, Web Chat) usando a `global_system.Engagement.transcrição` variável.
* **Vários fluxos:** Ao trabalhar com vários fluxos na sua configuração, especialmente quando um fluxo usa o `RouteTo` widget para conectar a outro fluxo, é essencial garantir que Scripts de Evento e gatilhos idênticos estejam devidamente configurados em todos os fluxos.
Este método é mais eficaz em um fluxo de mensagem, no qual você pode combinar tanto a transcrição quanto a disposição em um único Evento.
**Etapas de configuração**
Siga estas etapas para Configurar seu fluxo:
{% stepper %}
{% step %}
**Adicionar um Script de Evento**
No seu fluxo do ZCC (por exemplo, um fluxo de Web Chat), clique no widget Iniciar.
Localize Scripts de Evento e Adicionar um Script de Evento para eventos, como Engajamento encerrado e/ou Disposição salva.
{% endstep %}
{% step %}
**Adicionar seu JavaScript personalizado**
O exemplo abaixo recupera tanto a disposição quanto a transcrição e, em seguida, envia ambas juntas para uma API externa.
```javascript
função assíncrona main () {
tente {
// Obter o objeto de disposição a partir da sua variável
const disposição_data = var_get()['global_system.Engagement.disposição'];
// Obtenha o objeto de transcrição completo
const transcrição_data = await req.get(var_get()['global_system.Engagement.transcrição']);
// Prepare um payload com todos os dados que deseja enviar
const payload_to_send = {
disposição: disposição_data.data.result,
transcrição: transcrição_data.data.result.transcrição
};
// Defina o destino dos seus dados
const external_api_url = '';
// Enviar os dados combinados para o seu sistema externo
const response = await req.post(external_api_url, payload_to_send);
// Registrar a resposta do sistema externo para solução de problemas
log.debug("Resposta da API externa: " + JSON.stringify(response.data));
} catch (error) {
log.debug("Ocorreu um erro no script do Evento de transcrição: " + error);
}
}
```
{% endstep %}
{% endstepper %}
***
### Resumo e Recomendações
Escolher o método de Integrações que melhor se alinha ao fluxo de trabalho do seu agente e aos recursos técnicos.
| Se os seus agentes usarem... | Então, sua melhor opção é... | Considerações importantes: |
| -------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| O Conector ZCC CTI em um CRM compatível | A Integrações integrada |
O caminho mais fácil
Nenhum código necessário
A Sincronizar dos dados de engajamento é integrada
|
| O aplicativo Zoom Workplace ou Smart Embed | Webhooks da API mais reconciliação de polling filtrada pelo horário final |
Usar central de contato.cx\_engagement\_end\_data\_ready como o seu gatilho de recuperação
Depois, concilie com end\_time\_from/end\_time\_to janelas
Melhora a eficiência ao mesmo tempo que reduz interações perdidas
|
| Um Fluxo de mensagem Recebidas (e necessidade de enviar dados) | Scripts de Evento do Fluxo |
De nicho, mas poderoso
Requer JavaScript
Funciona melhor para enviar transcrições de mensagem e disposições
|
Ao entender esses diferentes caminhos, você pode construir uma solução de Integrações robusta e confiável que oferece uma visão completa das suas interações com clientes. Combinar a recuperação acionada por Evento com a reconciliação filtrada pelo horário de término ajuda você a reduzir chamadas desnecessárias de API, ao mesmo tempo em que melhora a completude.
---
# 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/pt/servicos-corporativo-for-plan/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.
