Conector de entrada do link do XM Discover

Sobre o conector de entrada do link do XM Discover

Você pode usar o conector de entrada de links do XM Discover para enviar dados do XM para o XM Discover por meio de um ponto de acesso da API REST e, ao mesmo tempo, aproveitar todos os recursos oferecidos pela estrutura de conectores, como mapeamento de campos, transformações, filtros, observação de trabalhos etc.

Formatos de dados suportados

Os seguintes tipos de dados só são suportados no formato JSON:

• Feedback individual
• Interações digitais
• Transcrições de chamada

Antes de configurar o conector, crie um arquivo de amostra que represente os campos que você deseja importar para o XM Discover. Consulte as páginas vinculadas acima para obter mais informações sobre os campos e formatos de arquivo obrigatórios.

Também existem arquivos de modelo disponíveis para download no conector para formatos de dados específicos:

• Chat
  • Chat (padrão): use para dados de interações digitais padrão.
  • Amazon Connect: Use para interações digitais específicas ao Amazon Connect Chat.
• Chamada
  • Chamada (padrão): utilizar para dados de transcrições de chamada padrão.
  • Verint: Use para transcrições de chamada específicas para Verint.
• Feedback
  • Dynamics 365: Use para dados do Microsoft Dynamics.

Criação de uma tarefa de conector de entrada do XM Discover Link

1. Na guia Trabalhos, clique em Novo trabalho.
   
2. Clique na tarefa Link do XM Discover.
   
3. Dê um nome ao seu job para poder identificá-lo.
   
4. Selecione o projeto para o qual os dados devem ser carregados.
5. Dê uma descrição ao seu cargo para que você saiba o seu objetivo.
6. Clique em Seguinte.
7. Escolha seu modo de autorização ou como se conectará ao XM Discover:
   
   • Chave API: conecte-se usando um token de API do XM Discover.
   • OAuth 2.0: conecte-se usando um ID de cliente e segredo do cliente fornecidos pelo serviço de autenticação do XM Discover. Entre em contato com o XM Success Manager para solicitar esse método.
8. Clique em Seguinte.
9. Escolha seu formato de dados: chat (digital), chamada ou feedback.
   
10. Se desejar, escolha um modelo e clique no link aqui para baixar o arquivo de modelo.
11. Insira o caminho JSON para um subconjunto de JSON que contém nós de documento. Deixe este campo em branco se os documentos estiverem localizados no nível do nó raiz.
12. Clique no botão Clicar para selecionar arquivo para upload e escolha o arquivo de amostra em seu computador.
13. Uma visualização do arquivo será exibida. Se você vir uma mensagem de erro ou conteúdo de arquivo bruto em vez da visualização, pode haver um problema com as opções de formato de dados que você selecionou. Consulte Erros de arquivo de amostra para obter ajuda na solução de problemas do seu arquivo.
14. Clique em Seguinte.
15. Se necessário, ajuste seus mapeamentos de dados. Consulte a página de suporte Mapeamento de dados para obter informações detalhadas sobre campos de mapeamento no XM Discover. A seção Mapeamento de dados padrão contém instruções específicas para este conector.
    
16. Clique em Seguinte.
17. Se desejar, você pode adicionar regras de substituição e ocultação de dados para ocultar dados confidenciais ou substituir automaticamente determinadas palavras e frases no feedback e nas interações do cliente. Consulte a página de suporte Substituição e redação de dados para obter mais informações.
    
18. Clique em Seguinte.
19. Se desejar, você pode adicionar um filtro de conector para filtrar os dados de entrada a fim de limitar quais dados são importados.
    
20. Clique em Seguinte.
21. Escolha como os documentos duplicados são tratados. Consulte Tratamento de duplicados para obter mais informações.
    
22. Clique em Seguinte.
23. Revise sua configuração. Se você precisar modificar uma configuração específica, clique no botão Editar para ir para essa etapa na configuração do conector.
    
24. O link Documentação da API contém seu ponto de extremidade de API, que será usado para enviar dados para o XM Discover. Consulte Acessando o ponto de acesso da API para obter mais informações.
25. Clique em Concluir para salvar sua configuração.

Mapeamento de dados padrão

Esta seção contém informações sobre os campos padrão para as vagas de Link de entrada do XM Discover.

Ao mapear seus campos, estão disponíveis os seguintes campos padrão:

• feedback_type: O tipo de feedback ajuda você a identificar dados com base em seu tipo. Isso é útil para relatórios quando seu projeto contém diferentes tipos de dados (por exemplo, pesquisas e feedback de mídias sociais). Este campo é editável. Por padrão, o valor deste atributo está definido como:
  • “chamada” para transcrições de chamadas
  • “chat” para interações digitais
  • “feedback” para feedback individual
  • Você pode usar transformações personalizadas para definir um valor personalizado.
• fonte: a fonte ajuda você a identificar dados obtidos de uma fonte específica. Isso pode ser qualquer coisa que descreva a origem dos dados, como o nome de uma pesquisa ou uma campanha de marketing móvel. Este campo é editável. Por padrão, o valor deste atributo é definido como “Link de descoberta do XM”. Você pode utilizar a transformação personalizada para definir um valor personalizado.
• richVerbatim: Este campo é usado para dados conversacionais (como transcrições de chamada e chat) e não é editável. O XM Discover usa um formato verbatim conversacional para o campo richVerbatim. Este formato suporta a ingestão de metadados específicos do diálogo necessários para desbloquear a visualização conversacional (turnos do falante, silêncio, eventos conversacionais, etc.) e enriquecimentos (hora de início, duração, etc.). Este campo literal inclui campos “filhos” para rastrear o lado do cliente e do representante da conversa:
  • clientVerbatim rastreia o lado do cliente da conversa.
  • agentVerbatim acompanha o lado do representante (agente) da conversa.
  • desconhecido rastreia o lado desconhecido da conversa.
• Qdica: Não há suporte a transformações para campos textuais conversacionais. O mesmo texto não pode ser usado para diferentes tipos de dados conversacionais. Se você quiser que seu projeto hospede vários tipos de conversa, use pares separados de conversações textuais por tipo de conversa.
• clientVerbatim: este campo é usado para dados conversacionais e é editável. Esse campo monitora o lado do cliente da conversa em interações de chamada e chat. Por padrão, este campo é mapeado para:
  • clientVerbatimChat para interações digitais.
  • clientVerbatimCall para interações de chamada.
• agentVerbatim: este campo é usado para dados conversacionais e é editável. Este campo monitora o lado do representante da conversa em interações de chamada e chat. Por padrão, este campo é mapeado para:
  • agentVerbatimChat para interações digitais.
  • agentVerbatimCall para interações de chamada.
• desconhecido: este campo é usado para dados conversacionais e é editável. Este campo rastreia o lado desconhecido da conversação nas interações de chamada e chat. Por padrão, este campo é mapeado para:
  • unknownVerbatimChat para interações digitais.
  • unknownVerbatimCall para interações de chamada.
• document_date: a data do documento é o campo de data principal associado a um documento. Esta data é usada em relatórios, tendências, alertas do XM Discover e assim por diante. Para a data do documento, selecione uma das seguintes opções:
  • conversationTimestamp (para dados conversacionais): data e hora para toda a conversação.
  • Se os dados de origem contiverem outros campos de data, você pode definir um deles como data do documento selecionando-o a partir do menu drop-down no Nome do campo.
  • Você também pode definir uma data específica adicionando um campo personalizado.
• natural_id: o ID natural serve como um identificador exclusivo de um documento e permite o processamento correto de duplicados. Para o ID natural, selecione uma das seguintes opções:
  • conversationId (para dados conversacionais): um código exclusivo para toda a conversa.
  • Selecione qualquer campo de texto ou numérico a partir de seus dados no Nome do campo.
  • Gere IDs automaticamente adicionando um campo personalizado.
• feedback_provider: O provedor de feedback ajuda você a identificar dados obtidos de um provedor específico. Para uploads do link do XM Discover, o valor deste atributo está definido como “Link do XM Discover” e não pode ser editado.
• job_name: o nome do job ajuda você a identificar dados com base no nome do job utilizado para carregar os mesmos. Você pode modificar o valor deste atributo na caixa Nome do job na parte superior da página ou usando o menu de opções de job.
• loadDate: a data de carregamento indica quando um documento foi carregado no XM Discover. Este campo é definido automaticamente e não pode ser editado.

Além dos campos acima, você também pode mapear os campos personalizados que deseja importar. Consulte a página de suporte Mapeamento de dados para obter maiores informações sobre campos personalizados.

Acessando o ponto de acesso da API

O ponto de extremidade da API é usado para carregar dados para o XM Discover enviando os dados por meio de uma solicitação da API REST no formato JSON.

Você pode acessar o ponto de extremidade a partir da página Trabalhos:

1. Selecione Resumo no menu de opções de trabalho do seu trabalho.
   
2. Clique no link Documentação API.
   
3. Clique no botão Imprimir para baixar todas as informações nesta janela como um PDF imprimível.
   
4. Suas informações de ponto de extremidade incluem:
   • URL da API: o URL usado para a solicitação de API.
   • Método: use o método POST para carregar dados no XM Discover.
   • ID do job: o ID do job selecionado atualmente.
5. Um exemplo de payload JSON está incluído na seção Corpo da solicitação. Uma solicitação de API deve conter somente 1 documento e incluir somente os campos no payload de exemplo.
6. A seção Respostas lista as possíveis respostas de êxito e erro da solicitação de API.
   
7. A seção Esquema exibe o esquema de dados. Os campos obrigatórios estão na matriz obrigatória.

Monitoramento de um job de link do XM Discover via API

Você pode monitorar o status dos jobs do XM Discover Link sem fazer login no XM Discover chamando o ponto de extremidade da API de status. Isso permite que você obtenha o último status de execução do job, métricas para uma execução de job específica ou métricas acumuladas para um período específico.

Informações do ponto de acesso de status

Para chamar o ponto de acesso de status, você precisará do seguinte:

• URL de API: https://na-data.clarabridge.net/v1/public/job/status/ <jobID> ?apiKey=<apiKey>
  • <jobId> é o ID da tarefa Link do XM Discover que você deseja monitorar.
  • <apiKey> é o token de API.
• Tipo: use o REST HTTP
• Método HTTP: use o método GET para recuperar dados.

Elementos de entrada

Os seguintes elementos de entrada opcionais podem ser utilizados para recuperar métricas adicionais sobre seu job:

• historicalRunId: o ID da sessão de upload específica. Se este elemento for omitido e nenhum intervalo de datas for fornecido, a chamada de API retorna o status de execução de job mais recente. Se esse elemento for omitido e um intervalo de datas for fornecido, a chamada da API retornará métricas acumuladas para o período especificado.
• startDate: defina a data inicial a partir da qual os dados serão retornados.
• endDate: defina a data de término para retornar dados com base no último upload. Se esse elemento for omitido e startDate for fornecida, a endDate será definida automaticamente como a data atual.

Elementos de saída

Os seguintes elementos de saída serão retornados, desde que você tenha inserido os elementos de entrada necessários:

• job_status: o status do job.
• job_failure_reason: Se o trabalho falhou, o motivo da falha.
• run_metrics: informações sobre os documentos processados pelo job. Estão incluídas as seguintes métricas:
  • SUCCESSFULLY_CREATED: o número de documentos criados com êxito.
  • SUCCESSFULLY_UPDATED: o número de documentos foi atualizado com êxito.
  • SKIPPED_AS_DUPLICATES: o número de documentos ignorados como duplicados.
  • FILTERED_OUT: o número de documentos filtrados por um filtro específico de fonte ou um filtro de conector.
  • BAD_RECORD: o número de interações digitais enviadas para processamento que não correspondem ao formato conversacional Qualtrics.
  • SKIPPED_NO_ACTION: o número de documentos ignorados como não duplicados.
  • FAILED_TO_LOAD: o número de documentos que falharam no carregamento.
  • TOTAL: o número total de documentos processados durante a execução desta tarefa.

Mensagens de erro

A seguinte mensagem de erro é possível para a solicitação de API de status:

• 401 Não autorizado: falha na autenticação. Utilize uma chave API diferente.
• 404 Não encontrado: um trabalho com o código especificado não existe. Use um código de trabalho diferente.

Solicitação de amostra

Abaixo está um exemplo de solicitação para obter o status de um job:

curl --location --request GET 'https://na-data.clarabridge.net/v1/public/job/status/62da736987c9788b830918e0?apiKey=02e7a0e26b592632dd50f623e974fff6'

Resposta de amostra

Abaixo está uma resposta de exemplo de um job falhado:
{
"job_status": "Falhou",
"job_failure_reason": "{\"problem\":[{\"request}":"RQ-MOB-f339aa58-71b6-4a1d-a67c-12b8d3439321","gravidade":"ERROR","descrição":"Limite de comprimento de 900 caracteres para o atributo supportexperienceresp:"RQ-MO
","
""lyROR","descrição":"Limite de comprimento de 900 caracteres para o atributo supportexperienceresp: {1\\ métricas_
", "

""is 1043", "1043","
"


Exemplos de payload

Esta seção contém 1 payload JSON de exemplo para cada tipo suportado de dados estruturados (feedback, chat, chamada).

Clique aqui para visualizar o payload de exemplo de feedback.

curl --location --request POST 'https://na-data.clarabridge.net/v1/cb_link?apiKey=887fc11663c456f9f34844a8a8bdff64&jobId=5f4e583f9142ae48a1090a76' \
--header 'Content-Type: application/json' \
--data-raw '{dataSource
": "Standard JSON",
"Row_ID": "id43682",

"store_number": "out1,1,0,0",

"Mariw_ID": "5916

Loop 289" Continue o bom trabalho.",
"LTR": 10,
"state": "TX",
"Rewards_Member": "MyBestBuy"
}'

Clique aqui para visualizar o payload de exemplo de chat.

curl --location --request POST 'https://na-data.clarabridge.net/v1/cb_link?apiKey=887fc11663c456f9f34844a8a8bdff64
&jobId=5f4d77656afa99b0396ef959' \
- ]-header 'Hello Content-Type
: application/json' \
--data-raw '{
"conversationId": "37854",
"conversationTimestamp": "2020-07-30T12:42:15.000Z",
"content": {participantType": "CHENT AT",

"

" "participant" "participants":

,
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785201"
},
{
"participantId": "2",
"text": "Oi, você está aberto hoje?",
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785202"
},
"participantId": "1",
"text": "We are open from 17:00 till 23:00.",
"timestamp": "2020-07-30T12:42:15.000Z": "We are open from 17:00 till "make": "3720-07-30T12:42:15.000Z":
"make" "37an": "3720-07-30T12:42: {15.000Z": "We are open from 17:00 till 23:00.",
"timestamp": "2020-07-30T12:}: {15.000Z": "We are open from 17:00 till 23:00.",
"timestamp": "2020-07-30T12:} } {15.000Z":
"make" "37id": "3720-07-30T12
:42":
"
:

" Que nome posso usar?",
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785205"
}
]
},
"city": "Boston",
"source": "Facebook"
}'

Clique aqui para visualizar o payload de exemplo de chamada.

curl --location --request POST 'https://na-data.clarabridge.net/v1/cb_link?apiKey=887fc11663c456f9f34844a8a8bdff64&jobId=5f4e564d9242ae6e6308ff04' \

--header 'Content-Type: application/json' \
--data-raw '{
"conversationId": "462896",}
"contentType" {
ENT Timestamp": "2020-07-30T10:15:45.000Z",
"content", {
"contentType" {ENT,CALL
",

"

" "participant" "participant" "participant" "participant": "

" "participant",
"start": 22000,
"end": 32000
},
{
"participant_id": "2",
"text": "Oi, eu tenho algumas perguntas.",
"start": 32000,
"end": 42000

"contentSegmentType": "TURN"
},
"city": "Boston",
"Call SegmentType": "TURN"},"city": "Boston",
"Boston",